Documentación de ChatGPT
Español
Contacto goolvyouyou@gmail.com

Implementación de catálogos de modelos para pasarelas y servicios en la nube

Obtén los valores predeterminados de Codex específicos de cada versión, aplica las modificaciones del proveedor y ofrece un catálogo de modelos

Esta página está dirigida a desarrolladores que implementan el formato Codex Models, que define el catálogo de modelos y permite el funcionamiento del selector de modelos. Si desarrollas un proveedor de inferencia, como una pasarela o un servicio en la nube, usa esta especificación para que la aplicación de escritorio de Codex y la CLI descubran tus modelos y utilicen sus instrucciones y ajustes de capacidades.

Si administras una empresa y quieres controlar el catálogo de modelos, consulta la guía de configuración de model_catalog_url.

Para admitir el formato, implementa un endpoint de catálogo autenticado. Obtén los valores predeterminados actuales de tu proveedor de origen para la versión de Codex que realiza la solicitud, aplica tus modificaciones y devuelve el catálogo resultante.

El endpoint predeterminado del catálogo es /models bajo base_url del proveedor. Por ejemplo, con base_url = "https://gateway.example.com/v1", Codex solicita:

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

El descubrimiento predeterminado admite autenticación mediante comandos y autenticación mediante el backend de Codex, como ChatGPT. Para un proveedor personalizado que utilice autenticación con API key sin autenticación mediante comandos, establece model_providers.<id>.model_catalog_url explícitamente para habilitar el descubrimiento remoto. Una API key por sí sola no activa el descubrimiento en la ruta predeterminada.

Usa model_catalog_url para elegir una URL completa del catálogo, como https://gateway.example.com/codex/models. También puede apuntar al endpoint predeterminado /v1/models. Codex utiliza esta URL directamente sin añadir /models. Para el descubrimiento con API key, mantén features.api_key_model_discovery habilitado; lo está por defecto. Los encabezados personalizados por sí solos no habilitan el descubrimiento.

Codex envía la autenticación y los encabezados configurados del proveedor seleccionado y añade client_version y cualquier query_params del proveedor. Aloja el catálogo en un servicio autorizado para recibir esas credenciales.

Autentica al solicitante, obtén los valores predeterminados de origen correspondientes, aplica tus modificaciones y devuelve directamente el JSON completo de ModelsResponse. Asigna a cada entrada un slug único y no vacío. Para un model_catalog_url explícito, Codex rechaza las redirecciones y las respuestas de más de 1 MiB. Sigue aplicando el control de acceso a los modelos en las solicitudes de inferencia.

Elimina cualquier ajuste model_catalog_json que esté en vigor en los clientes que utilicen el endpoint: el archivo local tiene prioridad e impide la obtención remota.

Ajusta el catálogo al esquema del cliente

Lee el parámetro de consulta client_version de la solicitud del catálogo. Codex envía su versión de la CLI como major.minor.patch, sin ningún sufijo de versión preliminar. Para los clientes de escritorio, esta es la versión de la CLI incluida.

Usa la etiqueta rust-v<version> correspondiente del repositorio público de Codex o el commit exacto del código fuente para una compilación personalizada. Estos enlaces usan rust-v0.162.1; selecciona la revisión que corresponda a tu cliente:

El archivo incluido es una instantánea de la versión. Obtén los valores predeterminados actuales antes de generar tu catálogo.

Obtén los valores predeterminados actuales del proveedor de origen

Los proveedores de nube que ofrecen modelos de OpenAI obtienen los valores predeterminados de OpenAI. Las pasarelas leen el catálogo de su proveedor de nube o de origen para conservar los ajustes del modelo desplegado y la disponibilidad por cuenta y región. Transmite la versión de Codex que realiza la solicitud en cada paso y autentícate por separado en cada endpoint.

Para obtener los valores predeterminados directamente de OpenAI, llama al endpoint de modelos de Codex con el mismo client_version. Por ejemplo, con una API key de OpenAI:

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

Para una integración con ChatGPT, usa el token de acceso de ChatGPT del solicitante y el encabezado ChatGPT-Account-ID cuando corresponda. Usa credenciales autorizadas para el endpoint de origen; la API key de tu propia pasarela no sirve para autenticarse en OpenAI.

Analiza la respuesta completa, incluido su array models de nivel superior. Este endpoint devuelve metadatos de Codex, como instrucciones, valores predeterminados de razonamiento, ajustes de herramientas, límites de contexto y niveles de servicio. El endpoint público /v1/models no proporciona este catálogo.

Actualiza estos valores predeterminados incluso cuando la versión de Codex no haya cambiado. Limita las solicitudes a la identidad de origen prevista y respeta los controles de caché de las respuestas: los catálogos pueden depender del acceso del solicitante. Mantén tus modificaciones por separado para poder volver a aplicarlas a los valores predeterminados actualizados.

Aplica las modificaciones del proveedor

Cambia los valores de los campos conservando la estructura de respuesta de la versión:

  • Filtra los modelos para incluir solo aquellos que el solicitante pueda usar. Asocia cada slug con una ruta de inferencia compatible y ajusta display_name, description o priority. Para un alias sin migración de modelo, establece upgrade en null.
  • Establece las opciones de razonamiento, los límites de contexto, las modalidades de entrada y los niveles de servicio en valores que tu modelo y tu ruta admitan. Mantén los valores predeterminados dentro de las opciones admitidas. Para una ruta sin niveles de servicio, borra service_tiers y additional_speed_tiers y establece default_service_tier en null.
  • Conserva las instrucciones y los ajustes de herramientas del proveedor de origen, salvo que hayas probado una alternativa. Los metadatos no añaden capacidades al modelo ni conceden acceso a la inferencia.

Para Bedrock a través de LiteLLM, aplica las modificaciones obligatorias del catálogo. Prueba el catálogo resultante con cada versión de Codex compatible.

Usa los tipos públicos de Rust

Usa crates de la misma etiqueta pública de Git o del mismo commit que el esquema del cliente:

  • Usa codex-protocol para codex_protocol::openai_models::{ModelsResponse, ModelInfo}. Analiza con serde_json::from_slice::<ModelsResponse>(), edita catalog.models y serializa el contenedor completo con serde_json::to_vec(). El contenedor gestiona los campos de compatibilidad de las instrucciones del modelo.
  • Usa codex-models-manager::bundled_models_response() para cargar el catálogo estático incluido en esa revisión como un ModelsResponse. No obtiene los valores predeterminados actuales del proveedor de origen.