マルチモデル API ゲートウェイの LLM 可観測性: トレース、トークン台帳、テナント分析、安全なプロンプト ロギング
マルチモデル AI ゲートウェイ向けの実用的な可観測性アーキテクチャ: すべての LLM 呼び出しを 1 回トレースし、テレメトリをトークン台帳とコスト台帳に結合し、プロバイダーの請求書を調整し、デフォルトで生のプロンプトを保存せずに安全にデバッグします。
お客様から、昨日あるワークフローがなぜ遅くなったのか、より高価になったのか、または信頼性が低くなったのかを尋ねられた場合、リクエストの総数と毎月の費用だけでは十分ではありません。マルチモデル API ゲートウェイは、可観測性をコントロール プレーンの一部として扱う場合、その質問に答えることができます。すべてのリクエストがトレースを取得し、すべてのモデル呼び出しで使用状況台帳が更新され、すべてのテナントとワークフローが帰属可能であり、機密コンテンツはデフォルトで保護されます。
この記事では、OpenAI 互換 API を介して複数のプロバイダーに対応するゲートウェイにおけるAI 使用状況分析 と LLM 可観測性の実用的な設計について説明します。このパターンは、特定のベンダーを使用しない場合でも役立ちます。つまり、ゲートウェイで一度計測し、モデル テレメトリを正規化し、請求の帰属を保持し、明示的なポリシーに基づいてのみプロンプト コンテンツをキャプチャします。
読者の問題: 「変更の原因となったテナント、モデル、プロンプト、または取得パスはどれですか?」
ほとんどのチームは、最終的には同じデバッグ ギャップに直面します。アプリケーション ログには、機能が失敗したことが示されています。プロバイダーのダッシュボードには、トークンの使用量が増加していることが示されています。財務部門は請求書を確認します。これらのビュー自体は、テナント リクエストからモデル呼び出し、取得コンテキストを経て請求コストを再試行するまでの完全なパスを説明するものではありません。
目標は、合計トークンを含む別のダッシュボードではありません。目標は、次のような運用に関する質問に答えることです。
- 支出の急増を引き起こしたテナントまたは API キーはどれですか?
- モデルのエイリアスを変更した後、レイテンシーは増加しましたか?
- 再試行またはフォールバックはコストを二重にカウントしますか?
- 最も多くのエラー バジェットを消費するプロンプト バージョンはどれですか?
- 取得によって追加されたコンテキスト トークンが多すぎるため、RAG ワークフローのコストが高くなりましたか?
- プライベート ユーザー プロンプトを読まずにインシデントのデバッグをサポートできますか?
事実、推奨事項、予測
事実: OpenTelemetry は、chat、generate_content、text_completion などの操作名を含む、モデル操作の生成 AI セマンティック規則と属性を文書化します。同じドキュメントでは、GenAI の入力および出力メッセージ属性には機密情報または PII が含まれる可能性があり、フィルタリングまたは切り捨てが必要になる可能性があると警告しています。主要なモデル プロバイダーは、プロバイダー側の調整をサポートできる使用状況ダッシュボード、API、またはエクスポートも公開していますが、詳細はプロバイダーによって異なります。
推奨事項: プロバイダーに依存しないトレースには OpenTelemetry を使用しますが、ゲートウェイ所有のビジネス ディメンションは独自の属性と台帳に保持してください。デフォルトでは、生のプロンプトまたは出力を保存しません。メタデータ、ハッシュ、トークン数、プロンプト テンプレート ID、スキーマ名、エラー クラス、および安全ラベルを最初に保存します。コンテンツ キャプチャは、オプトイン、アクセス制御、短期間のデバッグ機能としてのみ追加してください。
予測: LLM の可観測性は、分離されたプロバイダー ダッシュボードに関するものではなく、クロスプロバイダーのコントロール プレーンに関するものになるでしょう。チームは、レイテンシ、コスト、品質、ポリシー イベント、テナントの動作、モデル間の請求の差分を 1 か所で調査できることを期待します。
リファレンス アーキテクチャ: リクエスト パス全体を観察する
ゲートウェイは、すべてのアプリケーション チームがカスタム テレメトリを構築する必要がなく、リクエストのライフサイクル全体を確認できます。有用なトレース モデルは、受信した顧客リクエストの 1 つの親スパンと、コスト、レイテンシ、品質に影響を与えるステップの子スパンから始まります。
推奨されるスパン構造
- ゲートウェイ リクエスト スパン: リクエストの受け入れ、認証、承認、レート制限、およびルーティング。
- モデル呼び出しスパン: プロバイダー、モデル、オペレーション、トークンの使用状況、応答ステータス、レイテンシ。
- 取得範囲: クエリされたインデックス、ドキュメント ID またはハッシュ ID、チャンク カウント、取得レイテンシ、コンテキスト トークン シェア。
- ツール呼び出しスパン: ツール名、ステータス、レイテンシ、エラー クラス、および副作用の分類
- 再試行期間: 再試行の理由、試行回数、プロバイダーのステータス、および増分コスト。
- フォールバック スパン: 元のモデル、フォールバック モデル、トリガー、互換性ポリシー、および最終結果。
- ガードレールまたはモデレーション スパン: 呼び出されたポリシー、決定、ラベル、出力がブロックされたか変換されたか
- 後処理範囲: JSON 検証、スキーマ修復、引用チェック、または最終的な書式設定。
親スパンには安定した相関識別子が含まれている必要があります。子スパンには、正規化された技術属性が含まれている必要があります。使用状況台帳には、永続的な請求および分析記録が含まれている必要があります。すべての情報をメトリクス ラベルに強制的に組み込むことは避けてください。テナント ID、プロンプト ハッシュ、ドキュメント ID などのカーディナリティの高い値は、トレース、ログ、台帳テーブルに保存し、ダッシュボードに集約する方が適切です。
すべての LLM 呼び出しでキャプチャされたメタデータを正規化する
すべてのモデル リクエストは、プロバイダーに関係なく、一貫したレコードを生成する必要があります。正確なスキーマは異なりますが、実用的な最小値は次のようになります。
{
"request_id": "req_01J...",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"テナントID": "テナント_123",
"チームID": "チーム_456",
"app_id": "サポートボット",
"gateway_key_id": "key_789",
"操作": "チャット",
"プロバイダー": "プロバイダー名",
"モデル": "プロバイダーモデル ID",
"model_alias": "高速サポート チャット",
"prompt_template_id": "refund_policy_v5",
"prompt_hash": "sha256:...",
"response_schema": "support_answer_v2",
"ステータス": "完了",
"error_class": null、
"latency_ms": 1842、
"input_tokens": 2110、
「出力トークン」: 384、
「cached_input_tokens」: 1200、
"estimated_cost_usd": "0.00492",
"final_billed_cost_usd": null、
"finish_reason": "停止",
「再試行回数」: 0、
"fallback_used": false、
"content_capture_policy": "メタデータのみ"
}2 つのアイデアを分けて考えてください。テレメトリは何が起こったのかを説明し、使用量台帳は請求、調整、報告すべき内容を記録します。これらはリクエスト ID とトレース ID を使用して相互に参照しますが、同じストレージ システム内に存在する必要はありません。
カウンターだけでなく、トークンとコスト台帳を作成する
トークン カウンターはグラフには便利ですが、請求やインシデントの調査には十分ではありません。台帳は状態の遷移を表す必要があります。ゲートウェイがリクエストを受け入れるときに行を作成し、リクエストの進行に応じて行を更新します。
便利な台帳の状態
- 承認済み: 認証とポリシー チェックに合格しました。
- 転送済み: リクエストはプロバイダーに送信されました。
- ストリーミング: プロバイダーはトークンを返し始めました。
- completed: 応答は正常に終了しました。
- user_aborted: クライアントは完了前に切断されました。
- 再試行: 追加のプロバイダーの試行が行われました。
- fallback_used: 失敗またはポリシー一致の後に、別のモデルまたはプロバイダーが選択されました。
- 失敗: リクエストは使用可能な応答なしで終了しました。
- 調整済み: プロバイダー側の使用量またはコスト データが比較され、適用されました。
この状態モデルは、一般的な請求エラーや分析エラーを捕捉するのに役立ちます。たとえば、クライアントが切断された場合のストリーミング応答、プロバイダーによって課金されているがユーザーには隠されている再試行、間違ったモデルをカウントしたフォールバック パス、プロバイダー間のキャッシュ アカウンティングの違いなどです。
OpenTelemetry GenAI 規則を使用し、慎重に拡張する
OpenTelemetry GenAI のセマンティック規則は、モデル操作のための移植可能な語彙を提供します。オペレーション名、プロバイダー、モデル、リクエスト パラメータ、応答終了理由、トークンの使用法、エラー ステータスなどの一般的な属性には、適用される場合はこれらの規則を使用してください。
ただし、プロバイダー中立の規約は、ゲートウェイのビジネスのあらゆる側面をカバーするわけではありません。ゲートウェイ所有の属性またはレジャー列を追加します。
- テナント ID、チーム ID、販売代理店の顧客 ID、アプリ ID;
- ゲートウェイ API キー ID とキーのスコープ;
- 料金プラン、支出制限、予算ポリシー
- モデルのエイリアスとルーティング ポリシーのバージョン;
- プロンプト テンプレート ID とプロンプト バージョン;
- ワークフロー名とワークフロー ステップ;
- 見積もりコスト、最終的な請求コスト、調整ステータス
トレードオフはカーディナリティです。これらのフィールドは調査には価値がありますが、あらゆる場所でメトリック ラベルとして使用すると、メトリックが高価になり、ノイズが多くなる可能性があります。実際的なルールは次のとおりです。カーディナリティの低い集計はメトリクスに送られます。カーディナリティの高い識別子は、トレース、ログ、台帳に保存されます。
安全なプロンプトと出力ログを設計する
完全なプロンプト ログによりデバッグが容易になりますが、プライバシー、コンプライアンス、ストレージ、内部関係者のリスクが増大します。より安全なデフォルトは、メタデータ優先の可観測性です。
デフォルト: メタデータのみ
ほとんどの実稼働トラフィックの場合、以下を保存します。
- プロンプト テンプレート ID とバージョン;
- 正規化されたプロンプトと出力のハッシュ;
- 入力、出力、キャッシュされたトークン、およびコンテキスト トークンの数
- レスポンス スキーマ名と検証結果;
- 安全ラベルとポリシーの決定;
- エラーの概要とプロバイダーのエラー クラス;
- 生のドキュメントではなく、メタデータを取得します。
オプトイン: 制御されたコンテンツのキャプチャ
詳細なデバッグのために生のコンテンツまたは編集されたコンテンツが必要な場合は、明示的なポリシーが必要です。適切な管理には、環境ホワイトリスト、テナントの同意、サンプリング、最大ペイロード長、自動編集、短い保存期間、暗号化、ロールベースのアクセス、監査ログ、機密性の高いインシデントの非常に厳格な承認パスが含まれます。
編集を完璧なものとして扱わないでください。それはリスクを軽減します。それを排除するものではありません。規制されているワークロードや機密性の高いワークロードの場合は、ハッシュのみを保存し、承認されたテスト データを使用して合成ハーネスに問題を再生することを検討してください。
RAG 可観測性を別のレイヤーとして追加します
検索拡張生成により、品質とコストの両方が変化する可能性があります。最終的なモデル呼び出しのみをログに記録すると、取得者が多すぎるチャンク、古いドキュメント、または無関係なコンテキストを返した場合に、根本原因が隠蔽されます。
取得ステップごとに、以下をキャプチャします。
- インデックスまたはコレクション名;
- 取得戦略と埋め込みモデル
- ドキュメント ID またはハッシュ ID;
- チャンク数と合計コンテキスト トークン;
- 取得レイテンシ;
- 上位スコアの分布（利用可能な場合）
- 引用範囲;
- 取得したコンテキストが最終的な回答で使用されたかどうか。
これにより、「モデルが悪化した」ことと「取得者が低品質または過剰なコンテキストを送信し始めた」ことを区別できます。また、コンテキスト トークンが総コストの大半を占めるワークフローを特定するのにも役立ちます。
ゲートウェイの使用状況とプロバイダーの請求を調整する
ゲートウェイの見積もりはすぐに利用できます。プロバイダー側の請求データは通常は遅くなりますが、より信頼性が高くなります。両方を使用してください。
毎日の調整ジョブでは、ゲートウェイ台帳の行をプロバイダー使用状況 API、コスト API、ダッシュボード エクスポート、または請求書のエクスポートと比較する必要があります。プロバイダー、モデル、プロジェクト、および時間枠ごとにデルタをグループ化します。入力トークン、出力トークン、キャッシュされたトークン、リクエスト数、コストの違いを個別に追跡します。
一般的な調整の相違点
- ストリーミングの切断: プロバイダーが生成されたトークンの料金を請求している間に、ゲートウェイはクライアントが中止されたことを認識する可能性があります。
- 再試行: 最終応答が 1 つだけ返された場合でも、複数の試行に対して料金が請求される場合があります。
- プロンプト キャッシュ: プロバイダーは、キャッシュされたトークン アカウンティングを別の方法で公開する場合があります。
- 四捨五入: リクエストごとの小さな差異が大規模に表示される可能性があります。
- バッチ割引または段階割引: プロバイダーの請求書には、リアルタイム見積もりではまだ認識されていない価格が適用される場合があります。
- プロバイダ側の変更: モデルの価格設定、トークン化の動作、または請求のエクスポートは時間の経過とともに変更される可能性があります。
調整でデルタが見つかった場合は、台帳を黙って上書きすることは避けてください。元の見積もり、プロバイダーが調整した値、調整ソース、およびわかっている場合は理由コードを保存します。
運用に関する質問に答えるダッシュボード
バニティ指標ではなく、読者の問題からダッシュボードを開始します。便利なビューには次のものがあります。
- テナント、チーム、アプリ、ワークフローごとのコスト
- リクエストあたりのコストではなく、成功したタスクあたりのコスト
- プロバイダー、モデル、モデル エイリアス別の p50、p95、p99 レイテンシー
- ルート別のフォールバック率と再試行率
- タイムアウト率とプロバイダー エラー クラスの傾向
- キャッシュ ヒット率とキャッシュされたトークンの節約額の推定値;
- 構造化出力検証の失敗率;
- エラーバジェットの消費による上位のプロンプトバージョン
- ワークフローごとの RAG コンテキスト トークンの共有
- ガードレール ブロックとプロンプト インジェクション分類子ヒット。
アラートの場合は、技術シグナルとビジネスシグナルを組み合わせます。テナント支出の突然の急増は、世界的な遅延のわずかな増加よりも緊急である可能性があります。モデルのエイリアス変更後のフォールバック率の上昇は、互換性の問題を示している可能性があります。 401、429、または 5xx 応答が繰り返される場合は、重要な問題、クォータの枯渇、またはプロバイダーの不安定性を示している可能性があります。
OpenAI 互換プロキシの最小限の実装フロー
/chat/completions プロキシの場合、フローは単純になります。
request_id を割り当て、コンテキストをトレースします。accepted のレジャー行を作成します。展開チェックリスト
- 正規のリクエスト ID とトレース ID を定義します。
- 共通モデル テレメトリに OpenTelemetry GenAI 属性を採用する
- リクエストの状態遷移を含むゲートウェイ使用状況台帳を作成する
- プロバイダ、モデル、モデル エイリアス、テナント、アプリ、ワークフローのディメンションを正規化します。
- カーディナリティの高い調査データを指標ラベルに含めないようにします。
- 生のプロンプトと出力キャプチャをデフォルトで無効にします。
- サンプリング、編集、保持、アクセス制御のための明示的なポリシーを追加する
- RAG ワークフローの取得メタデータをキャプチャする
- コスト、レイテンシ、信頼性、検証、テナントの動作に関するダッシュボードを構築する
- ゲートウェイの見積もりとプロバイダの使用状況およびコストのエクスポートを調整する
- 支出の急増、レイテンシの回帰、フォールバックのジャンプ、検証の失敗、セキュリティ関連のイベントに関するアラートを発します。
結論
マルチモデル ゲートウェイは、プロバイダーに到達する前にリクエストを認識し、プロバイダーが知らないビジネス コンテキストを付加できるため、LLM オブザーバビリティを実装するのに最適な場所です。最強の設計は「すべてを記録する」ことではありません。これは階層化されたモデルです。実行のためのプロバイダー中立のトレース、請求のための耐久性のあるトークンとコスト台帳、ガバナンスのためのテナント分析、取得品質のための RAG メタデータ、安全なデバッグのためのプライバシー最優先のプロンプト ロギングです。
メタデータ、状態遷移、調整から始めます。ポリシー、保持、およびアクセス制御の準備ができている場合にのみ、コンテンツ キャプチャを追加します。このシーケンスにより、開発者は可観測性を新たなデータ漏洩リスクに変えることなく、レイテンシ、品質、費用をデバッグするために必要な証拠を得ることができます。