AI 使用状況分析 API により、開発者はプログラムによる方法で、通常のプロバイダのダッシュボードでは完全には答えられない質問に答えることができます。つまり、どの API キー、モデル、顧客、ワークフロー、機能、またはチームが使用量とコストを引き起こしたか?顧客またはプロジェクトにいくら割り当てるべきですか?どのレコードを倉庫、ダッシュボード、財務システム、または再販業者ポータルにエクスポートできますか?また、その数字はプロバイダのコスト API、ゲートウェイの記録、支払い記録、請求書と一致していますか?
単一のプロトタイプの場合、プロバイダのダッシュボードで十分な場合があります。複数の LLM、ホストされたツール、ストリーミング応答、画像または音声エンドポイント、バッチ ジョブ、および顧客固有の API キーを使用する運用アプリケーションの場合、使用状況レポートはデータ製品になります。安定した識別子、正規化された使用量単位、価格コンテキスト、アクセス制御、エクスポート セマンティクス、分析データと請求の真実の間の明確な境界が必要です。
このガイドでは、AI 使用状況分析 API が何を明らかにすべきか、ダッシュボード、請求書、オブザーバビリティ トレース、請求元帳との違い、LLM コスト分析、AI API 使用状況エクスポート、モデル別の支出分析用に設計する方法について説明します。チャージバック。 Model Gate は、統合請求、API キー管理、使用状況分析、チーム管理、Telegram 統合、およびゲートウェイ上にサービスを構築するためのパートナー API を備えた OpenAI 互換のマルチモデル API ゲートウェイであるため、このワークフローに関連します。アプリケーションとモデル プロバイダーの間にゲートウェイがすでに配置されている場合、ゲートウェイはアトリビューションと正規化された使用状況データの重要なソースになる可能性があります。
AI 使用状況分析 API とは
AI 使用状況分析 API は、AI 使用状況データのクエリとエクスポートのための読み取り指向のインターフェイスです。通常、時間、モデル、プロバイダー、エンドポイント、API キー、ユーザー、チーム、顧客、テナント、プロジェクト、ワークフロー、環境、リージョン、サービス層、使用タイプなど、複数の側面にわたる質問に答えます。
API は、生のリクエスト レコード、集計概要、またはその両方を公開する場合があります。リクエスト レベルのレコードには、1 つのチャットの完了、画像の生成、埋め込み呼び出し、文字起こし、ファイル検索の呼び出し、またはホストされたツール セッションが記述される場合があります。集約エンドポイントは、合計入力トークン、出力トークン、キャッシュされたトークン、リクエスト、エラー、画像、音声秒数、または日別およびモデル別の推定コストを要約する場合があります。
最も有用なシステムは、使用単位を金額から分離します。トークン、画像、音声秒、ベクトル ストレージ バイト、コード インタープリター セッション、ツール呼び出し、ファイル検索呼び出し、および Web 検索呼び出しはすべて、異なる請求セマンティクスを伝えることができます。コスト レポートでは、価格カタログ、通貨、割引またはマークアップ ポリシー、請求期間、および決済状態がそれらの使用単位に適用されます。
ダッシュボード、請求書、トレースだけでは不十分な理由
ダッシュボードは人間向けに最適化されています。検査や傾向の発見には役立ちますが、自動化には十分であることはほとんどありません。ダッシュボードは、顧客の割り当てに必要なすべてのディメンションを公開していない場合があり、固定グループを使用している場合があり、独自の倉庫にリプレイセーフにエクスポートできるように設計されていない場合があります。
請求書は、支払いと法的会計のために最適化されています。それはあなたが借りているものについては権威があるかもしれませんが、多くの場合、アプリケーションレベルの詳細が欠けています。請求書に先月のプロバイダー モデルの費用が 742 ドルと記載されている場合、どの顧客、API キー、機能、環境、またはワークフローが支出の原因となったかが示されていない可能性があります。
オブザーバビリティ トレースは、デバッグと遅延分析用に最適化されています。モデル呼び出し、スパン、トークン数、エラーをキャプチャできますが、自動的に請求レコードにはなりません。たとえば、OpenTelemetry GenAI の規則では、請求されたトークンの数とモデルで消費されたトークンの数を区別し、両方が利用可能な場合には請求されたトークンの数を報告することを推奨しています。コスト配分に使用される分析は、内部実行の詳細だけでなく料金とも一致する必要があるため、この区別は重要です。
請求元帳は財務状態に合わせて最適化されています。クレジット、借方、支払い、残高、請求書、調整、税金、割引、返金、再販業者のマージンが記録されます。使用状況分析 API は請求元帳にフィードできますが、請求元帳と混同しないでください。分析は消費を説明します。
LLM コスト分析の中核となるデータ モデル
永続的な LLM コスト分析 API は、リクエスト レベルの使用量台帳から始まります。ほとんどのユーザーが集計をクエリする場合でも、リクエスト レコードには、調整、チャージバック、インシデントのレビューに必要な属性とライフサイクルの詳細が保存されます。
ID フィールドと属性フィールド
各使用状況レコードには、再試行、エクスポート、システム移行後も存続する安定した識別子が含まれている必要があります。共通フィールドには、リクエスト ID、プロバイダ リクエスト ID (使用可能な場合)、ゲートウェイ リクエスト ID、API キー ID、アカウント ID、チーム ID、ユーザー ID、顧客またはテナント ID、プロジェクト ID、ワークフロー ID、環境、相関 ID が含まれます。
最も重要な設計上の選択は、どのアクターがコストを所有するかを決定することです。 API キーの帰属はシンプルであり、多くの場合、個々のビルダー、代理店、内部チームにとってはうまく機能します。顧客レベルのチャージバックには、より強力な ID 伝播が必要です。ワークフロー レベルのユニット エコノミクスには、アプリケーション層からの一貫したタグ付けが必要です。タグ付け規律がなければ、分析 API は実際に受信したものによってのみグループ化できます。
キーベースのアトリビューションの場合、分析は API - キー管理と支出レポートが一緒に設計されている場合に最適に機能します。キーレベルの ID をサポートするゲートウェイを使用すると、使用状況分析を LLM API キー別の支出制限 、割り当ての適用、顧客ごとのレポートなどの制御と簡単に接続できます。
モデル、プロバイダー、およびエンドポイントのフィールド
モデル分析では、パブリック モデルのエイリアスと解決されたプロバイダー モデルの両方を保持する必要があります。製品は高速チャット モデルなどの汎用エイリアスを呼び出すことができますが、ゲートウェイは価格、可用性、またはポリシー上の理由から特定のプロバイダー モデルにルーティングします。分析レコードにエイリアスのみが保持されている場合、後の請求書の調整が困難になります。プロバイダー モデルのみを保持する場合、製品レベルの分析は難しくなります。
役立つレコードには、プロバイダー、エンドポイント、モデル エイリアス、解決されたモデル、モデル バージョン (利用可能な場合)、モダリティ、リージョン、サービス レベル、ルート ポリシー、フォールバック状態、通話でストリーミング、バッチ、非同期処理、ホストされたツール、またはマルチモーダル入力が使用されたかどうかが含まれます。
使用量単位フィールド
AI の使用量を削減しないでください。単一のトークンカウンターに。成熟した分析スキーマでは、単位が重要な場合、入力トークン、出力トークン、キャッシュされた入力トークン、キャッシュ書き込みトークン、推論トークン、埋め込みトークン、画像数、画像サイズ、音声秒数、ビデオ秒数、ファイル検索呼び出し、Web 検索呼び出し、ベクトル ストレージ バイト、コード実行セッション、およびバッチ項目を分離します。
プロバイダー ネイティブ API は、なぜこの範囲が必要であるかをすでに示しています。 OpenAI は、プロジェクト、ユーザー、API キー、モデル、ラインアイテム、API ソース、モダリティ固有の使用状況などのディメンションにわたる組織の使用状況とコストのレポートを公開します。 Anthropic は、モデル、API キー ID、ワークスペース ID、サービス層、コンテキスト ウィンドウ、推論地理、速度などのフィルターとグループを使用して、使用状況とコストのレポートを文書化します。クラウド請求のエクスポートでは、SKU、プロジェクト、予約、リソースのメタデータの別のレイヤーを追加できます。クロスプロバイダー分析 API では、プロバイダー固有の詳細を破棄することなく、共通フィールドを正規化する必要があります。
コスト フィールド
コスト フィールドでは、ステータスと計算について明示的に示す必要があります。推定コスト、決済コスト、請求コスト、通貨、価格カタログのバージョン、マークアップまたは割引ポリシー、請求期間、決済タイムスタンプとは別に使用単位を保存します。Money には、浮動小数点値ではなく、10 進数文字列または固定精度小数点を使用する必要があります。
これにより、プロバイダが価格を更新したときに履歴レポートの意味が変わるのを防ぐことができます。また、リアルタイムの予算決定が最終的な請求書と異なる理由も説明できます。ストリーミング応答が早期に終了したり、ツール呼び出しによって最初の応答後に使用量が追加されたり、再試行によってアプリケーションが予期しなかったプロバイダー側のコストが発生したりする場合があります。
集約 API と詳細エクスポート
AI 使用状況分析 API には、通常、集約エンドポイントと詳細エクスポートという 2 つの面が必要です。
集約エンドポイントは、ダッシュボードと迅速な意思決定用に最適化されています。過去 30 日間のモデル別の合計コスト、API キー別の毎日のトークン、エンドポイント別のエラー率、今週の顧客別の支出などの質問に答えます。これらは、カーディナリティが高い一般的なグループ化ディメンション、日付バケット、フィルタ、ページネーションをサポートする必要があります。
詳細エクスポートは、ウェアハウス、チャージバック、監査、調整用に最適化されています。これらは、安定した順序付け、不変のイベント ID、カーソル、updated_at ウォーターマーク、リプレイセーフなページネーションを備えた行レベルまたはリクエスト レベルのデータを提供します。適切な AI API 使用状況のエクスポートは、重複請求や修正の欠落を発生させることなく繰り返し取り込むことができます。
2 つのサーフェスは一致する必要がありますが、同じストレージ パスでバックアップされている必要はありません。速度を上げるために、集計は事前計算されたロールアップから取得される場合があります。完全を期すために、エクスポートは追加専用の台帳または分析ウェアハウスから読み取ることができます。重要なのは、タイムゾーン、バケットの境界、ステータスの包含、遅れて到着するレコード、通貨、コストが見積もられるか決済されるかなどのセマンティクスが文書化されていることです。
モデル別の使用状況分析
モデル別の AI 支出分析は、チームが最初に求めるレポートの 1 つですが、不適切に実装されやすいです。モデルのみのレポートでは、1 つのプロバイダー モデルが高価であることが示されますが、単一のワークフロー、テナント、または API キーが原因であるという事実が隠蔽される可能性があります。
モデルレベルのレポートでは、少なくとも 3 つのビューをサポートする必要があります。まず、製品エイリアスを表示して、ビルダーがどのアプリケーション構成が使用を促進しているかを理解できるようにします。次に、財務部門とエンジニアリング部門がプロバイダー料金を調整できるように、解決されたプロバイダー モデルを示します。 3 番目に、移行、フォールバック、ルーティング ポリシーによって数字が曖昧にならないように、時間の経過に伴うモデルの変化を表示します。
マルチモデル アプリケーションの場合、ここでゲートウェイ データが特に役立ちます。 Model Gate の OpenAI 互換マルチモデル ゲートウェイ設計により、プロバイダーの来歴を維持しながら、使用をゲートウェイ レベルの API キーとモデル ルーティング コンテキストに関連付けることができます。また、その統合請求機能により、分析の議論が 統合 AI API 請求に隣接して行われます。この場合、複数のモデル プロバイダーは、より集中化された商用レイヤーを通じて支払いが行われます。
チャージバックとショーバックの使用状況データ
チャージバックの AI 使用状況データは、コストを原因となった顧客、チーム、プロジェクト、再販業者、機能、またはコスト センターに割り当てます。 Showback は資金を回収せずに割り当てを報告します。通常、チャージバックにより、実際の請求書、内部送金、顧客残高、または販売代理店の明細書が作成されます。
中核となる要件は、割り当ての忠実度です。アプリケーションが 1 つのバックエンド キーを通じて複数の顧客にサービスを提供する場合、API キーによるプロバイダーのレポートだけでは十分ではありません。顧客またはテナントの識別子をゲートウェイ、台帳、または分析パイプラインに渡す必要があります。機能レベルの収益性が必要な場合は、ワークフローまたは機能タグが必要です。エンドユーザーのレポートが必要な場合は、ユーザー ID と、ユーザー ID をクエリできるプライバシー モデルが必要です。
財務に配慮したエクスポートでは、多くの場合、AI の使用状況が顧客、製品、環境、所有者、ワークロード、地域、コスト センター、請求期間、ユニット エコノミクス指標などの割り当て列にマッピングされます。FinOps オープン コストと使用量の仕様は、割り当て、ベンチマーク、予算編成、予測、および関連する実践のためのコストと使用量のデータセットを定義しているため、参照点として役立ちます。 AI ワークロードには、モデル、トークン、キャッシュ動作、ツール、モダリティの拡張フィールドが引き続き必要です。
パートナーと再販者のシナリオでは、別のレイヤーが追加されます。ゲートウェイ上に構築されたサービスでは、上流のプロバイダーの詳細を内部的に保持しながら、下流の顧客に使用状況を公開する必要がある場合があります。このような場合、分析エクスポートと パートナー API 自動化は、再販業者のステートメント、顧客ダッシュボード、運用レポートが変動しないように、同じ ID と割り当てモデルを共有する必要があります。
プロバイダー ネイティブ API、ゲートウェイ台帳、ウェアハウス
AI 使用状況データには 4 つの一般的なソースがあり、それぞれにトレードオフがあります。
プロバイダー ネイティブ使用状況 API は、使用状況とコストに関するプロバイダーの見解に対して権威を持っています。これらは調整にとって重要ですが、プロバイダー固有のディメンション、可用性の遅延、異なるタイム バケット、および制限されたアプリケーション レベルのコンテキストを使用する場合があります。彼らはプロバイダ API キーを知っているかもしれませんが、顧客、ワークフロー、内部プロジェクト、またはリセラーは知らないかもしれません。
ゲートウェイが所有するリクエスト台帳は、アプリケーションに最も近いコンテキストをキャプチャします。ディスパッチ前に、ゲートウェイ API キー、モデル エイリアス、ルーティングされたプロバイダー、顧客 ID、チーム ID、および相関 ID を記録できます。また、失敗、再試行、ストリーミング状態、部分的な使用状況をキャプチャすることもできます。リスクとしては、ゲートウェイの見積もりをプロバイダが決済した費用と調整する必要があるということです。
請求台帳では、残高、支払い、クレジット、請求書、調整、商業ポリシーが追跡されます。明確な価格設定と決済ルールが適用された後にのみ、使用量に応じた料金を受け取る必要があります。未加工の使用状況記録を請求状況に直接混合すると、監査が難しくなります。
ウェアハウスはこれらのソースを組み合わせます。耐久性のあるアーキテクチャにより、正規化されたゲートウェイ記録、生のプロバイダー使用状況の詳細、プロバイダーコストのエクスポート、クラウド請求のエクスポート、支払い記録、請求書記録が保存されます。その後、分析 API によって高速ロールアップを公開できると同時に、詳細エクスポートによって監査と調整に十分な出所が提供されます。
ライフサイクルの状態: 見積、最終、決済、請求
AI の使用状況は、リクエストの開始時に常に把握できるとは限りません。予算チェックでは見積もりが使用される場合があります。ストリーミング通話では、接続が閉じる前に部分的な使用が発生する場合があります。非同期イメージまたはバッチ ジョブは後で完了する場合があります。ホストされたツールは、最初のモデル呼び出し後に追加の課金対象ユニットを生成する場合があります。プロバイダーコスト API は遅れて更新される場合があります。クラウドの請求書は、異なる粒度で決済される場合があります。
そのため、分析レコードは履歴を上書きするのではなく、ライフサイクルの状態を保持する必要があります。有用な状態には、推定、部分、最終、provider_reported、調整済み、決済済み、請求済み、キャンセル、失敗、不明などがあります。正確な語彙は異なる場合がありますが、API により、意思決定時にわかっていた内容と、後で請求された内容を区別できるようになります。
これは、予算の執行において特に重要です。リアルタイムのコスト見積もりは、リクエストをディスパッチするかどうかを決定するのに役立ちますが、キャッシュされたトークン、再試行、プロバイダー側のアカウンティング、ツール呼び出し、またはストリーミングの終了により、最終的なコストは異なる場合があります。見積もりと最終結果の両方を保持する分析 API により、これらの違いを説明できます。
ページ分割とエクスポートの設計
エクスポートは、手動ダウンロードではなく自動化を目的として設計する必要があります。 Cursor ページネーションは、大量の変化するデータセットの場合、通常、オフセット ページネーションよりも安全です。レコードには、安定した順序、不変のイベント ID、created_at および updated_at タイムスタンプ、増分同期用のウォーターマークが必要です。
適切なエクスポート エンドポイントは、冪等の取り込みをサポートしています。クライアントがタイムアウト後にリクエストを繰り返す場合、ダウンストリームで重複を作成すべきではありません。遅れて到着した使用状況によってレコードが変更された場合、updated_at ウォーターマークによりウェアハウスがレコードを取得できるようにする必要があります。レコードが可変行ではなく不変イベントである場合、調整は元の使用状況レコードを参照する新しいイベントとして表す必要があります。
時間フィルターは、リクエストの開始、リクエストの終了、プロバイダーの決済、請求期間、またはレコードの更新時間に適用するかどうかを定義する必要があります。それらの違いは重要です。 12 月のリクエストは 1 月に解決される可能性があります。クラウド請求のエクスポートには、1 日を通して使用量が反映される場合がありますが、最終的には後で完了します。プロバイダの調整により、過去のコストが更新される可能性があります。
プライバシーとアクセス制御
分析に関する質問のほとんどはメタデータで解決できます。プロンプトコンテンツと出力コンテンツをデフォルトで保存すると、コストレポートを改善することなく、プライバシー、保持、アクセス制御のリスクが増加します。通常はメタデータのみの分析 (識別子、タイムスタンプ、モデル、トークン数、モダリティ、ステータス、およびコストのフィールド) がデフォルトになります。
デバッグや品質レビューにプロンプトまたは出力コンテンツが必要な場合は、明示的な保持、権限、編集、監査ログを使用して個別に管理する必要があります。分析 API は多くの場合、財務、運用、カスタマー サクセス、エンジニアリング、および再販業者のユーザーにサービスを提供します。すべての読者が機密コンテンツを閲覧できるわけではありません。
アクセス制御は読者の境界に従う必要があります。チームメンバーには自分のチームのみが表示されます。顧客にはテナントのみが表示されます。リセラーは、自分が管理するダウンストリームアカウントのみを表示できます。 API キーの所有者には、そのキーのみが表示されます。管理者はアカウント間レポートが必要な場合がありますが、広範なアクセスは明示的かつ監査される必要があります。
よくある間違い
最初の間違いは、プロバイダーのダッシュボードを完全な分析として扱うことです API。ダッシュボードは便利ですが、顧客ごと、ワークフローごと、または倉庫のエクスポートに関する質問には事後的には答えられないことがよくあります。
2 番目の間違いは、トークンのみをカウントすることです。最新の AI の使用には、キャッシュされたトークン、推論トークン、画像、音声秒、ファイル検索、Web 検索、コード実行、ストレージ、バッチ割引、サービス層、ホストされたツールが含まれます。トークンのみのモデルでは、実際のコストが過小評価されたり、誤って割り当てられたりします。
3 番目の間違いは、プロバイダの出所を失うことです。正規化はダッシュボードに役立ちますが、請求書の異議申し立て、将来の請求変更、および詳細な調整のために生のプロバイダー フィールドを保持する必要があります。
4 番目の間違いは、見積もりを最終値で上書きすることです。予算の決定、再試行、キャンセル、部分的なストリーム、プロバイダーの調整にはすべて監査証跡が必要です。
5 番目の間違いは、浮動小数点の金額を使用することです。 10 進数の文字列または固定精度の小数点を使用し、あらゆる金額の通貨を維持します。
6 番目の間違いは、弱いタグ付けです。 API キーによるチャージバックは、キーが所有者に正しくマッピングされている場合にのみ実現可能です。顧客、ユーザー、ワークフロー、または機能によるチャージバックには、リクエスト時にこれらの識別子が存在する必要があります。
7 番目の間違いは、権限の範囲が不十分であることです。使用状況分析は、プロンプト コンテンツと比較すると無害に見えるかもしれませんが、顧客、ワークロード、ビジネス量、モデルの選択、および内部コスト構造を明らかにすることができます。
AI 使用状況分析を評価する方法 API
AI 使用状況分析 API を比較または設計する場合は、回答が必要な質問から始めます。モデル、プロバイダー、エンドポイント、API キー、顧客、チーム、ワークフロー、日付バケットごとの支出を表示できますか?倉庫のラインレベルの使用状況をエクスポートできますか?未加工の使用量とコストを区別できますか?価格バージョンと通貨を維持できますか?ストリーミング、非同期ジョブ、再試行、キャンセル、ホストされたツールを表すことができますか?プロバイダのコスト API や請求書と調整できますか?
次に、運用プロパティを評価します。カーソルベースのページネーションと増分エクスポートはサポートされていますか?レコードは再生しても安全ですか?遅れたアップデートは表示されますか?権限の境界は明示的ですか?API はデフォルトでプロンプトの保存を回避しますか?プロバイダ固有のフィールドは正規化されたフィールドとともに保存されますか?
最後に、それが商用モデルにどのように適合するかを評価します。個々のビルダーには、単純なキーレベルのレポートと月次エクスポートが必要な場合があります。 SaaS 製品では、顧客と機能の割り当てが必要な場合があります。代理店または再販業者は、下流の顧客レポートを必要とする場合があります。複数のモデルを使用するチームは、プロバイダ レベルの監査可能性を損なうことなく、プロバイダ間で統一された可視性を必要とする場合があります。
結論
耐久性のある AI 使用状況分析 API は、単なるグラフ バックエンド以上のものです。これは、モデル呼び出しをコスト、キー、チーム、顧客、ワークフロー、財務割り当て、調整に結び付けるレポート層です。最良の実装では、リクエスト レベルの出所を保持し、高速集計を公開し、使用単位をお金から分離し、プロバイダーの詳細を保持し、プライバシーとアクセス制御をコア製品要件として扱います。
複数の LLM プロバイダーを使用しているチームの場合、ゲートウェイはプロバイダー ダッシュボードに欠けていることが多いアトリビューション レイヤーを提供できます。 Model Gate の OpenAI 互換マルチモデル ゲートウェイ、統合請求、API キー管理、使用状況分析、チーム管理、Telegram 統合、およびパートナー API は、コストと割り当てスタック全体を自分で再構築することなく、LLM の実用的な API 使用状況レポートを必要とするビルダーに適しています。
実際の開始点はシンプルです。重要なディメンションを定義し、安定したリクエスト レベルの使用状況を記録し、保存します。生のプロバイダー データを収集し、集計レポートとリプレイセーフ エクスポートの両方を公開し、定期的に調整します。この基盤により、今日のダッシュボード、明日のチャージバック、そして使用量の増加に伴う金融グレードの AI コスト分析をサポートできます。