Crie um catálogo /v1/models com reconhecimento de locatário para um gateway API multimodelo

Um gateway não deve retornar todos os modelos conhecidos por todos os provedores conectados de GET /v1/models. Ele deve retornar os modelos que a chave API autenticada está autorizada e operacionalmente capaz de chamar.

Essa distinção é importante quando uma chave API fornece acesso a vários provedores LLM. Uma união bruta de catálogos upstream pode incluir modelos proibidos pela política da equipe, indisponíveis no plano do locatário, faltando uma credencial íntegra, incompatíveis com o API solicitado ou não implantados na região necessária. Essas entradas produzem seletores de modelo quebrados e erros de tempo de execução que a descoberta deveria ter evitado.

O contrato prático é mais forte: cada modelo anunciado deve passar pelas mesmas verificações de admissão que se aplicariam a uma solicitação real.

Defina o que significa “disponível”

A existência do provedor é apenas uma entrada. Um modelo deve aparecer no catálogo padrão de uma chave somente quando todas as condições obrigatórias forem verdadeiras:

• O gateway tem um produto público configurado para o modelo.
• O inquilino, a equipe e a chave API têm direito a esse produto.
• O plano comercial aplicável permite seu uso.
• A política permite o modelo, o provedor, a região e o modo de tratamento de dados.
• Existe pelo menos uma implantação ou rota upstream compatível.
• Uma credencial de provedor utilizável está disponível para essa rota.
• A rota suporta pelo menos uma API superfície anunciada no catálogo.
• A rota está operacionalmente pronta de acordo com a política de integridade do gateway.

Expresso como uma operação de conjunto:

visible_models(key) =
  configured_products
  ∩ tenant_entitlements
  ∩ team_grants
  ∩ key_grants
  ∩ commercial_rights
  ∩ policy_eligible_routes
  ∩ compatible_deployments
  ∩ operationally_ready_routes

Esta é uma recomendação, não uma afirmação sobre o esquema OpenAI. O esquema padrão não define todos esses controles específicos do gateway. Eles pertencem ao plano de controle e ao compilador de catálogo do gateway.

Normalizar a descoberta de provedores sem proxy

Fato: APIs de descoberta de provedores expõem conceitos diferentes. A lista de modelos de OpenAI fornece identificadores e metadados básicos, mas não uma matriz de capacidade completa para cada superfície API. Anthropic distingue estados do ciclo de vida e pode retornar informações de capacidade mais ricas quando um modelo ou alias é recuperado. Gemini expõe campos como limites de token e métodos de geração suportados. O Microsoft Foundry pode exigir um nome de implantação no campo model, e uma implantação pode ser incompatível com um API específico, mesmo quando o modelo subjacente existir.

Consequentemente, o encaminhamento direto das respostas do provedor não é um design durável. Trate cada provedor API como uma fonte de reconciliação. Converta suas observações em um registro interno e combine-as com a configuração do gateway e a política de locatário.

Use um registro de catálogo canônico

Um registro interno útil separa o contrato público da implementação upstream:

{
  "catalog_revision": "cat_2026_11_05_0182",
  "public_model_id": "reasoning-large",
  "lifecycle": "active",
  "api_surfaces": ["chat.completions", "responses"],
  "input_modalities": ["text", "image"],
  "output_modalities": ["text"],
  "limits": {
    "context_tokens": 200000,
    "max_output_tokens": 32000
  },
  "capabilities": {
    "tools": true,
    "structured_output": true,
    "batch": false
  },
  "entitlement_profile": "advanced-reasoning",
  "routes": [
    {
      "provider": "provider-a",
      "target_type": "deployment",
      "target_id": "prod-reasoning-east",
      "region": "us-east",
      "state": "ready"
    }
  ]
}

Não exponha target_id, referências de credenciais ou estado de roteamento interno por meio do terminal público padrão. Esses campos são dados do plano de controle. Mantenha-os disponíveis para rotear admissão, ferramentas de suporte e atribuição de uso.

IDs, aliases e implantações separados

Um ID de modelo público é um contrato de cliente. Um ID de modelo de provedor identifica uma família ou versão de modelo upstream. Um nome de implantação identifica um recurso de serviço criado pelo operador. Eles não são intercambiáveis.

Resolva um alias público para uma revisão de catálogo imutável antes do roteamento. Registre o ID solicitado e o destino resolvido no evento de uso. Se o alias mudar posteriormente, a equipe de suporte ainda poderá reconstruir qual implantação processou uma chamada anterior.

Compilar o catálogo para a chave autenticada

O compilador do catálogo deve receber um principal autenticado, não apenas um ID de locatário. O mesmo locatário pode ter chaves de produção, chaves de desenvolvimento, chaves restritas de clientes e contas de serviço com diferentes concessões de modelo.

Uma sequência de compilação determinística é:

1. Carregue a revisão do catálogo base imutável.
2. Resolver associação de locatário, associação de equipe e concessões específicas de chave.
3. Aplicar restrições de plano, geografia, residência de dados e provedor.
4. Remova rotas sem credenciais válidas ou implantações compatíveis.
5. Avalie a preparação da rota usando o instantâneo de integridade atual.
6. Agregue rotas sobreviventes em registros de modelo público.
7. Retorne apenas API superfícies suportadas por pelo menos uma rota sobrevivente.

Use a semântica de interseção quando existirem concessões de equipe e de chave. Uma chave atribuída a uma equipa restrita não deve recuperar um acesso mais amplo apenas porque o inquilino possui um plano mais amplo. Isso torna o controle de acesso ao modelo de IA para equipes de software previsível e reduz a divulgação acidental.

Mantenha a lista e recupere comportamentos idênticos

GET /v1/models/{model} deve executar o mesmo predicado de autorização que a operação de lista. Caso contrário, um invasor poderá enumerar identificadores ocultos comparando respostas bem-sucedidas, proibidas e não encontradas.

Para um modelo que a chave não pode ver, retorne o mesmo erro público usado para um modelo desconhecido. Não revele se outro locatário pode usá-lo, qual provedor o hospeda ou qual direito o desbloquearia. APIs administrativas podem expor motivos mais detalhados aos operadores autorizados.

Representa API compatibilidade explicitamente

A existência de um modelo não implica suporte para todos os endpoints. Conclusões de bate-papo, respostas, incorporações, geração de imagens, tempo real, lote e Anthropic Mensagens têm diferentes contratos de solicitação e streaming.

A admissão da rota deve, portanto, aceitar um modelo e uma API superfície:

admit(key, public_model_id, api_surface, request_features)

O resultado deve identificar uma revisão de catálogo compatível e uma ou mais rotas elegíveis. Por exemplo, um modelo pode suportar chat.completions mas não responses, ou suportar Respostas apenas quando as ferramentas integradas estão ausentes. Um único booleano como supports_responses pode ser insuficiente quando a compatibilidade depende dos recursos solicitados.

Recomendação: publique recursos conservadores. Anuncie um recurso somente quando o gateway puder aplicá-lo no conjunto de rotas elegíveis ou puder selecionar uma rota que o suporte de forma determinística. Não infira entrada de imagem, chamada de ferramenta ou saída estruturada de um nome de família de provedor.

Preservar SDK compatibilidade ao adicionar metadados

Mantenha estáveis os campos padrão esperados pelos clientes compatíveis com OpenAI:

{
  "id": "reasoning-large",
  "object": "model",
  "created": 1793836800,
  "owned_by": "gateway",
  "x_gateway": {
    "catalog_revision": "cat_2026_11_05_0182",
    "lifecycle": "active",
    "api_surfaces": ["chat.completions", "responses"],
    "input_modalities": ["text", "image"],
    "availability": "available"
  }
}

Uma extensão com namespace reduz o risco de colisão, mas alguns clientes descartam campos desconhecidos. Se os aplicativos precisarem de dados de seleção detalhados, forneça um terminal de informações de modelo autenticado separado com um esquema com versão. Mantenha /v1/models pequeno o suficiente para SDKs, ferramentas de linha de comando e seletores de modelos.

Escolha listagens estáveis ou com filtro de integridade

Existem duas políticas de disponibilidade razoáveis.

Catálogo com filtro de integridade: oculta um modelo quando nenhuma rota está íntegra no momento. Isso minimiza chamadas com falha, mas os catálogos podem flutuar durante incidentes e invalidar seleções do lado do cliente.

Catálogo estável: continue listando os produtos autorizados enquanto relata availability: temporarily_unavailable. Isso é mais fácil para ferramentas de automação e migração, mas os clientes ainda poderão tentar chamadas, a menos que entendam a extensão.

Um padrão prático é ocultar modelos não implantados, proibidos, desativados ou com credenciais inelegíveis, mantendo modelos temporariamente indisponíveis com um status explícito para clientes confiáveis. O endpoint de compatibilidade mínima poderá omitir entradas indisponíveis se os clientes existentes não conseguirem interpretar os metadados de status.

Previsão: clientes de seleção de modelo mais ricos dependerão cada vez mais de metadados de capacidade e disponibilidade. Até que esse comportamento seja amplamente confiável, a admissão de rota no lado do servidor deve permanecer oficial.

Armazene catálogos compilados em cache sem fornecer concessões obsoletas

Compile catálogos fora do caminho da solicitação sempre que possível. Uma chave de cache deve incluir pelo menos:

(tenant_id, key_id, entitlement_version, catalog_revision, policy_revision)

Invalidar entradas afetadas quando a associação à equipe, concessões de modelo, planos de preços, credenciais do provedor, estado de implantação ou política de roteamento forem alterados. Valores de vida útil curtos não substituem eventos de revogação: mesmo uma breve janela obsoleta pode expor um modelo recém-proibido.

A reconciliação do provedor pode ser assíncrona. Durante uma interrupção do plano de controle do provedor, preserve o último catálogo conhecido, registre seu tempo de observação e evite que novas rotas incertas se tornem elegíveis. Isso mantém a listagem responsiva sem tratar a descoberta obsoleta como prova de que uma nova rota é utilizável.

Teste o catálogo como um contrato de admissão

A propriedade de conformidade mais forte é simples: para cada modelo e API superfície retornada a uma chave, a admissão de rota deve ser bem-sucedida no mesmo catálogo e revisão de integridade.

Adicione testes automatizados para:

• Uma chave permitida para ver e recuperar seus modelos atribuídos.
• Uma chave proibida que não vê entradas de lista nem metadados recuperáveis.
• As restrições da equipe restringem, em vez de ampliar, o acesso às chaves.
• Uma implantação somente de bate-papo que não está sendo anunciada para respostas.
• Uma credencial desativada removendo suas rotas dependentes.
• Um alias que resolve a revisão de catálogo imutável esperada.
• Um modelo retirado desaparecendo do catálogo padrão.
• Invalidação de cache após alteração de concessões, associações ou políticas.
• IDs de modelo desconhecidos e ocultos que produzem erros públicos indistinguíveis.
• Toda capacidade anunciada tem pelo menos uma rota qualificada.

As sondagens sintéticas podem adicionar evidências de que uma rota funciona, mas consomem cota, podem custar dinheiro e não podem cobrir todas as combinações de recursos. Use-os para classes de rota representativas e combine-os com estado de implantação, verificações de credenciais e integridade real do tráfego.

Registre evidências suficientes para explicar as decisões

Para cada solicitação aceita ou rejeitada, registre a revisão do catálogo, o ID do modelo público solicitado, API superfície, rota resolvida, contrato de capacidade, revisão da política e um motivo de admissão estruturado. Evite armazenar conteúdo de prompt exclusivamente para essa finalidade.

A sequência de implementação é simples: definir o registro canônico, construir reconciliadores de provedor, compilar visualizações por chave, criar lista e recuperar compartilhar um predicado de autorização, conectar a admissão de rota à mesma revisão e adicionar testes negativos antes de ativar caches. Uma vez que essas peças estejam no lugar, /v1/models se torna uma resposta confiável para “o que essa chave pode chamar?” em vez de um inventário pouco filtrado.

Leitura relacionada

• projetando uma camada de compatibilidade de respostasAPI