ChatGPT ドキュメント
日本語
お問い合わせ goolvyouyou@gmail.com

ゲートウェイとクラウド向けのモデルカタログの実装

バージョンごとの Codex のデフォルト設定を取得し、プロバイダー独自の設定で上書きして、モデルカタログを提供します

このページは、モデルカタログを定義し、モデル選択機能を支える Codex Models 形式を実装する開発者向けです。ゲートウェイやクラウドサービスなどの推論プロバイダーを構築する場合は、この仕様に従うことで、Codex デスクトップアプリと CLI がモデルを検出し、その指示と機能設定を使用できるようになります。

企業の管理者としてモデルカタログを管理したい場合は、 model_catalog_url の設定ガイドをご覧ください。

この形式をサポートするには、認証付きのカタログエンドポイントを実装します。リクエスト元の Codex バージョンに対応する上流プロバイダーの最新のデフォルト設定を取得し、独自の設定で上書きして、生成したカタログを返します。

カタログエンドポイントを実装する

デフォルトのカタログエンドポイントは、プロバイダーの base_url 配下にある /models です。たとえば、base_url = "https://gateway.example.com/v1" の場合、Codex は次のリクエストを送信します。

GET /v1/models?client_version=0.162.1
Authorization: Bearer <PROVIDER_ACCESS_TOKEN>

デフォルトの検出では、コマンドによる認証と、ChatGPT などの Codex バックエンドによる認証がサポートされます。コマンドによる認証を使わず、API key による認証を使用するカスタムプロバイダーでは、 model_providers.<id>.model_catalog_url を明示的に設定して、リモート検出を有効にします。API key だけでは、デフォルトのパスでの検出は開始されません。

model_catalog_url を使用して、https://gateway.example.com/codex/models などの完全なカタログ URL を指定します。デフォルトの /v1/models エンドポイントを指定することもできます。Codex は /models を追加せず、この URL をそのまま使用します。 API key による検出では、features.api_key_model_discovery を有効にしておきます。この設定はデフォルトで有効です。カスタムヘッダーだけでは検出は有効になりません。

Codex は、選択したプロバイダーの認証情報と設定済みのヘッダーを送信し、 client_version と、プロバイダーに設定されている query_params を追加します。カタログは、これらの認証情報の受信を許可されたサービスでホストしてください。

呼び出し元を認証し、対応する上流のデフォルト設定を取得して、独自の設定で上書きし、完全な ModelsResponse JSON を直接返します。すべてのエントリに、一意かつ空でない slug を指定します。model_catalog_url が明示されている場合、Codex はリダイレクトと 1 MiB を超えるレスポンスを拒否します。推論リクエストでも引き続きモデルへのアクセス制御を適用してください。

このエンドポイントを使用するクライアントから、有効になっている model_catalog_json 設定を削除します。ローカルファイルが優先されるため、この設定があるとリモートから取得されません。

クライアントのスキーマに合わせる

カタログリクエストの client_version クエリパラメーターを読み取ります。Codex は、プレリリースのサフィックスを除いた CLI バージョンを major.minor.patch として送信します。デスクトップクライアントでは、バンドルされている CLI のバージョンが使われます。

公開 Codex リポジトリの対応する rust-v<version> タグを使用するか、カスタムビルドの場合はその正確なソースコミットを使用します。以下のリンクは rust-v0.162.1 を参照しています。クライアントに対応するリビジョンを選択してください。

バンドルされているファイルは、リリース時点のスナップショットです。カタログを生成する前に、最新のデフォルト設定を取得してください。

上流の最新のデフォルト設定を取得する

OpenAI モデルを提供するクラウドプロバイダーは、OpenAI からデフォルト設定を取得します。ゲートウェイは、クラウドまたは上流プロバイダーのカタログを読み取り、デプロイ済みモデルの設定と、アカウントおよびリージョンごとの利用可否を保持します。リクエスト元の Codex バージョンを各段階で渡し、各エンドポイントに対して個別に認証します。

OpenAI からデフォルト設定を直接取得するには、同じ client_version を指定して Codex のモデルエンドポイントを呼び出します。たとえば、OpenAI の API key を使用する場合は次のようになります。

curl --fail --silent --show-error \
  'https://chatgpt.com/backend-api/codex/models?client_version=0.162.1' \
  -H "Authorization: Bearer $OPENAI_API_KEY"

ChatGPT との連携では、呼び出し元の ChatGPT アクセストークンを使用し、該当する場合は ChatGPT-Account-ID ヘッダーも使用します。上流エンドポイントへのアクセスが許可された認証情報を使用してください。ゲートウェイ自体の API key では OpenAI に認証できません。

最上位の models 配列を含め、レスポンス全体を解析します。このエンドポイントは、指示、推論のデフォルト設定、ツール設定、コンテキストの上限、サービスティアなどの Codex メタデータを返します。公開の /v1/models エンドポイントでは、このカタログは提供されません。

Codex のバージョンが変わっていなくても、これらのデフォルト設定を更新してください。リクエストの対象を意図した上流の認証主体に限定し、レスポンスのキャッシュ制御に従ってください。カタログは呼び出し元のアクセス権によって変わる場合があります。独自の上書き設定は分けて保持し、最新のデフォルト設定に再適用できるようにします。

プロバイダー独自の上書き設定を適用する

そのバージョンのレスポンス構造を保持しながら、フィールドの値を変更します。

  • 呼び出し元が使用できるモデルだけに絞り込みます。各 slug をサポートされている推論ルートに対応付け、display_name、description、または priority を調整します。モデル移行を伴わないエイリアスでは、upgrade を null に設定します。
  • 推論オプション、コンテキストの上限、入力モダリティ、サービスティアを、モデルとルートがサポートする値に設定します。デフォルト値は、サポートされている選択肢の範囲内に収めます。サービスティアのないルートでは、service_tiers と additional_speed_tiers をクリアし、default_service_tier を null に設定します。
  • 代わりの設定をテスト済みでない限り、上流の指示とツール設定を保持します。メタデータによってモデルの機能が追加されたり、推論へのアクセス権が付与されたりすることはありません。

LiteLLM 経由で Bedrock を使用する場合は、 必要なカタログの変更を適用してください。生成したカタログを、サポートする各 Codex バージョンでテストします。

公開 Rust 型を使用する

クライアントのスキーマと同じ公開 Git タグまたはコミットのクレートを使用します。

  • codex_protocol::openai_models::{ModelsResponse, ModelInfo} には codex-protocol を使用します。serde_json::from_slice::<ModelsResponse>() で解析し、catalog.models を編集して、serde_json::to_vec() でラッパー全体をシリアライズします。ラッパーは、モデルの指示に関する互換性フィールドを処理します。
  • codex-models-manager::bundled_models_response() を使用すると、そのリビジョンにバンドルされた静的カタログを ModelsResponse として読み込めます。上流の最新のデフォルト設定は取得しません。