LiteLLM 経由で Bedrock を使用する
組織で LiteLLM 経由で Codex を Amazon Bedrock にルーティングする場合は、 このページを参照してください。LiteLLM ゲートウェイがすでにある場合は、まず Codex を接続します。LiteLLM をデプロイするのは、 組織で新しいゲートウェイが必要な場合のみです。
他のゲートウェイ製品にも、同じゲートウェイの要件 と Codex の接続手順が適用されます。
既存のゲートウェイに接続する
ゲートウェイ管理者から次の値を入手します。
https://gateway.example.com/v1などの HTTPS ベース URL。- LiteLLM が承認済みの Bedrock モデルにルーティングするモデルエイリアス。
- Codex の設定で使用するプロバイダー ID。
- スコープを限定したゲートウェイ認証情報、またはそれを返す認証ヘルパー。
- 組織の設定とともに配布されるモデルカタログ。
次に、この順序で接続を完了します。
- ゲートウェイが
POST /v1/responsesを提供し、 レスポンスをストリーミングし、後続ターンとツール呼び出しを維持し、 承認済みのエイリアスをルーティングすることをゲートウェイチームに確認してもらいます。ゲートウェイの互換性を参照してください。 - ゲートウェイに接続するに従い、 プロバイダー、モデル、認証情報を設定します。
- 有効なプロバイダーとエイリアスを確認し、接続ガイドの短い
gateway-okプロンプトを送信して、LiteLLM の記録に期待するユーザーとエイリアスが表示されることを確認します。 - 組織全体に配布する場合は、ゲートウェイ経由で Codex を展開するに進んでください。
ゲートウェイ認証情報は、LiteLLM に対する認証に使用されます。ゲートウェイは独自に Bedrock の認証情報を管理するため、その認証情報をワークステーションにコピーする必要はありません。
ゲートウェイを準備する
このセクションは、Codex を接続する前に LiteLLM ゲートウェイを作成する必要がある場合にのみ使用してください。
デプロイ前の確認
次のものが揃っていることを確認してください。
- 承認済みの LiteLLM アーキテクチャを AWS 環境にデプロイする権限。
- ルーティングするモデルまたは推論プロファイルへの Bedrock アクセス。
- レビュー済みの LiteLLM イメージとデプロイ構成。
- 信頼できる HTTPS ホスト名と証明書。
- 制限されたクライアントネットワーク範囲。
以下の Runtime の例では、ゲートウェイの AWS ID に、選択した推論プロファイルとアカウントのデフォルトプロジェクトに対する bedrock:InvokeModel が必要です。必要な権限については、AWS の GPT-6 Sol のセットアップ手順を参照してください。
アーキテクチャ
この構成では、Codex と Bedrock の間に LiteLLM を配置し、クライアントとの境界で HTTPS を使用します。ロードバランサーと LiteLLM は組織のゲートウェイの境界内に置き、プロバイダーの認証情報はゲートウェイ側に保持します。
受信アクセスを承認済みクライアントに制限し、データベースとキャッシュのポートを非公開に保ち、ゲートウェイには必要な Bedrock 権限のみを付与します。再起動によって実装が意図せず変わらないよう、デプロイするイメージをダイジェストで固定してください。
プロンプト、ソースの抜粋、ツールの結果はゲートウェイを通過し、そのログに記録される可能性があります。リクエストのログ記録を有効にする前に、保持、アクセス、秘匿化の方針を決めてください。MCP serverとプラグインは別々の接続と認証を使用し、このゲートウェイ設定ではそれらは設定されません。
デプロイの確認項目
開発者にゲートウェイを提供する前に、次の確認項目を順番に完了してください。
| 確認項目 | 成果物 |
|---|---|
| 非公開のデータベースとキャッシュの依存サービスを含めてプロキシをデプロイする。 | ゲートウェイが Bedrock 認証を管理する、末尾が /v1 の安定した HTTPS ベース URL。 |
| モデルのルートと、それに対応するクライアントカタログを設定する。 | 意図した Bedrock のターゲットにマッピングされた、安定した Codex 向けエイリアス。 |
| Responses のサポートを検証する。 | POST /v1/responses のレスポンスがストリーミングされ、response.completed で終了すること。 |
| テスト用認証情報を発行する。 | エイリアスへのアクセスを限定し、有効期限、予算、レート制限を設定した、ユーザーごとの仮想キー。 |
| 開発者を 1 人接続する。 | Codex のプロバイダー設定と、ゲートウェイ経由で検証済みの短いプロンプト。 |
以下のセクションで、各確認項目を説明します。本番環境への展開では、 後続ターン、ツール、認証情報の取り消しもテストしてください。
Bedrock のルートを選ぶ
LiteLLM の上流ルートによって、Bedrock のエンドポイント、モデル識別子、認証方法が決まります。ゲートウェイをデプロイまたは変更する際は、これらをまとめて扱ってください。
新しい設定では Bedrock Runtime を使用します。以下の例では、その OpenAI 互換の Responses エンドポイントを使用します。
代替ルートについては、LiteLLM の Bedrock Mantle 連携を参照してください。
AWS へのデプロイ例として、リビジョンを固定した LiteLLM on ECS のリファレンスを使用してください。この実装は Bedrock Runtime を使用し、ECS タスクロールから認証情報を更新します。デプロイ手順と認証手順を一緒に実施し、本番環境の要件が、組織のネットワーク、TLS、ログ記録、リソース保持のポリシーに合っているか確認してください。
どのルートを選ぶ場合も、デプロイするゲートウェイのバージョン、上流エンドポイント、モデルの組み合わせを、ゲートウェイの互換性に照らして検証してください。上流モデルがゲートウェイのモデル一覧に表示されても、そのストリーミング、会話の継続、ツールの動作が Codex で機能するとは判断できません。
Runtime モデルのルートを設定する
安定した Codex 向けエイリアスを、承認済みの上流モデルにマッピングします。この Runtime の例を使用する前に、AWS アカウントとリージョンでアクセスできることを確認してください。
model_list:
- model_name: company-coding-model
litellm_params:
model: openai/global.openai.gpt-6-sol
api_key: os.environ/AWS_BEARER_TOKEN_BEDROCK
api_base: https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1シークレット管理システムを通じて、有効な Bedrock API key を AWS_BEARER_TOKEN_BEDROCK として提供します。有効期間の短いキーでは、期限切れになる前に代替キーを発行し、ゲートウェイプロセスの環境変数を更新して、そのキーを使用するワーカーを再起動または再デプロイします。一方、ECS のリファレンスでは、タスクロールからプロセス内で認証情報を更新します。その設定とエントリーポイントを組み合わせて使用してください。
openai/ プレフィックスは LiteLLM の OpenAI 互換アダプターを選択し、設定された api_base が Bedrock Runtime にリクエストを送信します。Global 推論プロファイルは、送信元リージョンの外部にリクエストをルーティングする場合があります。AWS の権限とデータ所在地の要件を満たすプロファイルとリージョンを選び、必要に応じて両方の値を置き換えてください。
クライアントは company-coding-model を送信し、LiteLLM は設定された上流ルートを使用します。このカスタムエイリアスには、次に説明する対応したクライアントカタログが必要です。汎用のゲートウェイは、組み込みの Bedrock プロバイダーによるメタデータの調整を継承しません。
クライアントカタログを準備する
Codex 0.158.0 を使うこの GPT-6 Sol/Runtime の例では、そのバージョンのモデルカタログにある完全な gpt-6-sol エントリを出発点にします。そのエントリに、次の編集をすべて適用してください。
| フィールド | 必要な編集 |
|---|---|
slug |
LiteLLM のエイリアスと一致するよう、"company-coding-model" に設定します。 |
visibility |
"list" に設定します。 |
availability_nux |
null に設定します。 |
upgrade |
null に設定します。 |
use_responses_lite |
false に設定します。 |
tool_mode |
null に設定します。 |
supported_reasoning_levels |
effort が "ultra" のエントリを削除し、他のエントリは維持します。 |
additional_speed_tiers |
[] に設定します。 |
service_tiers |
[] に設定します。 |
default_service_tier |
null に設定します。 |
web_search_tool_type |
"text" に設定します。 |
multi_agent_version |
"v1" に設定します。 |
supports_search_tool |
Runtime では false に設定します。 |
モデルの指示とコンテキストの上限を含め、残りのフィールドは維持します。編集したエントリは、カタログのトップレベルの models 配列内に保持してください。これらの変更は、リリース済みの Bedrock のメタデータ調整と Runtime の検索制限を反映しています。クライアントのバージョンや上流モデルを変更する際は、対応するソースと照合して再確認してください。
完全な JSON ファイルを配布し、ゲートウェイ経由で Codex を展開するに従って model_catalog_json を設定します。Runtime のクライアント設定では web_search = "disabled" を維持してください。より多くのユーザーに配布する前に、ゲートウェイ経由で編集済みのカタログを検証します。
Responses のサポートを検証する
クライアント向けの HTTPS エンドポイントで POST /v1/responses を公開します。ロードバランサーとすべてのリバースプロキシが、バッファリングせずにストリーミングイベントを通過させるよう設定してください。後続ターンと関数呼び出しの結果を維持します。Chat Completions のエンドポイントが動作するだけでは、この接続には不十分です。
クライアント設定を配布する前に、ゲートウェイの互換性の確認を完了してください。ユーザーが使用するものと同じホスト名、ネットワーク制御、認証経路を通じてテストします。
テスト用認証情報を発行する
テストユーザー 1 人に対して、スコープを限定した LiteLLM 仮想キーを作成します。承認済みのエイリアスにアクセスを限定し、有効期限、レート制限、予算を設定してください。適用できる制御については、LiteLLM の仮想キーのドキュメントを参照してください。
シークレット管理のプロセスまたは認証ヘルパーを通じてキーを配布します。ユーザーに LiteLLM の管理者キーを渡したり、config.toml にゲートウェイ認証情報を埋め込んだりしないでください。
ユーザーの接続を検証する
アクセスを拡大する前に、次の確認を完了してください。
- HTTPS 証明書がゲートウェイのホスト名と一致し、サービスが正常であることを確認します。
- ゲートウェイに接続するに従って、ユーザーを 1 人接続します。
- 短いプロンプト、後続ターン、読み取り専用のツールタスクを実行します。
- ゲートウェイの記録に、認証情報や機密性の高いプロンプト内容を公開することなく、期待する ID、エイリアス、上流ルートが表示されることを確認します。
- 認証情報の期限切れまたは取り消しをテストし、許可されていないモデルエイリアスが拒否されることを確認します。
デプロイしたイメージのバージョン、ルート設定、テスト結果を、展開の記録とともに保管します。チームへの配布と継続的な運用については、ゲートウェイ経由で Codex を展開するに進んでください。
接続の問題を解決する
失敗が発生しているレイヤーを手がかりに、問題を絞り込みます。
| 症状 | 確認事項 |
|---|---|
| 推論の前に HTTPS が失敗する | DNS、証明書のホスト名、ロードバランサーの正常性、許可されたクライアントネットワークを確認します。 |
ゲートウェイが 401 または 403 を返す |
ゲートウェイのログを使い、ユーザーの認証情報の拒否と、上流の Bedrock の認証または権限の失敗を区別します。 |
| リクエストしたモデルが見つからない | 正確なクライアント向けエイリアスと、上流モデルまたは推論プロファイルへのマッピングを確認します。 |
| LiteLLM に到達する前にリクエストがブロックされる | リクエストボディの制限も含め、ロードバランサーとウェブアプリケーションファイアウォールのログを確認します。代表的な Codex リクエストをテストする間も、セキュリティ制御を維持してください。 |
| テキストは返るが、ターンが完了しない | ストリーミングのバッファー、タイムアウト、終端イベント、および「ゲートウェイの互換性」にある後続ターンとツール呼び出しの確認項目を調べます。 |
| 上流へのリクエストがタイムアウトする | タイムアウト値を変更する前に、送信元リージョンでのモデルの利用可否、ルーティング設定、クォータ、ゲートウェイのログを確認します。 |
修正後は、同じユーザーの接続経路で再テストしてください。ゲートウェイのヘルスチェックが成功しても、認証済みの推論リクエストや Codex のターン全体が検証されたことにはなりません。