exploring-llm-costs

LLM のコストを調べる

PostHog は、取り込み時にすべての $ai_generation イベントと $ai_embedding イベントに、呼び出しごとのコストメタデータを付与します。コストに関する質問はすべて、 この2種類のイベントを集計すれば解決できます。違いが生じるのは、グループ化、フィルタリング、 比較の方法だけです。

このスキルでは、一般的なコスト調査を取り上げます。合計支出、内訳 （モデル、プロバイダー、ユーザー、トレース、カスタムプロパティ）、トークンとキャッシュヒットの分析、 回帰のデバッグ、インサイト、ダッシュボード、アラートへの結果の反映などです。

ツール

ツール	目的
posthog:query-trends	対応している合計、内訳、比較を使ったネイティブのコスト推移
posthog:execute-sql	あらゆるコスト集計に使えるアドホックな HogQL — このスキルの主力ツール
posthog:query-llm-traces-list	コスト、トークン、エラーの集計指標を含むトレースの一覧
posthog:query-llm-trace	単一のトレースに含まれるすべてのイベントのコスト内訳
posthog:read-data-schema	内訳に使えるカスタムプロパティを確認
posthog:insight-create	コストチャートを保存済みインサイトとして反映
posthog:dashboard-create	コストインサイトをダッシュボードにまとめる
posthog:alert-create	コストがしきい値を超えたときにアラートを送信
posthog:generate-app-url	リージョンとプロジェクトを指定した UI へのリンクを作成

基本ルール

問題の大半は、次の3つのルールで防げます。

• 集計では $ai_total_cost_usd を合計し、内訳の値は決して合計しないでください。 内訳の値では、 リクエスト料金とウェブ検索料金が除外されます。UI のコスト欄は event IN ('$ai_generation', '$ai_embedding') に含まれるイベントの $ai_total_cost_usd を合計します。同じ方法を使ってください。スキーマ全体と理由については、 コストプロパティを参照してください。
• プロジェクトで埋め込みが使われていないことが明らかでない限り、コストクエリには必ず $ai_generation と $ai_embedding の両方を含めてください。 含めないと、気付かないうちに 過少集計になります。$ai_trace と $ai_span には集計対象のコストがありません。一部の SDK ラッパーは $ai_total_cost_usd を $ai_trace にも重複して記録するため、集計に含めると 二重計上になります。
• 必ず期間を指定してください。 期間の指定がないコストクエリは、イベントテーブル全体をスキャンします。

$ai_total_cost_usd は、取り込み時に3つの方法（パススルー、カスタム料金設定、自動検索）の いずれかで設定されます。コストの値に問題がある場合は、まず $ai_cost_model_source を確認してください。優先順位のルールと診断クエリについては、 コストのソースを参照してください。

キャッシュヒットの計算方法は、プロバイダーがキャッシュトークンを $ai_input_tokens に含めて報告するか、含めずに報告するかによって異なります。必ずプロバイダー名ではなく、 イベントごとの $ai_cache_reporting_exclusive フラグに基づいて分岐してください。排他的と包括的の 計算式については、キャッシュの計上を参照してください。

distinct_id は、ユーザーを表す標準的なディメンションです。顧客はカスタムプロパティ （feature、tenant_id、workflow_name）を追加することがよくあります。グループ化する前に、 posthog:read-data-schema でプロパティを確認してください。名前を推測してはいけません。

ワークフロー：期間内の合計支出

posthog:execute-sql
SELECT round(sum(toFloat(properties.$ai_total_cost_usd)), 4) AS total_cost_usd
FROM events
WHERE event IN ('$ai_generation', '$ai_embedding')
    AND timestamp >= now() - INTERVAL 30 DAY

ワークフロー：コストの内訳

コストに関する質問はすべて、ディメンションでグループ化し、 $ai_total_cost_usd を集計するという同じテンプレートの応用です。実行可能なレシピについては、 内訳のパターンを参照してください。

• 時系列でのコスト（日次）
• モデル別のコスト
• ユーザー別のコスト（支出上位）
• トレース別のコスト（高コストのトレース上位）
• カスタムディメンション別のコスト
• 呼び出しあたりのコスト分布
• 入力、出力、キャッシュのコスト分析

ワークフロー：単一のトレースのコストを確認する

ユーザーがトレースの URL を貼り付けてコストについて尋ねた場合は、トレースを取得し、イベントごとの内訳を示します。

posthog:query-llm-trace
{ "traceId": "<trace_id>", "dateRange": {"date_from": "-30d"} }

返されたイベントの $ai_total_cost_usd をスパン名またはモデルごとに合計し、コストを押し上げたステップを示します。トレースのレスポンスには、利便性のため totalCost も含まれています。

ワークフロー：コストの回帰をデバッグする

「LLM の請求額が急増したのはなぜ？」という場合、原因はほぼ必ず、呼び出しの増加、プロンプトの肥大化、新しいモデル、またはキャッシュヒット率の変化のいずれかです。順番に確認してください。5 ステップの手順については、回帰のデバッグを参照してください。

ワークフロー：インサイト、ダッシュボード、アラートとして保存する

その場でのクエリで疑問が解決したら、インサイトとして保存するか、ダッシュボードにまとめるか、アラートを設定します。posthog:insight-create、posthog:dashboard-create、posthog:alert-create ですぐに実行できる JSON については、保存方法を参照してください。

UI リンクの作成

https://app.posthog.com/... のリンクを手書きしないでください。このホストではリージョンとプロジェクトのプレフィックスが失われるため、意図したページではなくログイン画面にリダイレクトされます。

• ツールから返される正規 URL を優先してください。 query-llm-traces-list と query-llm-trace は _posthogUrl を返します。この値を提示してください。単一のトレースの場合は、その URL に ?timestamp=<url_encoded_iso>（トレースの最も早いイベント時刻）を付けてください。返されるリンクにはタイムスタンプが含まれていません。タイムスタンプがない場合、トレースページはトレースの前後 10 分ではなく、固定の過去の日付から検索します。
• それ以外の場合は、generate-app-url でリンクを作成してください。 リージョンに対応するホストと /project/<id>/ プレフィックスが解決されます（例：https://us.posthog.com/project/2/ai-observability/traces）。具体的な ID はパスに直接埋め込まず、params で渡してください。
  • ダッシュボード：generate-app-url {url: "/ai-observability/dashboard"}
  • トレース一覧（コスト順）：generate-app-url {url: "/ai-observability/traces"}
  • 生成一覧：generate-app-url {url: "/ai-observability/generations"}
  • ユーザー一覧（ユーザーごとのコスト）：generate-app-url {url: "/ai-observability/users"}
  • 単一のトレース：generate-app-url {url: "/ai-observability/traces/{id}", params: {id: "<trace_id>"}}

generate-app-url ではクエリパラメーターを指定できないため、上記の ?timestamp=<url_encoded_iso> を単一トレースのリンクに自分で追加してください。

ユーザーが視覚的に確認できるよう、必ず UI リンクを提示してください。

このスキルを最新の状態に保つ

プロバイダーによるレポートの動作（どのトークンが包含されるか、どのトークンが除外されるか、どこにどのコストが表示されるか）は、時間とともに変化し、同じプロバイダーでも SDK のバージョンによって異なる場合があります。情報の陳腐化を防ぐには、次の点に従ってください。

• ハードコードされたプロバイダー名やモデル名ではなく、イベントレベルのフラグ（$ai_cache_reporting_exclusive、$ai_cost_model_source）を基準に分岐してください。これらのフラグは、取り込み処理が個々のイベントについて判定した結果であり、信頼できる情報源です。
• ロールアップには常に $ai_total_cost_usd を使用してください。新しいコストカテゴリが追加されると変動する可能性があるため、各コンポーネントの合計よりもこちらを優先してください。
• ここで扱っていない内容（新しいコストカテゴリ、価格参照の変更、プロバイダーの追加）については、このファイルにハードコードされたルールを信頼せず、まず posthog:docs-search で「calculating costs」または「AI observability」を検索してください。
• このスキルの内容が UI と矛盾する場合は UI を信頼し、このスキルの更新が必要であることを報告してください。

ヒント

• 常に期間を指定してください。期間を指定しないコストクエリは、イベントテーブル全体をスキャンします
• トークン、コスト、モデル、$ai_trace_id のプロパティは events にありますが、メッセージの 内容（$ai_input ／ $ai_output_choices）は posthog.ai_events テーブルにのみ存在します。コストと一緒に内容を確認する必要がある場合は、exploring-llm-traces スキルを読み込んでください
• コストを合計するときは、常に $ai_generation とともに $ai_embedding も含めてください。埋め込みの1回あたりのコストは低くても、大規模になると積み上がります
• コストは取り込み時に書き込まれます（LLM コストの計算を参照）。$ai_total_cost_usd が欠損またはゼロの場合は、まず $ai_cost_model_source を確認してください。passthrough は SDK がコストを提供したことを意味し、custom はカスタムトークン価格、openrouter ／ manual は自動検索を意味します。欠損している場合は、モデルが一致しなかったことを意味します（一般的でないカスタムモデル、ファインチューニング済みモデルなど）。Grep：(model, source) ごとの countIf(properties.$ai_total_cost_usd IS NULL)
• カスタム価格では、100万トークンあたりではなく トークンあたり の価格を使用します。カスタム価格のモデルが約100万倍高すぎる、または安すぎる場合、ほぼ間違いなくこれが原因です
• 明示的に求められた場合を除き、コスト合計からエラーになった呼び出しを除外しないでください。プロバイダーは多くのエラーモードでも料金を請求するため、含めたほうが実際の請求額を正確に把握できます
• ユーザーごとの合計では、distinct_id = properties.$ai_trace_id の行を除外してください。ユーザーが設定されていない場合、一部の SDK は distinct_id をトレース ID にデフォルト設定します
• コストは、トレース内の $ai_generation イベントと $ai_embedding イベントで加算されます。$ai_span を合計してもゼロになります。一部の SDK ラッパーでは $ai_trace に $ai_total_cost_usd が含まれることがありますが、ロールアップには含めないでください。二重計上になります。$ai_evaluation イベントにもコストは含まれますが、標準の UI ロールアップには含まれません。ユーザーが合計に評価のコストも明示的に含めるよう求めた場合のみ追加してください
• キャッシュヒット率は $ai_cache_reporting_exclusive によって決まります。プロバイダー名やモデル名ではなく、イベントレベルのフラグに基づいて分岐してください。プロバイダーの動作や SDK のバージョンは変わるため、この特定のイベントについて取り込み時に解決された答えを示すのがこのフラグです
• 「X のコストが高い理由は？」と尋ねられたら、コスト と トークンの内訳を示してください。ユーザーはほとんどの場合、プロンプトを短くすべきか、出力を短くすべきか、モデルを切り替えるべきかを知りたいと考えています
• カスタムダッシュボードを作成する前に、標準の /ai-observability/dashboard タイルで質問に回答できないか確認してください。作り直すのは無駄な作業です
• 大規模なテナントでは、よく使うコストクエリをインサイトとしてマテリアライズし、insight-query で再利用してください。単発の用途ならアドホック SQL でも問題ありませんが、ダッシュボードの読み込みごとに再実行するとコストがかかります

参考資料

• コストプロパティ — プロパティの完全なスキーマ、合計コストの根拠、イベントセットのルール
• コストのソース — 取り込み時にコストが設定される仕組みと、診断クエリ
• キャッシュの計上 — 排他的プロバイダーと包括的プロバイダー、キャッシュヒット率の計算式
• 内訳のパターン — 一般的な内訳ごとの SQL レシピ
• 回帰のデバッグ — コスト急増に対処する5段階の手順
• マテリアライズ — インサイト、ダッシュボード、アラートの JSON

関連スキル

• analyzing-expensive-users — 誰がコストを押し上げているのか、その利用パターンが原因かどうかを確認します
• exploring-llm-traces — 内訳から判明したコストの高いトレースを調査します