Documentation ChatGPT
Français
Contact goolvyouyou@gmail.com

Implémenter des catalogues de modèles pour les passerelles et les services cloud

Récupérez les paramètres par défaut de Codex propres à chaque version, appliquez les ajustements du fournisseur et exposez un catalogue de modèles

Cette page s’adresse aux développeurs qui implémentent le format Codex Models, lequel définit le catalogue de modèles et alimente le sélecteur de modèles. Si vous développez un fournisseur d’inférence, comme une passerelle ou un service cloud, utilisez cette spécification pour permettre à l’application de bureau Codex et à la CLI de découvrir vos modèles et d’utiliser leurs instructions et leurs paramètres de capacités.

Si vous administrez une entreprise et souhaitez contrôler le catalogue de modèles, consultez les consignes de configuration de model_catalog_url.

Pour prendre en charge ce format, implémentez un point de terminaison de catalogue authentifié. Récupérez les paramètres par défaut actuels de votre fournisseur en amont pour la version de Codex à l’origine de la requête, appliquez vos ajustements et renvoyez le catalogue obtenu.

Implémenter le point de terminaison du catalogue

Le point de terminaison par défaut du catalogue est /models sous le base_url du fournisseur. Par exemple, avec base_url = "https://gateway.example.com/v1", Codex envoie la requête suivante :

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

La découverte par défaut prend en charge l’authentification par commande et l’authentification via le backend de Codex, comme ChatGPT. Pour un fournisseur personnalisé utilisant l’authentification par API key sans authentification par commande, définissez model_providers.<id>.model_catalog_url explicitement pour activer la découverte à distance. Une API key seule ne déclenche pas la découverte sur le chemin par défaut.

Utilisez model_catalog_url pour choisir une URL de catalogue complète, telle que https://gateway.example.com/codex/models. Elle peut également pointer vers le point de terminaison par défaut /v1/models. Codex utilise cette URL directement sans y ajouter /models. Pour la découverte par API key, laissez features.api_key_model_discovery activé ; il l’est par défaut. Les en-têtes personnalisés seuls n’activent pas la découverte.

Codex envoie les informations d’authentification du fournisseur sélectionné et les en-têtes configurés, puis ajoute client_version et les éventuels query_params du fournisseur. Hébergez le catalogue sur un service autorisé à recevoir ces identifiants.

Authentifiez l’appelant, récupérez les paramètres par défaut correspondants en amont, appliquez vos ajustements et renvoyez directement le JSON ModelsResponse complet. Attribuez à chaque entrée un slug unique et non vide. Pour un model_catalog_url explicite, Codex refuse les redirections et les réponses de plus de 1 Mio. Continuez à contrôler l’accès aux modèles lors des requêtes d’inférence.

Supprimez tout paramètre model_catalog_json actif sur les clients utilisant ce point de terminaison : le fichier local est prioritaire et empêche la récupération à distance.

Respecter le schéma du client

Lisez le paramètre de requête client_version dans la requête du catalogue. Codex envoie sa version de CLI au format major.minor.patch, sans suffixe de préversion. Pour les clients de bureau, il s’agit de la version de la CLI intégrée.

Utilisez le tag rust-v<version> correspondant dans le dépôt public Codex, ou le commit source exact pour une compilation personnalisée. Ces liens utilisent rust-v0.162.1 ; sélectionnez la révision correspondant à votre client :

Le fichier intégré est un instantané de la version publiée. Récupérez les paramètres par défaut actuels avant de produire votre catalogue.

Récupérer les paramètres par défaut actuels en amont

Les fournisseurs cloud qui proposent des modèles OpenAI récupèrent les paramètres par défaut auprès d’OpenAI. Les passerelles lisent le catalogue de leur fournisseur cloud ou en amont afin de conserver les paramètres du modèle déployé et sa disponibilité selon le compte et la région. Transmettez la version de Codex à l’origine de la requête à chaque étape et authentifiez-vous séparément auprès de chaque point de terminaison.

Pour récupérer les paramètres par défaut directement auprès d’OpenAI, appelez le point de terminaison des modèles Codex avec le même client_version. Par exemple, avec une API key OpenAI :

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

Pour une intégration ChatGPT, utilisez le jeton d’accès ChatGPT de l’appelant et l’en-tête ChatGPT-Account-ID, le cas échéant. Utilisez des identifiants autorisés pour le point de terminaison en amont ; l’API key propre à votre passerelle ne permet pas de s’authentifier auprès d’OpenAI.

Analysez la réponse complète, y compris son tableau models de premier niveau. Ce point de terminaison renvoie des métadonnées Codex telles que les instructions, les paramètres de raisonnement par défaut, les paramètres des outils, les limites de contexte et les niveaux de service. Le point de terminaison public /v1/models ne fournit pas ce catalogue.

Actualisez ces paramètres par défaut même si la version de Codex n’a pas changé. Limitez les requêtes à l’identité prévue en amont et respectez les directives de mise en cache des réponses : les catalogues peuvent dépendre des droits d’accès de l’appelant. Conservez vos ajustements séparément afin de pouvoir les réappliquer aux paramètres par défaut actualisés.

Appliquer les ajustements du fournisseur

Modifiez les valeurs des champs tout en préservant la structure de réponse de la version :

  • Filtrez les modèles pour ne conserver que ceux que l’appelant peut utiliser. Associez chaque slug à une route d’inférence prise en charge et ajustez display_name, description ou priority. Pour un alias sans migration de modèle, définissez upgrade sur null.
  • Définissez les options de raisonnement, les limites de contexte, les modalités d’entrée et les niveaux de service sur des valeurs prises en charge par votre modèle et votre route. Veillez à ce que les valeurs par défaut figurent parmi les choix pris en charge. Pour une route sans niveaux de service, videz service_tiers et additional_speed_tiers, puis définissez default_service_tier sur null.
  • Conservez les instructions et les paramètres des outils provenant de l’amont, sauf si vous avez testé une solution de remplacement. Les métadonnées n’ajoutent aucune capacité aux modèles et n’accordent aucun accès à l’inférence.

Pour Bedrock via LiteLLM, appliquez les modifications requises du catalogue. Testez le catalogue obtenu avec chaque version de Codex prise en charge.

Utiliser les types Rust publics

Utilisez les crates du même tag Git public ou du même commit que le schéma du client :

  • Utilisez codex-protocol pour codex_protocol::openai_models::{ModelsResponse, ModelInfo}. Analysez les données avec serde_json::from_slice::<ModelsResponse>(), modifiez catalog.models et sérialisez l’ensemble de la structure englobante avec serde_json::to_vec(). Cette structure gère les champs de compatibilité des instructions des modèles.
  • Utilisez codex-models-manager::bundled_models_response() pour charger le catalogue statique intégré de cette révision en tant que ModelsResponse. Cela ne récupère pas les paramètres par défaut actuels en amont.