マルチテナント ゲートウェイの Anthropic API バージョンとベータ ヘッダーを管理する
anthropic-version と anthropic-beta をテナント スコープの機能として扱います。バージョン レジストリを構築し、ベータ許可リストを強制し、互換性のあるアップストリームにのみルーティングし、前方互換性のあるストリームを保持し、すべての使用イベントで有効なプロトコルを記録します。
Anthropic 互換の API ゲートウェイは、anthropic-version と anthropic-beta を通常のパススルー ヘッダーとして扱うべきではありません。彼らは、検証ルール、応答ブロック、ストリーミング イベント、可用性、価格設定、キャッシュ アカウンティングを変更できるプロトコルの動作と実験的な機能を選択します。
実際的な問題は、1 つのテナントのリクエスト ヘッダーによるプラットフォーム ポリシーのバイパスを許可せずに、ネイティブの Claude 動作を維持することです。解決策は、プロトコル アドミッションを第一級のゲートウェイの決定にすることです。つまり、呼び出し元を認証し、そのバージョン ポリシーを解決し、要求されたベータ機能を検証し、互換性のあるルートを選択し、アップストリームに送信された内容を正確に記録します。
ポリシーの境界を定義する
事実: 直接の Claude API リクエストには anthropic-version ヘッダーが必要ですが、通常は公式 SDK がそれを提供します。 Anthropic ベータ機能は、anthropic-beta または SDK 固有のベータ パラメータを通じてリクエストされます。
推奨事項: 両方の値を、信頼できるルーティング命令ではなく、要求された機能として解釈します。クライアントはバージョンまたはベータを要求する場合がありますが、その組み合わせがテナント、API キー、モデル、リージョン、およびアップストリーム資格情報でサポートされているかどうかはゲートウェイが決定します。
未承認のベータ版を黙って削除しないでください。これにより、明示的なリクエストが、異なるセマンティクスで成功した呼び出しに変わる可能性があります。上流の資格情報や内部ルートの詳細を公開せずに、サポートされていない機能を識別する安定したゲートウェイ エラーを表示してディスパッチする前に拒否します。
{
"type": "gateway_policy_error",
"code": "beta_not_allowed",
"message": "The requested Anthropic beta is not enabled for this API key.",
"details": {
"beta": "example-beta-2026-01-01",
"policy_id": "claude-production"
}
}アドミッションの失敗に対しては 4xx 応答を返し、ゲートウェイまたはアップストリームの失敗に対しては 5xx 応答を予約します。 Anthropic が独自のエラー形式を変更した場合でも、エラー スキーマを安定に保ちます。
バージョンと機能のレジストリを構築する
日付形式のバージョン文字列は構文的に検証するのは簡単ですが、構文だけから制御することは不可能です。ゲートウェイには、実際にテストしたバージョンとベータ機能を含むレジストリが必要です。
バージョンレコード
各バージョン レコードには以下を含める必要があります:
- 正規バージョン識別子とライフサイクル状態: テスト中、利用可能、デフォルト、非推奨、またはブロック。
- サポートされているリクエスト フィールド、コンテンツ ブロック、停止理由、使用状況フィールド、既知のストリーミング イベント。
- 互換性のあるモデル、アップストリーム プラットフォーム、リージョン、認証情報プール。
- 契約結果と最後に成功したテストの日付。
- 価格設定とカタログの互換性と、キャッシュ アカウンティングの既知の影響。
- 採用制限、非推奨日、および代替ガイダンス。
ベータ版レコード
ベータ機能の可用性と運用リスクはベース API バージョンとは異なる可能性があるため、ベータ機能には別のレコードが必要です。正規ベータ名、互換性のあるバージョンとモデル、許可されたリージョン、必須のリクエスト フィールド、考えられる応答ブロック、ストリーミング イベント、価格設定、レート制限クラス、ロールアウト状態を記録します。
これをアプリケーションの条件ではなくデータとしてモデル化します。ポリシー評価者は、「キー K は、ルート R でベータ セット B を持つバージョン V を使用してもよいですか?」という具体的な質問に答えることができます。同じカタログは、すべてのアダプターに独自のテナント ルールの実装を強制することなく、チーム用の マルチモデル API ゲートウェイをサポートできます。
すべてのテナントに明示的なバージョン ポリシーを与える
3 つのポリシー モードをサポートします:
- 固定: テナントまたはキーは 1 つの正確なバージョンを使用する必要があります。欠落値または異なる値を拒否します。
- Gateway current: 欠落しているヘッダーは、ゲートウェイのテスト済みのデフォルトに解決されます。明示的なクライアント値は引き続き検証されます。
- 承認範囲: クライアントは、テストされたバージョンの有限の許可リストから選択できます。
「範囲」を 2 つのエンドポイント間のすべての日付として解釈することは避けてください。 Anthropic バージョンは識別子であり、連続したセマンティック バージョン シーケンスではありません。許可された値の明示的なセットを保存します。
上流ルートを選択する前に、有効なバージョンを解決してください:
requested = parse_version_header(request)
policy = load_policy(tenant_id, api_key_id)
effective = resolve_version(requested, policy, registry)
betas = parse_and_canonicalize_betas(request)
admitted = authorize_betas(betas, policy, effective, registry)
route = select_compatible_route(model, region, effective, admitted)
dispatch(route, effective, admitted)要求された値と有効な値を分けてください。ポリシーがデフォルトを提供する場合は異なる場合がありますが、監査レコードによってその置換が表示される必要があります。
ベータ版ヘッダーを構造的に解析する
部分文字列の一致または生の文字列の等価性を伴うベータ機能を承認しないでください。アップストリーム API で受け入れられる構文に従ってヘッダーを解析し、必要に応じて不正な形式または重複したエントリを拒否し、正規の特徴識別子を比較します。
正規順序付けは、ポリシー キャッシュ キーとテレメトリ ディメンションに役立ちます:
requested header: beta-b, beta-a
canonical policy set: [beta-a, beta-b]
upstream header: beta-b,beta-a // serialized in accepted upstream syntaxデバッグに十分なリクエスト メタデータを保存しますが、正規化された識別子で十分な場合は生のヘッダーを無期限に保持しません。ヘッダー ログには不要なクライアント メタデータが含まれる可能性があり、それらを保存すると保持とアクセス制御の範囲が広がります。
ベータ認証はテナント スコープ、できればキー スコープである必要があります。開発キーは、運用ワークロードに自動的に付与されずに、実験的な機能を受け取ることができます。ホワイトリストを変更すると、アクター、理由、以前の状態、新しい状態、有効時間を含むコントロール プレーン監査イベントが生成される必要があります。
入場をルーティングから分離する
モデル名が存在するというだけでは、リクエストはルーティング可能ではありません。ルートの適格性は、プロトコルとインフラストラクチャの機能の交差点です:
eligible(route) =
route.platform supports effective_version
AND route.model supports every admitted_beta
AND route.region permits every admitted_beta
AND route.credentials are entitled to those capabilities
AND route.pricing_catalog can account for the result完全なセットを満たすルートがない場合は、リクエストを送信する前に失敗します。ルートを適格にするためにベータ機能を削除しないでください。テナント ポリシーでその動作が明示的に定義されていない限り、別のバージョンを自動的に置き換えないでください。
この分離は、認証情報をプールしたり、顧客指定のキーをサポートしたり、リージョン間で動作したりするゲートウェイにおいて重要です。同じモデルへの 2 つのルートには、異なる機能アクセス、常駐制限、またはレート制限が設定される可能性があります。
ネイティブ応答セマンティクスを保持する
事実: Anthropic メッセージの応答は、ツールの使用、トークンの制限、コンテキスト ウィンドウの制限、ターンの一時停止、拒否などの理由で終了する場合があります。ストリーミング応答では、名前付きサーバー送信イベントが使用され、Anthropic の互換性ガイダンスでは、クライアントが新しいイベント タイプを許容する必要があります。
推奨事項: 成功したすべての終了状態を「完了」に折りたたまないでください。上流の停止理由をネイティブ応答およびゲートウェイ テレメトリに保存します。アプリケーションは、ツールを実行したり、一時停止したターンを継続したり、コンテキストを削減したり、拒否を表面化したりする必要がある場合があります。
ストリーム プロキシは、前方互換性を維持しながら、アカウンティングとライフサイクル管理に必要なイベントを認識する必要があります:
- テナントのポリシーでネイティブ パススルーが許可されている場合、不明なイベント タイプを転送します。
- 生のイベント名とシーケンスの位置を境界付き診断メタデータに保持します。
- 不慣れな追加イベントでストリームを閉じるような完全な列挙型は使用しないでください。
- アップストリームのエラー イベントを、トランスポートの切断やクライアントのキャンセルと区別します。
- 権限のあるフィールドからのみ使用を最終決定します。最終的な使用が利用できない場合は、不完全なストリームを暫定としてマークします。
ゲートウェイが OpenAI 型のエンドポイントも公開する場合は、そのアダプターをネイティブのメッセージ パスから切り離してください。 Anthropic の OpenAI 互換性レイヤーには、フィールドと機能の制限が文書化されています。共通の内部エンベロープはルーティングに役立ちますが、コンテンツ ブロックの順序、キャッシュ コントロール、思考署名、ツールの状態、プロバイダー固有の停止理由を破棄してはなりません。
アカウンティングのバージョンを認識する
事実: プロンプト キャッシュの使用は、通常の入力トークン、キャッシュ作成入力トークン、およびキャッシュ読み取り入力トークンを分離します。合計入力消費量は、該当するすべてのカテゴリを考慮する必要があります。
バージョンまたはベータ版の変更により、キャッシュの適格性、コンテンツ表現、または返される使用状況フィールドが変更される可能性があります。したがって、すべての使用イベントには次のものが含まれる必要があります:
- 要求された有効な API バージョン。
- リクエストおよび承認されたベータ セット。
- テナント、API キー、ポリシー、ルート、モデル、リージョン、およびアップストリーム リクエスト ID。
- ステータス、停止理由、ストリーム完了状態、およびエラーの属性。
- 入力、出力、キャッシュ作成、およびキャッシュ読み取りトークンのカテゴリ。
- 価格設定カタログのバージョンと暫定または確定したコストの状態。
これらのディメンションにより、統合 AI API 請求が可能となり、同様のリクエストで異なるコストが発生する理由を説明できます。プロバイダーが異なるレートのカテゴリを公開している場合は、単一の結合トークン数からの請求を避けてください。
バージョンまたはベータ版を有効にする前にテストしてください
通常のテキスト、ストリーミング テキスト、ツール呼び出し、構造化出力、拒否、トークンの切り捨て、コンテキスト ウィンドウの枯渇、ターンの一時停止、プロンプト キャッシュ、不正な形式のリクエスト、レート制限、およびミッドストリーム エラー用のコントラクト フィクスチャを作成します。
各フィクスチャについて、HTTP 個以上のステータスを比較します。コンテンツ ブロックのタイプと順序、停止理由、ツールの識別子と引数、イベント シーケンス、使用状況フィールドの存在、キャッシュ カテゴリ、およびエラーの形状をキャプチャします。正確な散文出力ではなく、承認された構造上の期待値を保存します。
シャドウ リクエストは、重複実行が安全な場合にのみ使用してください。ツール、外部副作用、機密データ、または材料費を伴うリクエストは不適切な場合があります。これらのワークロードの場合は、制御された環境でサニタイズされたフィクスチャを再生します。
予測: 新しいバージョンとベータ機能では、応答のバリエーションとイベントが引き続き追加されます。機能レコードと追加解析を中心に設計されたゲートウェイは、通常、固定列挙型とグローバル デフォルトを中心に構築されたゲートウェイよりも緊急作業が少なく、これらの変更を吸収します。
機能のロールアウトと廃止を安全に行う
テスト、内部、オプトイン、カナリア、利用可能、非推奨、ブロックされた状態を通じて機能を促進します。カナリア処理中に、ステータスの分布、停止理由、コンテンツ ブロック シーケンス、ツールの動作、使用フィールド、レイテンシ、キャッシュ結果を比較します。トラフィックが開始される前にロールバックしきい値を定義します。
退職は段階的に行う必要があります:
- 既存の割り当てを継続しながら、新しいテナントの採用をブロックします。
- 影響を受けるテナント、キー、モデル、および最近のリクエスト パターンを特定します。
- 互換性レポートまたは置き換え用のテスト エンドポイントを提供します。
- 承認されたリクエストについて警告し、明確な期限を公開します。
- 所有者と有効期限を明示的に例外にする必要があります。
- 機能をブロックし、履歴監査と請求解釈のためにレジストリ レコードを保持します。
ピン留めにより再現性が向上しますが、テスト マトリックスが拡張されます。ゲートウェイ全体のバージョンでは、運用上のバリエーションが減りますが、無関係なテナントが 1 つの移行スケジュールに結合されます。ブロード ベータ パススルーにより、機能へのアクセスが高速化されますが、コスト、常駐、およびサポートの保証が弱まります。マルチテナント サービスの場合、通常は明示的なテナントごとのポリシーが防御可能な中間点となります。
実装チェックリスト
- すべてのテナントまたは API キーにバージョン ポリシーが必要です。
- テストされたバージョンとベータ機能の記録を維持します。
- ディスパッチ前に、不正な形式、不明な機能、または無許可の機能を拒否します。
- 完全なプロトコル リクエストを解決した後にのみルートを選択してください。
- ネイティブ コンテンツ ブロック、停止理由、使用状況フィールド、ストリームを保持します。
- 追加ストリーム イベントを安全に転送し、イベント名を保持します。
- 使用状況および監査イベントに関して、要求された有効なプロトコル値を記録します。
- デフォルトを変更する前に、コントラクト フィクスチャと制御されたカナリアを実行します。
- サイレント書き換えではなく、慎重な導入制御を通じて古い機能を廃止します。
重要な設計上の決定は単純です。バージョン ヘッダーとベータ ヘッダーはポリシー入力です。ゲートウェイがそれらを機能として認め、ルーティング、テスト、測定すると、実験的な動作が通常の HTTP メタデータであるかのように装うことなく、ネイティブ API 互換性が管理可能になります。