ChatGPT-Dokumentation
Deutsch
Kontakt goolvyouyou@gmail.com

Modellkataloge für Gateways und Clouds implementieren

Versionsspezifische Codex-Standardwerte abrufen, anbieterspezifische Anpassungen anwenden und einen Modellkatalog bereitstellen

Diese Seite richtet sich an Entwickler, die das Format Codex Models implementieren, das den Modellkatalog definiert und die Modellauswahl ermöglicht. Wenn Sie einen Inferenzanbieter entwickeln, etwa ein Gateway oder einen Cloud-Dienst, können Sie mit dieser Spezifikation dafür sorgen, dass die Codex-Desktop-App und CLI Ihre Modelle erkennen und deren Anweisungen und Funktionseinstellungen verwenden.

Wenn Sie ein Unternehmen administrieren und den Modellkatalog steuern möchten, lesen Sie die Konfigurationshinweise zu model_catalog_url.

Implementieren Sie zur Unterstützung des Formats einen authentifizierten Katalogendpunkt. Rufen Sie die aktuellen Standardwerte Ihres vorgelagerten Anbieters für die anfragende Codex-Version ab, wenden Sie Ihre Anpassungen an und geben Sie den resultierenden Katalog zurück.

Den Katalogendpunkt implementieren

Der Standardkatalogendpunkt ist /models unter base_url des Anbieters. Bei base_url = "https://gateway.example.com/v1" sendet Codex beispielsweise folgende Anfrage:

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

Die standardmäßige Erkennung unterstützt befehlsgestützte Authentifizierung und die Authentifizierung über das Codex-Backend, beispielsweise über ChatGPT. Legen Sie bei einem benutzerdefinierten Anbieter mit Authentifizierung per API key ohne befehlsgestützte Authentifizierung model_providers.<id>.model_catalog_url explizit fest, um die Remote-Erkennung zu aktivieren. Ein API key allein löst keine Erkennung unter dem Standardpfad aus.

Verwenden Sie model_catalog_url, um eine vollständige Katalog-URL anzugeben, etwa https://gateway.example.com/codex/models. Sie kann auch auf den Standardendpunkt /v1/models verweisen. Codex verwendet diese URL direkt, ohne /models anzuhängen. Lassen Sie für die Erkennung per API key features.api_key_model_discovery aktiviert; diese Einstellung ist standardmäßig eingeschaltet. Benutzerdefinierte Header allein aktivieren die Erkennung nicht.

Codex sendet die Authentifizierungsdaten und konfigurierten Header des ausgewählten Anbieters und hängt client_version sowie alle query_params des Anbieters an. Hosten Sie den Katalog auf einem Dienst, der zum Empfang dieser Zugangsdaten berechtigt ist.

Authentifizieren Sie den Aufrufer, rufen Sie die entsprechenden vorgelagerten Standardwerte ab, wenden Sie Ihre Anpassungen an und geben Sie das vollständige ModelsResponse-JSON direkt zurück. Geben Sie jedem Eintrag einen eindeutigen, nicht leeren slug. Bei einem expliziten model_catalog_url lehnt Codex Weiterleitungen und Antworten mit mehr als 1 MiB ab. Setzen Sie die Modellzugriffskontrollen weiterhin bei Inferenzanfragen durch.

Entfernen Sie alle wirksamen model_catalog_json-Einstellungen von Clients, die den Endpunkt verwenden: Die lokale Datei hat Vorrang und verhindert den Remote-Abruf.

Das Schema des Clients berücksichtigen

Lesen Sie den Abfrageparameter client_version aus der Kataloganfrage. Codex sendet seine CLI-Version als major.minor.patch, wobei ein etwaiges Vorabversionssuffix entfernt wird. Bei Desktop-Clients ist dies die Version der mitgelieferten CLI.

Verwenden Sie das passende rust-v<version>-Tag im öffentlichen Codex-Repository oder den exakten Quellcode-Commit für einen benutzerdefinierten Build. Diese Links verwenden rust-v0.162.1; wählen Sie die Revision aus, die zu Ihrem Client passt:

Die mitgelieferte Datei ist eine Momentaufnahme des Releases. Rufen Sie aktuelle Standardwerte ab, bevor Sie Ihren Katalog erstellen.

Aktuelle vorgelagerte Standardwerte abrufen

Cloud-Anbieter, die OpenAI-Modelle bereitstellen, rufen die Standardwerte von OpenAI ab. Gateways lesen den Katalog ihres Cloud-Anbieters oder vorgelagerten Anbieters, damit die Einstellungen des bereitgestellten Modells sowie dessen Verfügbarkeit nach Konto und Region erhalten bleiben. Geben Sie die anfragende Codex-Version bei jedem Schritt weiter und authentifizieren Sie sich an jedem Endpunkt separat.

Um Standardwerte direkt von OpenAI abzurufen, rufen Sie den Codex-Modellendpunkt mit demselben client_version auf. Zum Beispiel mit einem 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"

Verwenden Sie für eine ChatGPT-Integration das ChatGPT-Zugriffstoken des Aufrufers und gegebenenfalls den Header ChatGPT-Account-ID. Verwenden Sie Zugangsdaten, die für den vorgelagerten Endpunkt autorisiert sind; der eigene API key Ihres Gateways authentifiziert Sie nicht bei OpenAI.

Parsen Sie die vollständige Antwort einschließlich des Arrays models auf oberster Ebene. Dieser Endpunkt liefert Codex-Metadaten wie Anweisungen, Reasoning-Standardwerte, Werkzeugeinstellungen, Kontextlimits und Service-Stufen. Der öffentliche Endpunkt /v1/models stellt diesen Katalog nicht bereit.

Aktualisieren Sie diese Standardwerte auch dann, wenn sich die Codex-Version nicht geändert hat. Beschränken Sie Anfragen auf die vorgesehene vorgelagerte Identität und beachten Sie die Cache-Steuerung der Antwort: Kataloge können von den Zugriffsrechten des Aufrufers abhängen. Halten Sie Ihre Anpassungen separat, damit Sie sie auf neue Standardwerte erneut anwenden können.

Anbieterspezifische Anpassungen anwenden

Ändern Sie Feldwerte unter Beibehaltung der Antwortstruktur der jeweiligen Version:

  • Filtern Sie die Modelle auf diejenigen, die der Aufrufer verwenden darf. Ordnen Sie jeden slug einer unterstützten Inferenzroute zu und passen Sie display_name, description oder priority an. Setzen Sie bei einem Alias ohne Modellmigration upgrade auf null.
  • Setzen Sie Reasoning-Optionen, Kontextlimits, Eingabemodalitäten und Service-Stufen auf Werte, die Ihr Modell und Ihre Route unterstützen. Wählen Sie Standardwerte aus den unterstützten Optionen. Leeren Sie bei einer Route ohne Service-Stufen service_tiers und additional_speed_tiers und setzen Sie default_service_tier auf null.
  • Behalten Sie vorgelagerte Anweisungen und Werkzeugeinstellungen bei, sofern Sie keinen Ersatz getestet haben. Metadaten erweitern weder die Modellfähigkeiten noch gewähren sie Inferenzzugriff.

Wenden Sie für Bedrock über LiteLLM die erforderlichen Katalogänderungen an. Testen Sie den resultierenden Katalog mit jeder unterstützten Codex-Version.

Die öffentlichen Rust-Typen verwenden

Verwenden Sie Crates aus demselben öffentlichen Git-Tag oder Commit wie das Schema des Clients:

  • Verwenden Sie codex-protocol für codex_protocol::openai_models::{ModelsResponse, ModelInfo}. Parsen Sie mit serde_json::from_slice::<ModelsResponse>(), bearbeiten Sie catalog.models und serialisieren Sie den gesamten Wrapper mit serde_json::to_vec(). Der Wrapper verarbeitet Kompatibilitätsfelder für Modellanweisungen.
  • Verwenden Sie codex-models-manager::bundled_models_response(), um den statischen, mitgelieferten Katalog dieser Revision als ModelsResponse zu laden. Damit werden keine aktuellen vorgelagerten Standardwerte abgerufen.