未加工のプロバイダー キーを公開せずにパートナー LLM API を構築する方法
プロバイダーの資格情報を非表示にし、テナントの分離を強制し、使用量を測定し、予測可能なクォータ動作を公開しながら、LLM 機能をパートナー、再販業者、顧客アプリケーションに公開するための実用的なリファレンス アーキテクチャ。
LLM アクセスのパートナー API は、プロバイダー キーの薄いラッパーであってはなりません。パートナー、再販業者、または顧客のアプリケーションが言語モデルへの委任されたアクセスを必要とする場合、プラットフォームには独自のコントロール プレーン、ゲートウェイ、ポリシー層、メータリング パイプライン、および運用 Runbook が必要です。それ以外の場合、プロバイダー レベルの請求、プロバイダー レベルの制限、および共有認証情報が、1 つのパートナー統合と非常に高額なインシデントとの間の唯一の制御になります。
目標は簡単です。上流のプロバイダーの資格情報を非公開にし、パートナー固有の資格を強制し、請求対象の使用量を測定し、信頼できるクライアントを構築するための十分な透明性をパートナーに提供しながら、外部の関係者がプラットフォームを通じて LLM 機能を利用できるようにします。
リファレンス アーキテクチャ
実際のパートナー API には、コントロール プレーンとリクエスト ゲートウェイという 2 つの主要な部分があります。
コントロール プレーンは、パートナー組織、アプリケーション、環境、委任された API キー、モデル資格、レート制限階層、支出上限、請求条件、Webhook エンドポイント、監査記録を管理します。ここでは、商用ルールと運用ルールが機械可読ポリシーになります。
リクエスト ゲートウェイは、パートナー トラフィックを受信し、委任されたキーを認証し、ポリシーを評価し、割り当てを適用し、選択したモデル プロバイダーにルーティングし、使用状況を記録し、パートナーに表示される応答メタデータを返します。成熟した エンタープライズ LLM API では、このゲートウェイは、モデルのルーティング、再試行、フェイルオーバー、コンテンツ制御、オブザーバビリティが一貫して適用される場所でもあります。
重要な境界は次のとおりです。パートナーはプラットフォームが発行したキーのみを受け取ります。生のプロバイダー資格情報を受け取ることはありません。アップストリーム プロバイダー キーはプラットフォームのシークレット ストアに残り、ゲートウェイまたはバックエンド ワーカーによってのみ使用されます。
構築すべき事実のパターン
以下は、パブリック プラットフォームとクラウドのドキュメントでサポートされている事実であり、特定の展開に関する仮定ではありません:
- 一部の LLM プロバイダーは、プロジェクト スコープのキー、サービス アカウント、プロジェクト レベルのモデル アクセス、プロジェクト レベルのレート制限をサポートしています。
- マルチテナント SaaS API のクラウド ガイダンスでは、通常、ポリシー管理、ポリシー決定、ポリシー適用を分離して、偶発的なクロステナント アクセスを削減します。
- API ゲートウェイと SaaS コントロール プレーンは、レート、バースト、クォータ階層などのテナント固有のスロットリングとクォータ制御を適用できます。
- 従量制の SaaS 請求は、テナントのアクティビティの収集、集計、および請求記録との照合に依存します。
- 冪等キーは、重複した副作用を生じさせることなく、状態を変更する API リクエストを安全に再試行するための文書化されたパターンです。
- 標準化されたレート制限応答ヘッダーは、クライアントが制限、残りの許容量、リセットのタイミング、および再試行動作を理解するのに役立ちます。
すべてのパートナーに各上流モデル プロバイダーと直接統合するよう依頼するのではなく、これらのパターンをパートナー向けの LLM アクセス レイヤ（所有する）に結合することをお勧めします。
ステップ 1: テナントと ID モデルを定義する
1 つの API キー文字列だけでパートナー トラフィックを識別しないでください。有用なパートナー API には、請求、不正行為のレビュー、クォータのデバッグ、サポート調査で異なる質問がされることが多いため、個別の識別子が必要です。
少なくとも次の識別子を作成します:
- パートナー組織: 契約した外部企業。
- パートナー アプリケーション: 特定の統合、製品、プラグイン、または販売代理店のアプリケーション。
- 環境: 実稼働、ステージング、サンドボックス、または開発。
- エンド カスタマー: パートナーの顧客、ワークスペース、アカウント、またはテナント（契約上許可されており、技術的に利用可能な場合）
- API key: リクエストの認証に使用される委任された資格情報。
- リクエスト ID: ゲートウェイ、プロバイダー呼び出し、使用状況イベント、サポート ログ全体で 1 つのリクエストを追跡するための一意の識別子。
この構造は、1 つの侵害された統合またはノイズの多い統合が「パートナー X トラフィック」としか説明できない一般的な障害モードを回避します。また、パートナーのビジネス全体を無効にすることなく、1 つのアプリケーションまたは環境を一時停止することもできます。
ステップ 2: 委任されたパートナー キーを発行する
パートナー キーは、スプレッドシート内の静的トークンではなく、ファーストクラスのプラットフォーム オブジェクトである必要があります。各キーにはメタデータとポリシー バインディングが必要です:
- パートナー組織 ID
- アプリケーション ID
- 環境
- 許可された API サーフェス (チャット、埋め込み、バッチ、画像生成など)
- 許可されるモデル エイリアス
- 該当する場合、リージョンまたはデータ所在地の制約
- レート制限階層
- 支出上限または前払い残高ルール
- 作成時刻、最終使用時刻、所有者、ローテーション ステータス
可能な限りハッシュされたキー マテリアルのみを保存し、作成時に完全なシークレットを 1 回だけ公開し、ダウンタイムなしでローテーションをサポートします。実際のローテーション モデルでは、短い移行期間中に 2 つのアクティブなキーが許可され、各リクエストにどのキーが使用されたかが監査ログに記録されます。
ステップ 3: 資格をルーティングから分離する
モデルを使用するパートナーの権利は、現在サポートされているルーティング コードによって暗示されるべきではありません。資格チェックを明示的に保ち、プロバイダーの選択とは別にしてください。
たとえば、model: premium-reasoning のリクエストは、最初にポリシー決定を通過する必要があります:
- このパートナーはモデル エイリアスの使用を許可されていますか?
- パートナー アプリケーションはこの環境での使用を許可されていますか?
- リクエストは許可された領域またはデータ境界内にありますか?
- 契約は有効で良好な状態ですか?
- パートナーは支出、割り当て、不正行為のしきい値を超えていませんか?
この決定を行った後でのみ、ルーティングで上流のプロバイダー、プロバイダー プロジェクト、デプロイメント、またはフォールバック パスを選択する必要があります。モデルのルーティング変更は運用上頻繁に行われるため、これは重要です。資格の変更は意図的かつ監査可能である必要があります。
ステップ 4: 安定したパートナー API Surface
を公開するパートナーは、上流のプロバイダーが変更された場合でも、安定した動作を必要とします。すべてのプロバイダーのモデル名を直接公開するのではなく、独自のモデルのエイリアスと機能の説明を使用します。
小さな例:
POST /v1/chat/completions
Authorization: Bearer partner_key_...
Idempotency-Key: job_01J7...
X-Partner-Customer-Id: customer_123
{
"model": "standard-chat",
"messages": [
{"role": "user", "content": "Summarize this support thread."}
],
"metadata": {
"ticket_id": "T-44821",
"workflow": "support_summary"
}
}パートナーは standard-chat を要求しています。ゲートウェイは、資格、可用性、価格、待ち時間、リージョン、品質ルールに従って、現在承認されているプロバイダーとモデルにエイリアスをマップします。
ただし、プロバイダーの違いをすべて隠すことは避けてください。 2 つのモデル エイリアスに異なるコンテキスト ウィンドウ、構造化出力サポート、ツール呼び出し動作、レイテンシ プロファイル、または地域の可用性がある場合は、それらの違いを明確に文書化します。抽象化は統合を簡素化するものであり、予期せぬ動作を引き起こすものではありません。
ステップ 5: プロバイダーが呼び出す前にクォータを強制する
プロバイダーの制限は便利なガードレールですが、パートナー レベルの適用はプラットフォームに属します。 1 つの上流プロバイダー プロジェクトが多くのパートナーにサービスを提供する場合や、1 つのパートナーが異なる契約を持つ複数のアプリケーションを使用する場合があります。プロバイダーレベルのレート制限のみに依存すると、これらの違いを明確に表現できません。
アップストリーム呼び出しを行う前に割り当てチェックを適用します:
- パートナー キーごとの 1 分あたりのリクエスト数
- パートナー組織別の 1 分あたりのトークン数
- アプリケーション別の同時リクエスト
- 日次または月次の請求対象ユニット割り当て
- プリペイド残高またはクレジット限度額
- 必要に応じてエンド顧客ごとの上限
同期リクエストの場合、リクエストを受け入れられない場合は明確に拒否します。非同期ワークロードおよびバッチ ワークロードの場合は、キュー受付を実行クォータとは別に考慮してください。バッチアップロードは受け入れられますが、個々のジョブは引き続き測定され、パートナーの制限に達した場合は停止される必要があります。
ステップ 6: 予測可能なレート制限信号を返す
不透明な 429 Too Many Requests 個の応答により、回避可能なサポート チケットが作成されます。成功した応答と抑制された応答について、パートナーに表示されるクォータ信号を返します。
有用な応答には次のものが含まれます:
RateLimit-Limit: 600;w=60
RateLimit-Remaining: 42
RateLimit-Reset: 17
Retry-After: 17
X-Request-Id: req_01J8...推奨事項:
- キー、アプリケーション、組織、モデル、またはエンドポイントごとに制限が適用されるかどうかを文書化します。
- クライアントが動作できるリセット タイミングを返します。
- スロットリングされた応答には
Retry-Afterを使用します。 - エラー本体を安定させ、機械が読み取り可能な状態に保ちます。
- パートナーが動作をデバッグするために必要な場合を除き、アップストリーム プロバイダーの内部情報を公開しないでください。
これにより、パートナー クライアントの構築が容易になり、トラフィック急増時の再試行の嵐が軽減されます。
ステップ 7: 請求可能な作業に冪等性を使用する
状態または課金対象の作業を作成するエンドポイントは、冪等性キーをサポートする必要があります。これは、非同期生成ジョブ、バッチ送信、クレジット購入、Webhook でトリガーされる再試行、長時間実行タスクの場合に特に重要です。
実装ルールは単純です。パートナーが保持期間内に同じ冪等キーを使用して同じリクエストを繰り返す場合、重複した作業を作成するのではなく、元の結果を返します。
エッジケースを明示的にします:
- 冪等レコードの保持期間
- 冪等性キーのスコープが指定されるエンドポイントとパートナー キー
- 同じキーが異なるリクエスト パラメータで再利用された場合はどうなりますか
- 失敗したリクエストがキャッシュされるかどうか
- 部分的に完了したバッチ ジョブに冪等性を適用する方法
課金対象の LLM 作業の場合は、不要な機密ペイロード コンテンツを保持せずにパラメータの不一致を検出できるように、十分なリクエスト フィンガープリント データを保存します。
ステップ 8: 不変の使用状況イベントを発行する
プロバイダーの請求書をパートナーの請求に関する信頼できる情報源として扱わないでください。プロバイダーの請求書では、通常、パートナー契約、マークアップ ルール、リセラー層、エンド顧客 ID、または紛争ワークフローはわかりません。代わりに、各リクエストが終了状態に達したときに不変の使用状況イベントを発行します。
使用状況イベントには以下を含める必要があります:
- パートナー組織 ID
- アプリケーション ID と環境
- API キー ID (生のキーではありません)
- エンド顧客 ID (提供され許可されている場合)
- リクエスト ID とプロバイダー相関 ID
- モデルのエイリアスと上流プロバイダーのモデル
- 入力トークン、出力トークン、キャッシュされたトークン、またはその他の請求可能なユニット
- プロバイダーの料金ベース（利用可能な場合）
- パートナーの請求単位、マークアップ、クレジットドローダウン、または契約レート
- ステータス、エラークラス、レイテンシ、および再試行回数
- タイムスタンプとスキーマのバージョン
これらのイベントは、パートナー ダッシュボード、請求エクスポート、異常検出、割り当てカウンター、および調整にフィードします。イベント ストリームは追加専用にしておきます。修正はサイレント編集ではなく、調整イベントである必要があります。
ステップ 9: 毎日を調整する
メータリングは、一致する場合にのみ役立ちます。使用状況イベントを上流プロバイダーの使用状況、プロバイダーの請求書、クレジット残高、パートナー向けの請求記録と比較する毎日のプロセスを構築します。
調整プロセスでは以下を特定する必要があります:
- ゲートウェイによってリクエストは受け入れられたが、端末使用状況イベントが欠落しています
- パートナーのリクエストにマッピングできないプロバイダーの使用状況
- プロバイダー レポートとゲートウェイ レコード間のトークン数の違い
- 誤って請求された再試行
- 手動クレジット、払い戻し、請求修正
- 約束された支出、前払いの枯渇、または異常な成長に近づいているパートナー
ここでは、財務、サポート、エンジニアリングでも同じ ID が必要です。ダッシュボード、請求書の品目、ログ イベント、プロバイダー レコードを結び付けることができない場合、紛争は手動調査になります。
ステップ 10: 運用ランブックを作成する
パートナー API は外部の製品表面であるため、インシデントが発生する前に運用動作を計画する必要があります。少なくとも、次の状況に対応するランブックを作成します:
- 侵害されたパートナー キー: 1 つのキーを取り消すか一時停止し、パートナーに通知し、監査ログを保存し、ローテーション パスを提供します。
- 暴走使用: 緊急上限を適用するか、アプリケーションを一時停止するか、今後の使用には承認を必要とします。
- プロバイダーの停止: 承認されたプロバイダーにフェイルオーバーするか、再試行ガイダンスとともに安定したエラーを返します。
- 割り当ての枯渇: パートナーが待機、アップグレード、クレジットの購入、またはトラフィックの削減が必要かどうかを示します。
- Webhook リプレイ: 署名を検証し、冪等性を使用し、イベント配信試行を追跡します。
- 請求修正: 調整イベントを作成し、元の使用記録を保存します。
ランブックでは、各アクションを誰が実行できるかを定義する必要があります。 1 つのキーを一時停止することは、パートナー組織を無効にすることとは異なります。ノルマの引き上げは、契約の変更とは異なります。緊急時の制御には監査証跡が必要です。
トレードオフ
パートナー API ゲートウェイでは、遅延と運用責任が追加されます。これは、パートナー契約レベルで認証情報、割り当て、ルーティング、請求、可視性を制御するためのコストです。
厳格なクォータはマージンを保護し、乱用を減らしますが、バースト動作と再試行ガイダンスの設計が適切でないと、不要なエラーが発生する可能性があります。有用な割り当てシステムには、ハード制限と文書化されたバースト動作の両方があります。
詳細な測定により、請求の透明性とサポートの成果が向上しますが、保持、プライバシー、調整の義務が増大します。操作と請求に必要な識別子を収集しますが、明確な契約およびコンプライアンスの根拠がない限り、生のプロンプトと応答のコンテンツを請求記録に保存することは避けてください。
モデルを抽象化するとパートナーの統合が簡単になりますが、過度に抽象化すると重要な違いが隠れてしまう可能性があります。パートナーは、プロバイダー実装の詳細をすべて知る必要はありませんが、モデル エイリアスがコンテキスト制限、出力形式、待ち時間の予想、または地域の可用性をいつ変更するかを知る必要があります。
実装チェックリスト
- プロバイダーの資格情報を共有する代わりに、プラットフォームが所有するパートナー キーを発行します。
- すべてのキーをパートナー、アプリケーション、環境、資格、割り当て、請求レコードにマッピングします。
- 承認と資格のチェックをルーティング ロジックから切り離してください。
- 文書化された機能と制限を備えた安定したモデルのエイリアスを使用します。
- アップストリーム プロバイダーを呼び出す前に割り当てチェックを適用します。
- レート制限ヘッダーと機械可読エラーを返します。
- 状態または課金対象の作業を作成するエンドポイントには冪等性キーが必要です。
- リクエストの完了時に不変の使用状況イベントを発行します。
- プロバイダーの記録とパートナーの請求書と照合して使用量を調整します。
- キーの侵害、暴走した使用、プロバイダーの停止、クォータの枯渇、Webhook のリプレイ、および請求の修正に備えたランブックを維持します。
実用的な結論
LLM アクセスにとって最も安全なパートナー API は、非表示の資格情報を使用してリクエストを転送するプロキシではありません。これは、独自の ID モデル、ポリシー レイヤ、割り当ての適用、使用量メーター、調整プロセス、パートナー向けの透明性を備えた委任されたアクセス システムです。
制御境界から始めます。パートナー キー、明示的な資格、呼び出し前のクォータ チェック、冪等の状態変更エンドポイント、不変の使用状況イベントです。次に、ダッシュボード、調整、レート制限セマンティクス、インシデント ランブックなどの運用の成熟度を追加します。このアーキテクチャにより、パートナーは未加工のプロバイダ キーを受け取ることなく LLM 機能を構築できると同時に、コスト、悪用、信頼性、請求に関する紛争を管理するための十分な制御をプラットフォームに提供できます。