Yabanin — オフラインの支出監査 (yb audit)
yb audit は、自己完結した オフライン のコスト分析ツールです。顧客自身の LLM リクエストログを指定すると、記録された利用量と同梱の価格から推定支出を報告し、そのトラフィックに対してセマンティックキャッシュとティア経路がどれだけ節約できたかを示します。ゲートウェイも、管理 URL も、API キーも、組織も不要で、ネットワーク呼び出しも行いません。単一のバイナリが、ローカルファイル(または標準入力)に対して実行します。
分析ツールは、構造上正直です。すべて の金額は入力行または価格表まで追跡でき、派生した数値にはすべて実測または推定のラベルが付き、条件付きの投影(キャッシュの同等性、経路の許容性)には明示的な注意書きが付きます。サンプルが信頼できるには小さすぎる場合、レポートは精度を装わず、バナーでその旨を示します。
クイックスタート: クリーンなチェックアウト → HTML レポート
このツリーでエンドツーエンドに検証済みです(2026-09-13)。
# 1. Build the operator CLI (contains `yb audit`).
go build -o bin/yb ./cmd/yb
# 2. Run it against the bundled synthetic traffic fixture…
bin/yb audit datasets/audit/sample_traffic.jsonl \
--format html --output /tmp/my-report.html
# 3. …or against your own export (JSONL, one request per line):
bin/yb audit your-traffic.jsonl --format html --output your-report.html
期待される結果は、自己完結した HTML ファイル(JS/CDN/ネットワークなしで開きます)です。モデルごとの支出、キャッシュと経路の投影が含まれます。不明なモデル価格は不明として表示され、ゼロにはなりません。不正な入力行はカウントされて報告されます(何も解析できなかった場合、コマンドは失敗します)。
使い方
# Markdown report (default) to stdout
yb audit path/to/traffic.jsonl
# JSON
yb audit path/to/traffic.jsonl --format json
# Self-contained HTML (no CDN, no JS) to a file
yb audit path/to/traffic.jsonl --format html --output report.html
# Exact mode is the supported offline default.
# Semantic simulation is a library capability; the CLI has no embedder wiring.
# Share the report without leaking prompt content
yb audit path/to/traffic.jsonl --no-prompts
# Read from stdin
cat traffic.jsonl | yb audit -
フラグ:
| フラグ | デフォルト | 意味 |
|---|---|---|
--format, -f | md | md、json、または html |
--cache-mode | exact | exact、semantic、または off |
--output, -o | (標準出力) | レポートをこのファイルに書き出します |
--max-records | 5,000,000 | 取り込むレコード数の上限 |
--no-prompts | false | ハッシュ化のあと、生のプロンプトテキストを破棄します |
--provider | (推論) | ファイル全体のプロバイダ推論を上書きします |
無効な --format または --cache-mode は拒否され、黙ってデフォルトになることはありません。
入力形式
取り込みは形式を自動検出します。スニッフィングに頼ることもできます。
- OpenAI 形式の JSONL — 1 行につき 1 つの JSON オブジェクトです。フラットな形(
model、usage.prompt_tokens、usage.completion_tokens、messages、任意のtimestamp、status_code、duration_ms)か、ラップされた形({"request": {...}, "response": {...}})のいずれかです。 - CSV — ヘッダ駆動です。列名がフィールドに対応付けられます。
- このゲートウェイの形式 — Yabanin 自身のロガーが出力する JSONL/CSV です。
不正な行はカウントされてスキップされ、致命的にはなりません。シンボリックリンクされた入力は報告され、黙ってたどられることはありません。トークン数が欠落している場合は、固定の 4 文字/トークンでテキスト長から推定され、レポートはカウントが推定された行の割合を開示します。
6 つのセクション
- 概要 — リクエスト数、合計コスト(入力/出力の内訳)、価格未設定のリクエスト(すべての金額合計から除外され、$0 として価格付けされることはありません)、期間、上位モデル、上位プロバイダ。
- 判明した内容 — 実測された所見です。支出の集中(p50/p90/p99 + 上位 1%/10% のシェア)、繰り返されるプレフィックスの肥大、上位プロンプトクラスタ、リトライストーム、エラーによる浪費、max_tokens の過剰確保、テールレイテンシ、モデル構成のドリフト。しきい値を超えた所見だけが列挙され、形容詞で水増しされることはありません。
- キャッシュシミュレーション — ヒット率、回避されたトークン、回避された金額、モデルごとのヒット率。
semanticモードでは、セマンティックヒットは類似一致であり、検証済みの同等の回答ではないという注意書きが付きます。 - 経路シミュレーション — プロセス内のルールティア分類器によるクラス分布(easy/medium/hard)、経路のみの節約、ミス時経路の節約、および重複を明示した合算値。
- データ品質 — 解析済み/スキップの件数、実際のトークン数を持つ割合、タイムスタンプを持つ割合、価格未設定のリクエスト数、価格未設定のモデル名。
- 推奨事項 — 発火したすべてのルールを、それを引き起こした数値に紐づけて原文のまま示します。所見がデータに含まれない限り、推奨事項は出力されません。
キャッシュと経路: 本番と同じ順序、二重計上なし
合算の節約額は、ゲートウェイが本番で適用するのと同じ順序で、2 つの最適化を適用します。まずキャッシュ、経路はキャッシュミスのみ。 読者が二重計上できないよう、レポートは 3 つの数値を示します。
- キャッシュのみ — キャッシュ単体で回避できた金額。
- 経路のみ — すべての リクエストを経路付けした場合に、ティア経路が節約できた金額。
- 合算 — キャッシュのみ + ミス時経路。重複(経路のみ − ミス時経路)は、キャッシュと経路を単純に足した場合に二重計上される金額であり、明示されます。
ターゲットモデルに既知の価格がない場合(破棄されてカウントされます)、ターゲットが元のモデルと等しい場合、またはターゲットの方が安く ない場合、リクエストが経路の節約に寄与することはありません。不明なモデルが黙って $0 として価格付けされることはありません。
キャッシュモード
exact(デフォルト) — 本番のプロンプトハッシュをキーにします。依存関係はなく、完全にオフラインで、ネットワークも使いません。semantic— ライブラリのシミュレータは、注入されたEmbedFuncを必要とします。CLI はエンベッダを配線しておらず、このモードを明示的に拒否します。エンベッダサービスを起動するだけでは、有効になりません。off— シミュレーションをスキップします。このとき、ミス時経路は全件経路と等しくなります。
決定性
与えられた入力とモードに対して、レポートは 実行ごとにバイト単位で同一 です。例外は 1 つで、タイムスタンプを含む generated 行です。それ以外、つまりすべての表、すべての数値、JSON のフィールド順(構造体の宣言順、キーでソートされたマップ)は安定しています。これにより、レポートを diff し、アーカイブし、顧客に渡しても安全です。
サ ンプル不足
入力のリクエストが 50 未満、または期間が 24 時間未満(期間がまったくない場合を含む)のとき、レポートには厳格な サンプル不足 バナーが付きます。バナーはサンプルについての事実であり、提案ではありません。数値は引き続き表示されますが、統計的に信頼できないことが示されます。
例
サンプルのリクエストログと、そこから生成されたレポートは datasets/audit/ にあります。
yb audit datasets/audit/sample_traffic.jsonl --format md
# or open the pre-generated HTML:
open datasets/audit/sample_report.html
サンプルは決定的な 600 リクエストのログです(繰り返されるシステムプロンプト、easy/medium/hard のワークロードの混在、リトライ、エラー、価格未設定の内部モデル)。すべてのセクションを実行します。
行わないこと
exactモードでは、モデル、ゲートウェイ、いかなるネットワークサービスも呼び出しません。- 入力ファイルを変更しません。
- キャッシュされた回答が新規の回答と同等であることを検証しようとはしません(それはキャッシュアーキテクチャ上の判断です)。ヒット率と注意書きを報告します。
- 不明なモデルを $0 として価格付けしたり、価格表で裏付けられない節約を主張したりしません。
クリーンなチェックアウトからの最初のレポート
ルートの go.mod に宣言された Go のバージョンをインストールします(現在は Go 1.27.1、または互換性のあるより新しいツールチェーンです)。リポジトリのルートから、次を実行します。
go build -o /tmp/yabanin-audit ./cmd/yabanin
/tmp/yabanin-audit audit datasets/audit/sample_traffic.jsonl \
--cache-mode exact --format html --no-prompts \
--output /tmp/yabanin-sample-report.html
ブラウザで /tmp/yabanin-sample-report.html を開きます。同梱の 600 リクエストのフィクスチャは合成データであり、顧客の証拠ではありません。合成サンプルレポートを見る。監査にゲートウェイ、プロバイダのキー、Redis、データベースは不要です。ソースからビルドすると、Go モジュールをダウンロードする場合があります。得られる exact の監査自体はオフラインです。
レポートは、同梱の価格ソースとその SHA-256 フィンガープリントを示します。元のアップストリームの検証日は記録されておらず、不明として表示されます。 これらは利用量に基づく定価の推定です。キャッシュされた入力の割引、交渉済みレート、サービスティアは、プロバイダの請求書と照合されません。不明なモデル価格は除外されたままで、無料として数えられません。
無効な形式と、未配線のセマンティックモードは、エラーで終了します。入力行がすべて無効な場合、コマンドは失敗します。それ以外の場合、解析の失敗はデータ品質に表示されます。欠落したトークン利用量は、推定されて開示されることがあります。--no-prompts は、ハッシュ化のあと生のプロンプトテキストを破棄します。ソースパス、モデル名、タイムスタンプ、派生した所見は、依然としてワークロードを識別できます。共有する前に、エクスポート全体を確認してください。プロンプトを破棄すると、プロンプトに基づく分類に使える情報も減ります。経路の投影は、それに応じて解釈してください。
公開例を正確に再現するには、同じコマンドに --output web/site/static/examples/audit-sample.html を指定します。公開用のコピーには、明確に示された合成データのバナーが追加されます。生成されるタイムスタンプは実行ごとに変わります。基礎となる数値はすべて、同じソースと同じバイナリによる新しい実行と一致する必要があります。