Documentação do ChatGPT
Português
Contacto goolvyouyou@gmail.com

Implementar catálogos de modelos para gateways e serviços de nuvem

Obtenha os valores predefinidos do Codex específicos de cada versão, aplique substituições do fornecedor e disponibilize um catálogo de modelos

Esta página destina-se a programadores que implementam o formato Codex Models, que define o catálogo de modelos e serve de base ao seletor de modelos. Se desenvolver um fornecedor de inferência, como um gateway ou um serviço de nuvem, utilize esta especificação para permitir que a aplicação Codex para computador e a CLI descubram os seus modelos e utilizem as respetivas instruções e definições de capacidades.

Se administrar uma organização e pretender controlar o catálogo de modelos, consulte as orientações de configuração de model_catalog_url.

Para suportar o formato, implemente um endpoint de catálogo autenticado. Obtenha os valores predefinidos atuais do fornecedor a montante para a versão do Codex que faz o pedido, aplique as suas substituições e devolva o catálogo resultante.

O endpoint predefinido do catálogo é /models sob o base_url do fornecedor. Por exemplo, com base_url = "https://gateway.example.com/v1", o Codex solicita:

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

A descoberta predefinida suporta autenticação através de comandos e autenticação através do backend do Codex, como a do ChatGPT. Para um fornecedor personalizado que utilize autenticação por API key sem autenticação através de comandos, defina model_providers.<id>.model_catalog_url explicitamente para ativar a descoberta remota. Uma API key, por si só, não desencadeia a descoberta no caminho predefinido.

Utilize model_catalog_url para escolher um URL completo do catálogo, como https://gateway.example.com/codex/models. Também pode apontar para o endpoint predefinido /v1/models. O Codex utiliza este URL diretamente, sem acrescentar /models. Para a descoberta com API key, mantenha features.api_key_model_discovery ativado; está ativado por predefinição. Os cabeçalhos personalizados, por si só, não ativam a descoberta.

O Codex envia a autenticação do fornecedor selecionado e os cabeçalhos configurados, e acrescenta client_version e quaisquer query_params do fornecedor. Aloje o catálogo num serviço autorizado a receber essas credenciais.

Autentique o requerente, obtenha os valores predefinidos a montante correspondentes, aplique as suas substituições e devolva diretamente o JSON ModelsResponse completo. Atribua a cada entrada um slug único e não vazio. Para um model_catalog_url explícito, o Codex rejeita redirecionamentos e respostas superiores a 1 MiB. Continue a impor o controlo de acesso aos modelos nos pedidos de inferência.

Remova qualquer definição model_catalog_json em vigor nos clientes que utilizem o endpoint: o ficheiro local tem precedência e impede a obtenção remota.

Utilizar o esquema correspondente ao do cliente

Leia o parâmetro de consulta client_version no pedido do catálogo. O Codex envia a sua versão da CLI como major.minor.patch, sem qualquer sufixo de pré-lançamento. Nos clientes para computador, esta é a versão da CLI incluída.

Utilize a etiqueta rust-v<version> correspondente no repositório público do Codex ou o commit exato do código-fonte de uma compilação personalizada. Estas ligações utilizam rust-v0.162.1; selecione a revisão correspondente ao seu cliente:

O ficheiro incluído é uma captura dos dados no momento do lançamento. Obtenha os valores predefinidos atuais antes de produzir o seu catálogo.

Obter os valores predefinidos atuais a montante

Os fornecedores de nuvem que disponibilizam modelos OpenAI obtêm os valores predefinidos da OpenAI. Os gateways leem o catálogo do seu fornecedor de nuvem ou a montante para preservar as definições do modelo implementado e a disponibilidade por conta e região. Transmita a versão do Codex que faz o pedido em cada etapa e autentique-se separadamente em cada endpoint.

Para obter os valores predefinidos diretamente da OpenAI, invoque o endpoint de modelos do Codex com o mesmo client_version. Por exemplo, com uma API key da 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 uma integração com o ChatGPT, utilize o token de acesso do ChatGPT do requerente e o cabeçalho ChatGPT-Account-ID, quando aplicável. Utilize credenciais autorizadas para o endpoint a montante; a API key do seu gateway não permite autenticar-se na OpenAI.

Analise a resposta completa, incluindo o array models de nível superior. Este endpoint devolve metadados do Codex, como instruções, valores predefinidos de raciocínio, definições de ferramentas, limites de contexto e níveis de serviço. O endpoint público /v1/models não fornece este catálogo.

Atualize estes valores predefinidos mesmo quando a versão do Codex não tiver mudado. Restrinja os pedidos à identidade a montante pretendida e respeite os controlos de cache da resposta: os catálogos podem depender do acesso do requerente. Mantenha as suas substituições separadas para que possa reaplicá-las a valores predefinidos atualizados.

Aplicar substituições do fornecedor

Altere os valores dos campos, preservando a estrutura de resposta da versão:

  • Filtre os modelos para incluir apenas os que o requerente pode utilizar. Associe cada slug a uma rota de inferência suportada e ajuste display_name, description ou priority. Para um alias sem migração de modelo, defina upgrade como null.
  • Defina as opções de raciocínio, os limites de contexto, as modalidades de entrada e os níveis de serviço com valores suportados pelo seu modelo e pela sua rota. Mantenha os valores predefinidos entre as opções suportadas. Para uma rota sem níveis de serviço, limpe service_tiers e additional_speed_tiers e defina default_service_tier como null.
  • Preserve as instruções e as definições de ferramentas a montante, a menos que tenha testado uma alternativa. Os metadados não acrescentam capacidades ao modelo nem concedem acesso à inferência.

Para o Bedrock através do LiteLLM, aplique as alterações obrigatórias ao catálogo. Teste o catálogo resultante com cada versão do Codex suportada.

Utilizar os tipos públicos de Rust

Utilize crates da mesma etiqueta Git pública ou do mesmo commit que o esquema do cliente:

  • Utilize codex-protocol para codex_protocol::openai_models::{ModelsResponse, ModelInfo}. Analise com serde_json::from_slice::<ModelsResponse>(), edite catalog.models e serialize todo o objeto envolvente com serde_json::to_vec(). O objeto envolvente gere os campos de compatibilidade das instruções dos modelos.
  • Utilize codex-models-manager::bundled_models_response() para carregar o catálogo estático incluído nessa revisão como um ModelsResponse. Não obtém os valores predefinidos atuais a montante.