Migrando para um gateway de API compatível com OpenAI: crie um contrato de compatibilidade antes de inverter o URL base

Alterar base_url, api_key e model geralmente é suficiente para fazer uma simples demonstração de bate-papo funcionar em uma API compatível com OpenAI. Não basta provar que uma migração de produção é segura.

As falhas geralmente aparecem mais tarde: chamadas de ferramentas transmitidas chegam em uma forma diferente, um modo de esquema JSON é ignorado, um modelo de embeddings retorna um tamanho de vetor diferente, campos de uso estão faltando, novas tentativas de envio duplo de um efeito colateral ou uma opção de raciocínio específica do provedor silenciosamente não faz nada. O objetivo prático não é perguntar se um endpoint é “compatível com OpenAI” em abstrato. O objetivo é definir de quais partes do contrato em formato OpenAI seus aplicativos dependem, testar essas partes e rotear através de um gateway somente depois que o contrato for explícito.

Este guia mostra como migrar uma equipe de SDKs específicos do provedor ou endpoints compatíveis dispersos para um gateway compatível com OpenAI, preservando a confiabilidade, a atribuição de uso e as opções de reversão.

O que são fatos, recomendações e previsões nesta migração?

Fatos: vários provedores documentam caminhos compatíveis com OpenAI ou uso de SDK para partes de suas APIs. O Google documenta o acesso do Gemini por meio de bibliotecas OpenAI Python e TypeScript e REST, alterando a chave da API, URL base e modelo, ao mesmo tempo que recomenda o uso direto da API Gemini para aplicativos que ainda não usam bibliotecas OpenAI. A documentação de compatibilidade do Gemini cobre conclusões de bate-papo, streaming, chamada de função, compreensão de imagem, incorporações, mapeamentos de esforço de raciocínio e opções específicas do provedor por meio de corpos de solicitação extras. Together AI documenta a compatibilidade OpenAI REST e SDK para múltiplas modalidades, mas sua matriz também lista superfícies em formato OpenAI não suportadas, como assistentes, threads e execuções. Mistral documenta um caminho de migração para clientes compatíveis com OpenAI alterando o URL base e o nome do modelo. Groq expõe terminais de conclusão de bate-papo do caminho OpenAI. vLLM oferece um servidor compatível com OpenAI para conclusões e bate-papo, enquanto documenta diferenças de parâmetros. A documentação do OpenAI Agents SDK alerta que muitos provedores que não são OpenAI ainda não oferecem suporte à API Responses mais recente e que o modo Chat Completions costuma ser o alvo de compatibilidade mais seguro.

Recomendações: trate a compatibilidade como um contrato de aplicativo testado. Faça um inventário dos endpoints e recursos exatos que seus aplicativos usam, crie uma matriz de capacidade de provedor e modelo, escreva testes de conformidade antes da migração de tráfego, normalize diferenças conhecidas de solicitação e resposta no limite do gateway e implemente chaves e perfis de reversão por aplicativo.

Predição: as superfícies compatíveis com OpenAI continuarão úteis como uma camada de integração de menor atrito, mas os recursos nativos do provedor continuarão a divergir. As equipes que mantêm um contrato de compatibilidade serão capazes de adotar novos modelos mais rapidamente do que as equipes que dependem de suposições informais de “substituição imediata”.

Etapa 1: inventariar todas as chamadas de IA atuais

Comece com um inventário, não com alterações de código. Uma migração falha quando as equipes presumem que todas as chamadas de IA parecem conclusões de chat e descobrem dependências ocultas somente após o lançamento.

Crie uma linha por site de chamada. Inclua trabalhos agendados, ferramentas internas, notebooks, trabalhadores em segundo plano, equipamentos de avaliação e serviços voltados para o cliente.

app: assistente de suporte
proprietário: plataforma do cliente
provedor_atual: provedor_a
current_sdk: provedor_a_python_sdk
endpoint_shape: chat.completions
modelo: provedor-a-large-2026
recursos:
  - transmissão
  - chamadas de ferramentas
  -json_schema_output
  - utilização_contabilidade
latência_orçamento_ms: 8.000
retry_policy: retry_429_5xx_no_tool_side_effects
mensal_volume_estimate: 2,4 milhões de solicitações
rollback_contact: plataforma oncall-customer

Classifique cada chamada por endpoint e recurso, não apenas por modelo. Um único nome de modelo pode ocultar requisitos de compatibilidade muito diferentes, dependendo de como é usado.

Lista de verificação de inventário

• Bate-papo: mensagens, instruções do sistema, temperatura, top-p, tokens máximos, sequências de parada.
• Streaming: analisador de eventos enviados pelo servidor, blocos finais, uso no stream, comportamento de cancelamento.
• Ferramentas: esquemas de funções, chamadas paralelas, argumentos JSON, mensagens de resultados de ferramentas, segurança de efeitos colaterais.
• Saídas estruturadas: modo JSON, esquema JSON, validação estrita, lógica de reparo de fallback.
• Visão ou entrada multimodal: URL da imagem, base64, tratamento MIME, parâmetros de detalhe.
• Embeddings: ID do modelo, dimensão vetorial, expectativas de normalização, compatibilidade de índice.
• Arquivos e lote: upload de APIs, pesquisa de empregos, cancelamento, formatos de saída.
• Controles de raciocínio: esforço de raciocínio, orçamento de raciocínio, tokens ocultos, configurações específicas do provedor.
• Erros: formato de limite de taxa, formato de tempo limite, erros de política de conteúdo, códigos de status repetíveis.
• Uso e cobrança: tokens de prompt, tokens de conclusão, tokens em cache, tokens de raciocínio, tags de alocação de custos.

A saída desta etapa é um mapa de dependências. Ele informa quais aplicativos podem migrar com um perfil de API simples compatível com OpenAI e quais aplicativos precisam de adaptador.

Etapa 2: construir uma tabela de contrato de compatibilidade

Um contrato de compatibilidade é uma tabela que diz, para cada funcionalidade da aplicação, o que o gateway deve garantir e como você irá testá-lo. Deve ser específico o suficiente para que as equipes de engenharia e de produto tomem decisões de implementação.

Essa tabela também evita promessas exageradas. Se um provedor oferece suporte a chat e incorporações, mas não a um fluxo de trabalho semelhante a arquivos ou assistentes, o contrato deve indicar isso. “Não suportado” é um resultado de migração válido quando evita uma surpresa na produção.

Etapa 3: crie perfis de modelo em vez de espalhar IDs de modelo

Não substitua um ID de modelo codificado por outro ID de modelo codificado em todos os aplicativos. Use perfis de modelo.

perfil: support-chat-fast
openai_model_alias: suporte-chat-rápido
provedor: provedor_b
provedor_model: provedor-b/chat-large-fast
ponto final: chat.completions
recursos:
  streaming: verdadeiro
  ferramentas: verdadeiro
  saídas_estruturadas: esquema_validado
  visão: falsa
  incorporações: falsas
política_de_solicitação:
  drop_unsupported_params: falso
  rejeitar_unknown_params: verdadeiro
  pass_through_extra_body: ["reasoning_effort"]
fallback_profile: suporte-chat-seguro
cost_center_required: verdadeiro

Este perfil fornece aos aplicativos um nome estável enquanto o gateway possui o mapeamento do provedor. Ele também lida com provedores que usam IDs de modelo com namespace em vez de um namespace de modelo simples. O aplicativo pede support-chat-fast; o gateway decide se isso atualmente é mapeado para um modelo com namespace no estilo Together, um modelo compatível com Gemini, um modelo compatível com Mistral, um modelo de chat Groq, um endpoint vLLM auto-hospedado ou outro destino aprovado.

A compensação são as despesas gerais de governança. Os perfis devem ser documentados, revisados ​​e versionados. A vantagem é que migrações, reversões e substituições de modelos não exigem a reimplantação de todos os aplicativos.

Etapa 4: escrever testes de conformidade antes da migração

Os testes de conformidade são verificações pequenas e repetíveis que verificam seu contrato em relação a cada perfil alvo. Eles devem ser executados antes da primeira implementação e sempre que um provedor, modelo, SDK ou adaptador de gateway for alterado.

Conjunto mínimo de testes

• Testes de prompt de ouro: envie prompts determinísticos e verifique o formato da resposta, o motivo do término, o comportamento de segurança e os requisitos semânticos básicos. Não exija palavras exatas, a menos que a aplicação realmente dependa disso.
• Testes de analisador de streaming: confirme se seu cliente consegue analisar cada parte, reconstruir o texto final, lidar com o cancelamento e detectar a conclusão da transmissão.
• Percursos de chamada de ferramenta: força uma chamada de ferramenta, analisa os argumentos, executa uma ferramenta falsa, retorna o resultado da ferramenta e confirma se o modelo continua corretamente.
• Testes de streaming de chamada de ferramenta: verifique se os deltas de argumentos parciais podem ser armazenados em buffer e reconstruídos antes da execução da ferramenta. Caso contrário, desative a execução incremental da ferramenta para esse perfil.
• Validação do esquema JSON: teste saída válida, saída inválida, campos ausentes, campos extras e casos de recusa ou erro.
• Verificações de dimensão incorporada: confirme o comprimento do vetor, o tipo numérico e a compatibilidade com o índice do vetor de destino antes de reutilizar um índice existente.
• Testes de repetição e idempotência: simulam falhas de fluxo 429, 500, de tempo limite e parciais. Certifique-se de que os efeitos colaterais da ferramenta não se repitam acidentalmente.
• Reconciliação de uso: compare os registros de uso do gateway com os campos de uso informados pelo provedor e suas expectativas de faturamento.

Mantenha os testes próximos aos padrões de tráfego de produção. Um único prompt “escreva um poema” não prova quase nada sobre um fluxo de trabalho que depende de ferramentas, JSON, incorporações e contabilidade de uso.

Etapa 5: normalizar peculiaridades no limite do gateway

Um gateway compatível com OpenAI deve reduzir as alterações no código do aplicativo, mas não deve fingir que todos os provedores se comportam de forma idêntica. Use adaptadores para diferenças conhecidas e torne o comportamento visível.

Solicitar normalização

• Alias de modelo: mapeie nomes de perfis estáveis voltados para aplicativos para IDs de modelo específicos do provedor.
• Parâmetros não suportados: rejeita parâmetros não suportados com um erro claro por padrão. A eliminação silenciosa é conveniente durante as demonstrações e perigosa na produção.
• Opções específicas do provedor: permitir campos de passagem controlados, como controles de raciocínio ou pensamento, apenas em perfis de modelos documentados.
• Conversão de mensagens: normalize as mensagens do sistema, desenvolvedor, usuário, assistente e ferramenta onde o provedor de destino espera um formato diferente.
• Orçamentos de tempo limite: aplique um prazo no nível do aplicativo em vez de permitir que os padrões do SDK se acumulem.

Normalização de resposta

• Escolhas de texto e ferramentas: retorna uma forma consistente para texto do assistente, chamadas de ferramentas e motivos de finalização.
• Blocos de streaming: normalize deltas comuns e documente onde o buffer é necessário.
• Campos de uso: armazena o uso nativo do provedor, além de prompts normalizados, conclusão e contagens totais de tokens, quando disponíveis.
• Forma do erro: mapeie códigos de status, capacidade de repetição, código de erro do provedor e ID de solicitação em um esquema de erro.
• Metadados de custo: anexe rótulos de aplicativo, equipe, perfil, provedor, modelo e ambiente para análise posterior.

A principal compensação é a portabilidade versus o poder do provedor. A normalização para a menor superfície comum melhora a intercambialidade. Permitir campos específicos do provedor preserva recursos avançados, mas cada opção de passagem torna-se parte da documentação do perfil e da matriz de teste.

Etapa 6: implementação com chaves por aplicativo e perfis de reversão

A migração deve ser reversível sem reimplantação de código. Use chaves de API separadas para cada aplicativo, ambiente e equipe. Uma única chave compartilhada dificulta a atribuição de uso e a reversão de emergência.

Uma sequência de implementação segura é semelhante a esta:

1. Perfil de desenvolvimento: roteia apenas o tráfego local e de teste através do gateway. Corrija problemas de formato de solicitação e analisador.
2. Testes de sombra: reproduz solicitações de representantes para o novo perfil sem afetar a saída visível ao usuário. Compare a validade do esquema, o comportamento da ferramenta, a classe de latência e os campos de uso.
3. Pequena fatia de produção: mova uma baixa porcentagem de tráfego ou um locatário interno. Observe erros, novas tentativas, sinais de qualidade voltados para o usuário e custos.
4. Expansão por aplicativo: migre um aplicativo por vez. Não migre chat, incorporações, lotes e arquivos juntos, a menos que compartilhem o mesmo perfil de risco.
5. Perfil de reversão: mantenha um perfil de provedor/modelo em bom estado disponível com o mesmo alias voltado para o aplicativo ou uma mudança rápida de configuração.
6. Bloqueio pós-migração: quando estiver estável, remova as chaves diretas do provedor dos ambientes de aplicativos para que o tráfego não possa ignorar os controles do gateway.

A reversão deve ser testada como qualquer outro caminho. Se um perfil de modelo puder ser alternado no gateway, teste essa alternância durante um período de silêncio e confirme se os registros do aplicativo, a análise de uso e a atribuição de faturamento permanecem coerentes.

Exemplo: substituição de endpoints dispersos por um contrato de gateway

Suponha que uma equipe tenha três aplicativos:

• Um assistente de suporte ao cliente usando bate-papo e ferramentas de streaming.
• Um classificador de conteúdo que exige saída JSON estrita.
• Um serviço de pesquisa que usa embeddings armazenados em um banco de dados vetorial.

Uma migração arriscada mudaria todos os três aplicativos para o mesmo URL base e escolheria três novos IDs de modelo. Uma migração mais segura separa os contratos:

• perfil de bate-papo de suporte: requer streaming, chamadas de ferramentas, deltas de chamadas de ferramentas em buffer, classificação de novas tentativas e registro de uso.
• perfil classifier-json: requer validação de esquema, tratamento de recusa e nenhuma eliminação silenciosa de parâmetros.
• perfil de incorporação de pesquisa: requer uma dimensão vetorial fixa e um plano de migração de índice se a dimensão mudar.

Cada perfil recebe seus próprios testes de conformidade e implementação. O assistente de suporte pode precisar de trabalho no adaptador de streaming. O classificador poderá passar rapidamente se a validação do esquema for externa ao modelo. O serviço de incorporação pode exigir um novo índice em vez de uma troca de modelo local. O gateway fornece à equipe um URL base compatível com OpenAI, mas o contrato de compatibilidade mantém a migração honesta.

Lista de verificação de migração

• Liste todos os sites de chamadas de IA, incluindo trabalhos em segundo plano e scripts internos.
• Classifique as chamadas por endpoint, recurso, modelo, proprietário e caminho de reversão.
• Defina perfis de modelo voltados para aplicativos em vez de IDs de modelo de provedor codificados.
• Crie uma matriz de capacidade para cada fornecedor e perfil de modelo.
• Rejeite parâmetros não suportados, a menos que um perfil permita explicitamente a passagem.
• Teste streaming, ferramentas, resultados estruturados, incorporações, erros, novas tentativas e campos de uso.
• Use chaves de API por aplicativo e por ambiente para atribuição e controle.
• Execute testes de sombra antes do tráfego de produção visível ao usuário.
• Implante um aplicativo ou classe de recursos por vez.
• Mantenha um perfil de reversão testado disponível sem reimplantações de código.

Conclusão acionável

Um gateway de API compatível com OpenAI é mais valioso quando se torna uma camada de migração controlada, e não apenas uma URL diferente. A opção de URL base reduz alterações mecânicas de código. O contrato de compatibilidade reduz o risco operacional.

Antes de inverter o tráfego de produção, anote o que seus aplicativos realmente exigem: comportamento de streaming, semântica da ferramenta, garantias de esquema, dimensões de incorporação, regras de repetição, campos de uso e significados de erros. Converta esses requisitos em perfis de modelo, regras de adaptador e testes de conformidade. Em seguida, implemente chaves, análises e perfis de reversão por aplicativo.

Se o caminho simples do chat funcionar, trate-o como um bom começo. Trate o restante da migração como um trabalho de engenharia que merece a mesma disciplina que uma mudança de banco de dados, fila ou provedor de pagamentos.

Leitura relacionada

• validação de saída estruturada em vários provedores de modelo
• substituição de modelo e runbook de reversão
• análise de uso e reconciliação de token em um gateway