Um aplicativo integrando GPT, Claude e Gemini ao mesmo tempo: 6 tipos de problemas de compatibilidade a resolver na troca de modelos

Nota do autor: aplicações com múltiplos modelos devem usar um formato unificado de mensagens, uma camada de adaptação de provedores e um registro de capacidades para lidar com diferenças em chamadas de ferramentas, estado de raciocínio, saída em streaming, dados estruturados e cache.

GPT, Claude e Gemini dão conta de chamadas de texto comuns; Claude e Gemini também oferecem endpoints oficiais compatíveis com o SDK da OpenAI. Em aplicações de nível de produção, ao trocar de modelo, é preciso resolver 6 categorias de problemas de compatibilidade: papéis de mensagem e instruções de sistema, protocolo de chamada de ferramentas, parâmetros de raciocínio e estado de pensamento, eventos de streaming, saída estruturada e multimodalidade, cobrança de cache e tratamento de erros. Trocar apenas o ID do modelo faz uma sessão simples de perguntas e respostas funcionar, mas chamadas de ferramentas em múltiplos turnos, recuperação de streaming interrompido e cálculo de custos exigem tratamento separado. A solução de engenharia mais robusta é “interface de negócio unificada + camada de adaptação de provedores (Provider Adapter) + registro de capacidades do modelo”. Assim, a troca de modelo pode ser gerenciada como uma funcionalidade de produto sustentável.

A seguir, comparamos as diferenças estruturais entre as APIs nativas dos três provedores e mostramos quais cenários os endpoints compatíveis com OpenAI conseguem cobrir. Depois, detalhamos uma a uma as falhas reais que as 6 categorias de problemas de compatibilidade podem provocar, e apresentamos uma arquitetura de integração em seis camadas e um código executável de chamada unificada. Por fim, listamos seis testes de compatibilidade antes do lançamento e explicamos como o gateway de API unificado e a adaptação de capacidades nativas dividem as responsabilidades.

Para saber: Glossário de termos de compatibilidade de API multi-modelo

1 Compatibilidade de API entre múltiplos modelos: por que trocar de modelo não é só trocar o Model ID

Os três serviços permitem especificar o modelo por meio de um campo model, mas a forma como organizam o corpo da requisição, o objeto de resposta e o estado de contexto é diferente. Em perguntas e respostas simples, as diferenças se concentram nos nomes dos campos, e o custo de adaptação é baixo. Em aplicações do tipo agente, que dependem de chamadas de ferramentas, estado de raciocínio e eventos de streaming, as diferenças se transformam diretamente em falhas em produção.

1.1 Comparativo das APIs nativas de GPT, Claude e Gemini

A tabela abaixo descreve apenas as APIs nativas, sem considerar qualquer camada de compatibilidade ou endpoint de gateway.

Como dá para ver na tabela acima, as três empresas se dividem em duas abordagens quanto a “quem armazena o contexto”. OpenAI e Gemini oferecem continuação de contexto no servidor, enquanto Claude Messages deixa o reenvio do histórico por conta da aplicação. Se o armazenamento de sessão da aplicação for projetado para apenas um desses modos, trocar para outra empresa causará perda de contexto ou envio duplicado.

1.2 Até que ponto a interface compatível com OpenAI resolve o problema

Claude e Gemini oferecem endpoints compatíveis com o SDK da OpenAI. O endpoint oficial de compatibilidade do Gemini é generativelanguage.googleapis.com/v1beta/openai/; ao usar o cliente OpenAI, basta alterar base_url, a chave API e model. Já a documentação de compatibilidade do Claude delimita claramente o escopo de suporte. As limitações conhecidas em 2026-11-13 são:

• O parâmetro strict na definição de ferramentas é ignorado, então a validação rigorosa dos parâmetros de ferramentas deixa de funcionar.
• Não há suporte a Prompt Caching.
• Não há suporte a entradas dos tipos audio e file.
• As mensagens system e developer são movidas para o início e mescladas.
• Os campos relacionados a thinking diferem da API nativa.

A interface compatível atende bem a três tipos de cenário: chat comum, geração em turno único e comparação rápida da qualidade das respostas entre modelos. A migração de agentes complexos envolve parâmetros rigorosos de ferramentas, cache, entrada de arquivos e estado de raciocínio em múltiplos turnos; esses recursos exigem voltar à API nativa ou validar item por item antes de ir para produção. Um critério prático é: se um recurso do qual a aplicação depende aparece apenas na documentação nativa, registre-o no catálogo de capacidades e deixe que um adaptador dedicado cuide dele.

2 As seis categorias de problemas de compatibilidade mais comuns ao alternar entre os modelos GPT, Claude e Gemini

2.1 Tratamento de compatibilidade entre papéis de mensagem e instruções de sistema

A OpenAI diferencia papéis como developer e system. As instruções system do Claude ficam fora do array de mensagens. O Gemini usa system_instruction, e o conteúdo do usuário e do modelo também segue regras estruturais próprias. Os três expressam a mesma ideia de “prioridade de instruções + histórico multiturno”, mas os campos que carregam essas informações ficam em posições diferentes.

Uma falha comum vem de uma concatenação preguiçosa: juntar instruções de sistema, mensagens do histórico e resultados de ferramentas em uma única string e entregar tudo ao modelo como entrada do usuário. Isso até funciona, mas a prioridade das instruções fica enfraquecida, e o modelo pode tratar a saída de ferramentas no histórico como uma nova solicitação do usuário. O caminho correto é preservar a semântica de papéis dentro da aplicação e deixar o adaptador fazer o mapeamento para os campos de cada fornecedor. Além disso, vale lembrar que a camada de compatibilidade do Claude mescla system e developer; o design de comandos que depende da separação entre os dois precisa ser validado na prática.

2.2 Protocolo de invocação de ferramentas e tratamento de compatibilidade dos IDs de chamada

Os três modelos suportam Function Calling, e o fluxo de invocação acontece mais ou menos assim:

A camada de ferramentas precisa guardar integralmente seis informações: o ID da chamada, o nome da função, o JSON dos parâmetros, a relação entre chamadas paralelas, o resultado da execução e se o modelo exige que o raciocínio continue. Chamadas paralelas são o ponto mais propenso a erro. O modelo dispara várias solicitações de ferramentas de uma vez, e a aplicação devolve o resultado de apenas uma delas, ou associa o resultado ao ID errado; na rodada seguinte a requisição acaba em erro de parâmetros, ou o modelo continua respondendo com base em dados incorretos.

A recomendação é que a camada de ferramentas unificada valide os parâmetros primeiro com JSON Schema e só depois execute a operação externa real. Os parâmetros gerados pelo modelo nem sempre são válidos, e a validação antecipada barra o erro antes de “chamar o sistema externo”.

2.3 Compatibilidade entre modos de raciocínio e estado de contexto

Os nomes e significados dos parâmetros de raciocínio não são equivalentes entre os três provedores:

• OpenAI: usa parâmetros como reasoning.effort. GPT-6 Astra e GPT-6.1 Sol não aceitam reasoning.effort=none, e nesses dois modelos a chamada de ferramentas também exige a Responses API.
• Claude: os modelos de nova geração adotam principalmente o Adaptive Thinking, combinado com configurações de raciocínio como effort. Alguns modelos novos já não oferecem o modo antigo de raciocínio manual com budget_tokens fixo.
• Gemini: modelos diferentes usam thinking level ou budget; se é possível desligar o raciocínio e quais níveis existem varia de modelo para modelo. As regras de mapeamento de parâmetros da API nativa também são diferentes das da entrada compatível com OpenAI.

Quando a interface do produto define três níveis de intensidade de raciocínio — “rápido, padrão e aprofundado” —, o nome do nível expressa a intenção do produto. O adaptador precisa traduzi-lo para os parâmetros que cada modelo realmente aceita, e os recursos computacionais que cada provedor entrega no mesmo nível também não são iguais. Além disso, o resumo de raciocínio que o usuário enxerga pode não bater com a quantidade de tokens de raciocínio efetivamente cobrada; a contabilização de custos deve se basear no campo de uso retornado pela interface.

O estado criptografado nas chamadas de ferramentas de múltiplos turnos é o ponto que Agents de longa duração mais costumam ignorar:

• Itens de reasoning e chamadas de ferramentas do OpenAI Responses podem precisar ser propagados junto com o histórico.
• Blocos thinking / redacted_thinking do Claude podem conter estado criptografado; ao devolvê-los após a execução da ferramenta, é preciso manter a estrutura original.
• O modo stateless do Gemini Interactions exige preservar literalmente os blocos thought e as assinaturas; no modo stateful, parte do estado pode ser mantida pelo servidor.

Guardar apenas o texto exibido na janela de chat não é suficiente para restaurar por completo o histórico de raciocínio do modelo. A falha típica é: o Agent dá erro de repente depois da terceira rodada de chamadas de ferramentas, ou começa a repetir passos já concluídos. A causa costuma ser o bloco de assinatura perdido em alguma rodada intermediária.

2.4 Unificação dos eventos de streaming

Cada um dos três provedores tem seus próprios tipos de evento de streaming, ordem e sinal de encerramento. O OpenAI Responses pode emitir response.output_text.delta, incrementos de chamada de ferramenta e o evento de conclusão da response. O stream do Claude Messages usa eventos como message_start, content_block_delta e message_delta. A API nativa do Gemini usa sua própria estrutura de saída e de etapas.

Se o frontend parseia os eventos brutos de cada fornecedor, cada modelo novo integrado exige uma alteração no código do frontend. A recomendação é o backend converter tudo para um protocolo interno de eventos:

Existem três pontos de falha recorrentes no processamento de streaming. Primeiro, os fragmentos de parâmetros de várias chamadas de ferramenta chegam intercalados e concatenar na ordem de chegada embaralha os IDs. Segundo, os parâmetros JSON são cortados em qualquer caractere; tentar parsear com apenas metade recebida lança exceção. Terceiro, a conexão cai no meio do caminho sem que o evento de conclusão chegue, e a interface fica travada em “gerando”. A camada de conversão precisa tratar explicitamente esses três casos.

2.5 Saída estruturada com JSON Schema e diferenças de capacidade multimodal

As três oferecem capacidade de saída estruturada, mas existem diferenças nas características de JSON Schema suportadas, no modo estrito e na forma de combinar isso com a invocação de ferramentas. A documentação oficial do Claude distingue dois mecanismos: JSON outputs restringe a estrutura da resposta final, enquanto Strict tool use restringe a estrutura dos parâmetros de invocação de ferramentas. Alguns modelos, ao usar o formato estrito, ainda geram custos extras de compilação ou cache do Schema.

A recomendação de engenharia é: o aplicativo mantém um JSON Schema padrão próprio e registra, na tabela de registro de capacidades, quais características de Schema cada modelo suporta. Para características não suportadas, o adaptador faz uma conversão de degradação. Por mais rígido que o modelo se declare, o lado da aplicação deve fazer mais uma validação; quando a validação falha, entra em um fluxo controlado de nova tentativa ou de erro.

O mesmo vale para multimodalidade. “Suporta entrada de imagens” indica apenas a categoria da capacidade; na prática, ainda é preciso comparar os seguintes pontos: tipos de arquivo aceitos, tamanho e quantidade de imagens, capacidades de vídeo e áudio, forma de upload de arquivos, limite da janela de contexto longa e faixa realmente utilizável, máximo de tokens de saída, e se a invocação de ferramentas pode ser combinada com entradas multimodais. O fato de a camada de compatibilidade do Claude não suportar entradas audio e file é exatamente uma limitação concreta que precisa ser registrada na tabela.

2.6 Diferenças entre modelos em cache, cobrança e tratamento de erros

Os mecanismos de cache de prompts dos três fornecedores são bem diferentes:

• OpenAI: o GPT-5.6 e os modelos seguintes oferecem cache implícito e pontos de quebra (breakpoints) de cache explícito, com TTL de 30 minutos ou 12 horas.
• Claude: usa cache_control para indicar cache automático ou explícito, com dois modos, de 5 minutos e de 1 hora; esse recurso não é suportado na sua camada compatível com OpenAI.
• Gemini: os modelos novos têm cache implícito automático, e algumas APIs e modelos permitem criar objetos de cache de forma explícita.

Depois de trocar de modelo, o cache do fornecedor anterior normalmente não pode ser reaproveitado. Se você migrar de Claude para Gemini no meio de uma conversa, a primeira requisição será cobrada pelo input completo. E se a estimativa de custo assumir por padrão que “o cache sempre acerta”, quanto mais frequente for a troca de estratégia, maior será a diferença na conta.

Os preços unitários padrão de cada fornecedor também variam bastante. Os preços oficiais de tabela, em 2026-11-13, são os seguintes (USD / milhão de tokens):

Esta tabela serve apenas para ilustrar as diferenças de cobrança. Cada modelo tem capacidades e condições de uso distintas, e preço mais alto ou mais baixo não se converte diretamente em comparação de desempenho. A tabela também não inclui custos de gravação em cache, chamadas de ferramentas, níveis de serviço nem acréscimos de terceiros.

💰 Sugestão para cálculo de custos: a conta de uma aplicação multimodelo precisa ser registrada por item: “input normal, gravação em cache, acerto de cache, pensamento e saída, custos de ferramentas, adicional de contexto longo”. Ao chamar vários modelos de forma unificada através do APIYI apiyi.com, você pode ver o consumo de cada modelo em um só lugar, o que facilita relacionar a estratégia de roteamento com o custo real.

No tratamento de erros, os três fornecedores diferem em taxa de requisições, taxa de tokens, cotas, timeouts e formato de erro. A aplicação deve estabelecer uma classificação unificada de erros: falha de autenticação, modelo não suportado, parâmetros inválidos, requisição grande demais ou acima do contexto, 429 (limite de requisições), erro no servidor, desconexão de rede, interrupção do stream de resposta, falha em chamada de ferramenta.

O fallback entre modelos também precisa considerar se a tarefa tem efeitos colaterais. Se o modelo principal der timeout depois que a ferramenta já foi executada, e o sistema trocar automaticamente para o modelo de reserva reexecutando toda a tarefa, operações como pagamentos, envio de e-mails ou alteração de arquivos podem acontecer duas vezes. A solução é adicionar chaves de idempotência às ferramentas com efeitos colaterais e, no fallback, continuar apenas a partir das “etapas ainda não executadas”.

3 Como projetar uma arquitetura de API compatível com múltiplos modelos

A estrutura recomendada em seis camadas é a seguinte:

1. Interface de negócios: perguntas dos usuários, upload de materiais, seleção de modelo e tarefa.
2. Formato de requisição unificado: usar uma estrutura unificada para representar o histórico de mensagens, anexos, lista de ferramentas, requisitos de saída estruturada, intensidade de raciocínio e ID da tarefa.
3. Roteamento de modelos: selecionar GPT, Claude ou Gemini com base em preço, capacidade, latência, disponibilidade e regras de negócio.
4. Provider Adapter: converter a requisição padrão no formato nativo de cada fornecedor e, em seguida, mapear o resultado retornado de volta para o formato interno.
5. Execução de ferramentas e gerenciamento de estado: manter IDs de chamada, registros de execução, contexto da conversa, estado de raciocínio do fornecedor, cache e recuperação de falhas.
6. Logs e contabilidade de custos: registrar, em cada requisição, o modelo, os tokens, o custo real, a latência, o cache, os erros e as chamadas de ferramentas.

3.1 Estabelecer um formato unificado de mensagens e ferramentas

O princípio central do formato unificado é armazenar o histórico em duas camadas. A primeira camada é o histórico padrão universal, que inclui mensagens do usuário, a resposta final do modelo, solicitações de ferramentas e resultados de ferramentas — algo que qualquer fornecedor consegue entender. A segunda camada é o estado exclusivo do fornecedor, como itens de reasoning, assinaturas de thinking e blocos de thought, armazenados de forma isolada por fornecedor e retornados como estão somente ao fazer uma requisição para o mesmo fornecedor.

from dataclasses import dataclass, field
from typing import Any, Literal

@dataclass
class ToolCall:
    call_id: str              # ID de chamada unificado; o adaptador é responsável por mapear mutuamente com o ID do fornecedor
    name: str
    arguments: dict[str, Any]
    result: Any = None
    idempotency_key: str = "" # ferramentas com efeitos colaterais devem definir

@dataclass
class Message:
    role: Literal["system", "developer", "user", "assistant", "tool"]
    content: list[dict]                      # blocos multimodais, como texto e imagens
    tool_calls: list[ToolCall] = field(default_factory=list)
    # estado exclusivo do fornecedor: a chave é o nome do fornecedor; o valor são blocos de assinatura / reasoning salvos como estão
    vendor_state: dict[str, Any] = field(default_factory=dict)

Ao trocar de modelo, o adaptador lê os campos padrão para gerar uma nova requisição. As partes de vendor_state pertencentes a outros fornecedores não são enviadas; as partes pertencentes ao fornecedor de destino são retornadas como estão.

3.2 Adaptando APIs nativas por meio de Provider Adapters

Cada adaptador tem três responsabilidades:

• Conversão de entrada: mapeamento de papéis (por exemplo, mover o system para o campo separado do Claude), conversão das definições de ferramentas, degradação de Schema e mapeamento de níveis de raciocínio.
• Conversão de saída: transformar as respostas nativas e os eventos de streaming nos eventos internos da seção 2.4, mapeando os IDs de chamada de ferramenta para um ID unificado.
• Tratamento de estado: extrair e salvar estados do fornecedor, como assinaturas e itens de reasoning, decidindo entre continuidade do lado do servidor (previous_response_id, previous_interaction_id) ou reenvio completo do histórico.

Perguntas e respostas comuns podem usar o adaptador público no formato compatível com OpenAI. Cenários que exigem parâmetros de ferramenta rígidos, controle de cache ou estado de pensamento criptografado devem implementar adaptadores nativos separados. Assim você mantém a conveniência de um único ponto de entrada e dá aos recursos avançados um lugar claro para morar.

3.3 Decidindo os recursos disponíveis com um registro de capacidades

O registro de capacidades anota o suporte real por unidade de “modelo + endpoint de acesso”. Um mesmo modelo pode gerar duas entradas: uma para o caminho nativo e outra para a camada de compatibilidade. Veja abaixo um exemplo de estrutura; os valores concretos precisam se basear na documentação oficial e nos resultados dos seus próprios testes:

gpt-6.1-sol@responses:
  tools: true
  tool_api: responses          # a chamada de ferramentas exige a API Responses
  reasoning_effort: [low, medium, high]   # não aceita none
  vendor_state: reasoning_items
claude-sonnet@openai-compat:
  tools: true
  strict_tools: false          # a camada de compatibilidade ignora strict
  prompt_caching: false
  file_input: false
  merges_system_developer: true
gemini-flash@interactions:
  tools: true
  builtin_tools: [google_search, url_context, code_execution]
  vendor_state: thought_signatures

A camada de roteamento consulta o registro antes de escolher o modelo. Se a requisição trouxer arquivo, ela exclui as entradas com file_input: false; se precisar de parâmetros de ferramenta rígidos, seleciona apenas as entradas com strict_tools: true. A interface do produto também pode se basear nisso para ocultar opções que o modelo atual não suporta, reduzindo os erros que o usuário acaba disparando.

4 Testes e observação antes do lançamento da compatibilidade multi-modelo da API

4.1 Seis testes de compatibilidade, de perguntas simples a cadeias de ferramentas com múltiplos turnos

Em ordem crescente de complexidade, execute os seis testes a seguir:

1. Perguntas e respostas simples: envie o mesmo comando para os três modelos e verifique se o conteúdo da resposta e as estatísticas de tokens estão normais.
2. Saída em streaming: confirme que a saída chega de forma contínua e que o sinal de encerramento correto é recebido.
3. Chamada de ferramentas: o modelo chama a ferramenta de consulta de clima ou de consulta de dados; a aplicação executa e devolve o resultado.
4. Loop de múltiplas ferramentas: chame ferramentas por duas rodadas consecutivas ou mais e confirme que o histórico e os IDs de chamada estão completos.
5. JSON estruturado: produza a saída conforme o mesmo Schema e valide a estrutura com o validador do lado da aplicação.
6. Troca de modelo: a mesma sessão de negócio alterna entre GPT, Claude e Gemini; confirme que o contexto, o histórico de ferramentas e a resposta final estão normais.

Os itens 4 e 6 são os que mais expõem problemas de estado de raciocínio; recomenda-se incluí-los no pipeline de integração contínua. Sempre que atualizar a versão do modelo ou trocar o endpoint de acesso, execute-os novamente.

4.2 Criar uma observação unificada de custo e estabilidade

Para cada requisição, registre pelo menos os seguintes campos: modelo e endpoint, taxa de sucesso das requisições, tipo de exceção (conforme a classificação da seção 2.6), latência até o primeiro token e tempo total da tarefa, tokens discriminados por categoria (entrada, gravação em cache, acerto de cache, raciocínio, saída), número de chamadas de ferramentas e de falhas, número de novas tentativas e de fallbacks.

Ao avaliar um modelo, olhe para o tempo total e o custo total de uma tarefa completa; os dados de uma única requisição têm valor de referência limitado. Um modelo com preço unitário baixo, se tiver alta taxa de erro nos parâmetros das ferramentas e exigir várias rodadas de novas tentativas, pode acabar custando mais no total.

5 O papel de um gateway de API unificado na compatibilidade com APIs multimodelo

5.1 Custos de integração e manutenção

Usar três modelos ao mesmo tempo significa três conjuntos de contas, três conjuntos de chaves, três sistemas de cobrança e três configurações de SDK. Um gateway de API unificado concentra esse trabalho em um único ponto de entrada: gerencia de forma centralizada a integração de modelos e as credenciais, reduz a manutenção de configuração de cada provedor, permite escolher e alternar modelos na camada de configuração e oferece uma visão unificada de uso e custos. Para equipes que precisam comparar com frequência o desempenho dos modelos, a barreira para experimentar novos modelos também diminui.

5.2 O posicionamento do APIYI: divisão entre ponto de entrada unificado e adaptação de capacidades nativas

APIYI é uma plataforma agregadora de APIs de Modelos de Linguagem Grande de IA. Com uma única chave API, é possível chamar modelos populares como OpenAI, Claude e Gemini por meio de uma interface compatível com OpenAI, com cobrança por uso. Ele é adequado para assumir a camada de “ponto de entrada unificado de chamadas” na arquitetura: perguntas e respostas comuns, saída em streaming, comparação de modelos e roteamento multimodelo podem ser integrados diretamente.

Ter um ponto de entrada de chamadas unificado e garantir consistência total com as capacidades nativas do fornecedor são dois requisitos técnicos distintos. Ao integrar um modelo específico, ainda é necessário verificar, item por item no registro de capacidades, o escopo de suporte a chamadas de ferramentas, estado de pensamento, multimodalidade, cache e saída estruturada. Fluxos que dependem de capacidades nativas como Responses API, cache_control e assinaturas criptográficas precisam ter o endpoint correspondente confirmado como realmente disponível antes de entrarem em produção, ou então devem manter um adaptador nativo dedicado.

Início rápido para compatibilidade de API com vários modelos

Exemplo mínimo: comparar três modelos com o mesmo comando

O código abaixo usa o mesmo cliente OpenAI SDK para chamar três modelos em sequência, correspondendo ao teste 1 da seção 4.1.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Interface unificada da APIYI
)

# Os IDs dos modelos devem seguir a lista de modelos da plataforma
MODELS = ["你的GPT模型ID", "你的Claude模型ID", "你的Gemini模型ID"]

for model in MODELS:
    resp = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": "用一句话解释什么是幂等"}],
    )
    print(model, "→", resp.choices[0].message.content)
    print("usage:", resp.usage)

import json
import openai
from openai import OpenAI
from jsonschema import validate, ValidationError

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Interface unificada da APIYI
)

# Registro de capacidades: os valores são apenas exemplos de estrutura; mantenha conforme a documentação oficial e os resultados de testes reais
CAPABILITIES = {
    "gpt":    {"model": "你的GPT模型ID",    "tools_via": "responses"},  # A invocação de ferramentas precisa passar pelo adaptador Responses
    "claude": {"model": "你的Claude模型ID", "tools_via": "chat"},
    "gemini": {"model": "你的Gemini模型ID", "tools_via": "chat"},
}

def classify_error(e: Exception) -> str:
    """Classificação unificada de erros, decide se é possível tentar novamente"""
    if isinstance(e, openai.AuthenticationError):
        return "auth_failed"
    if isinstance(e, openai.NotFoundError):
        return "model_not_supported"
    if isinstance(e, openai.RateLimitError):
        return "rate_limited"          # Pode tentar novamente com backoff
    if isinstance(e, openai.BadRequestError):
        return "invalid_request"       # Erro de parâmetro ou contexto excedido; não deve tentar novamente às cegas
    if isinstance(e, openai.APIConnectionError):
        return "network_error"
    if isinstance(e, openai.InternalServerError):
        return "server_error"
    return "unknown"

def stream_chat(provider: str, messages: list, tools: list | None = None):
    """Converte o stream no formato compatível com OpenAI em eventos internos unificados"""
    cap = CAPABILITIES[provider]
    if tools and cap["tools_via"] != "chat":
        raise NotImplementedError(f"{provider} 的工具调用请交给原生适配器处理")

    kwargs = {
        "model": cap["model"],
        "messages": messages,
        "stream": True,
        "stream_options": {"include_usage": True},
    }
    if tools:
        kwargs["tools"] = tools

    calls: dict[int, dict] = {}   # Concatena por index os fragmentos de parâmetros das invocações paralelas de ferramentas
    finished = False
    try:
        for chunk in client.chat.completions.create(**kwargs):
            if not chunk.choices:
                if chunk.usage:
                    yield {"type": "usage", "data": chunk.usage.model_dump()}
                continue
            choice = chunk.choices[0]
            delta = choice.delta
            if delta.content:
                yield {"type": "text_delta", "data": delta.content}
            for tc in delta.tool_calls or []:
                slot = calls.setdefault(tc.index, {"id": None, "name": "", "args": ""})
                if tc.id:
                    slot["id"] = tc.id
                if tc.function and tc.function.name:
                    slot["name"] = tc.function.name
                    yield {"type": "tool_call_start", "data": {"id": slot["id"], "name": slot["name"]}}
                if tc.function and tc.function.arguments:
                    slot["args"] += tc.function.arguments
                    yield {"type": "tool_call_args", "data": {"index": tc.index}}
            if choice.finish_reason:
                finished = True
                yield {"type": "completed", "data": {
                    "finish_reason": choice.finish_reason,
                    "tool_calls": list(calls.values()),
                }}
    except Exception as e:
        yield {"type": "error", "data": classify_error(e)}
        return
    if not finished:
        yield {"type": "error", "data": "stream_interrupted"}  # Stream interrompido no meio

EXECUTED_KEYS: set[str] = set()   # Em produção, substitua por armazenamento persistente

def run_tool(call: dict, schema: dict, func, idempotency_key: str | None = None):
    """Primeiro valida os parâmetros, depois executa de forma idempotente"""
    try:
        args = json.loads(call["args"])   # Só faz o parse depois que todos os fragmentos estiverem completos
        validate(instance=args, schema=schema)
    except (json.JSONDecodeError, ValidationError) as e:
        return {"error": f"invalid_arguments: {e}"}
    if idempotency_key:
        if idempotency_key in EXECUTED_KEYS:
            return {"skipped": "already_executed"}
        EXECUTED_KEYS.add(idempotency_key)
    return func(**args)

# Exemplo de uso
for event in stream_chat("claude", [{"role": "user", "content": "介绍一下流式输出"}]):
    print(event)

🚀 Início rápido: cadastre-se na APIYI apiyi.com para obter uma cota de testes gratuita e use o código acima, com a mesma Key, para concluir os dois primeiros testes da seção 4.1. Para os testes relacionados à invocação de ferramentas e raciocínio multi-turno, valide modelo por modelo com base no registro de capacidades.

Perguntas frequentes (FAQ)

Pontos-chave da compatibilidade entre APIs multi-modelo (Key Takeaways)

• Trocar de modelo não é trocar de ID: perguntas e respostas simples migram diretamente; cadeias de Agent precisam lidar com 6 tipos de diferenças.
• A camada de compatibilidade tem limites: a camada de compatibilidade do Claude ignora strict e não suporta cache nem entrada de arquivos.
• As assinaturas devem ser preservadas como estão: a perda das assinaturas de thinking/thought é uma das causas mais comuns de erros em cadeias de ferramentas com múltiplos turnos.
• Eventos de streaming unificados: o backend produz 8 tipos de eventos internos e o frontend se conecta a um único protocolo.
• Roteamento guiado por registro de capacidades: registra, por “modelo + endpoint”, os recursos realmente suportados.
• O fallback precisa ser idempotente: ferramentas com efeitos colaterais recebem uma chave de idempotência para evitar execução duplicada.
• Teste antes de ir para produção: use a cota gratuita do APIYI apiyi.com para executar os seis testes de compatibilidade.

Resumo

Quando uma aplicação se conecta ao GPT, ao Claude e ao Gemini ao mesmo tempo, o segredo é concentrar as diferenças em poucos componentes:

1. Unificar o formato de mensagens e ferramentas: histórico padrão e estado proprietário de cada fornecedor ficam armazenados em camadas separadas, assim o contexto não se perde ao trocar de modelo.
2. Provider Adapter: responsável pela conversão de entrada, conversão de saída e tratamento de estado; os recursos avançados nativos são implementados aqui.
3. Registro de capacidades: documenta fielmente, para cada modelo e cada endpoint, o suporte a ferramentas, raciocínio, multimodal, Schema e cache — é ele que define o roteamento e as opções de interface.

Sobre essa base, use os seis testes de compatibilidade e a observação de custos por item para garantir a qualidade antes do lançamento. Na fase de chamadas comuns e de comparação de modelos, recomenda-se usar o APIYI apiyi.com para concluir rapidamente a validação multi-modelo com uma única chave e, depois, decidir com base nos resultados dos testes quais cadeias precisam de adaptação nativa.

📚 Materiais de referência

1. OpenAI Function Calling: chamada de ferramentas, call_id e function_call_output
2. Link: developers.openai.com/api/docs/guides/function-calling

3. Descrição: documentação autoritativa do protocolo de chamada de ferramentas da Responses API

4. Guia de migração para os modelos mais recentes da OpenAI: parâmetros de raciocínio e requisitos de interface da série GPT-6

5. Link: developers.openai.com/api/docs/guides/latest-model

6. Descrição: limites dos valores de reasoning.effort e requisitos da Responses API

7. OpenAI Prompt Caching: breakpoints de cache e TTL

8. Link: developers.openai.com/api/docs/guides/prompt-caching

9. Descrição: mecanismos de cache implícito e explícito

10. Compatibilidade do Claude com o SDK da OpenAI: escopo de suporte e limitações da camada de compatibilidade

11. Link: platform.claude.com/docs/en/cli-sdks-libraries/libraries/openai-sdk

12. Descrição: diferenças em strict, cache, entrada de arquivos, mesclagem de system, entre outros

13. Claude Extended Thinking: Adaptive Thinking e assinaturas de pensamento

14. Link: platform.claude.com/docs/en/build-with-claude/extended-thinking

15. Descrição: regras de reenvio dos blocos de pensamento em chamadas de ferramentas com múltiplos turnos

16. Saídas estruturadas e cache do Claude: JSON outputs, Strict tool use, cache_control

17. Link: platform.claude.com/docs/en/build-with-claude/structured-outputs
18. Link: platform.claude.com/docs/en/build-with-claude/prompt-caching

19. Descrição: restrições estruturais e padrões de cache

20. Gemini Interactions API e compatibilidade com OpenAI: nova interface e endpoint de compatibilidade

21. Link: ai.google.dev/gemini-api/docs/interactions-overview
22. Link: ai.google.dev/gemini-api/docs/openai

23. Descrição: estrutura de steps, estado da sessão e mapeamento de parâmetros compatíveis

24. Assinaturas de pensamento, chamada de ferramentas e cache do Gemini

25. Link: ai.google.dev/gemini-api/docs/thought-signatures
26. Link: ai.google.dev/gemini-api/docs/function-calling
27. Link: ai.google.dev/gemini-api/docs/caching

28. Descrição: preservação de assinaturas no modo stateless, protocolo de ferramentas e cache explícito

29. Páginas oficiais de preços das três empresas

30. Link: developers.openai.com/api/docs/pricing
31. Link: platform.claude.com/docs/en/models/sonnet-5-5/overview
32. Link: ai.google.dev/gemini-api/docs/pricing
33. Descrição: fonte dos dados da tabela de preços deste artigo, data de verificação 2026-11-13

Autor: Equipe técnica da APIYI
Contato técnico: sinta-se à vontade para falar conosco pela página inicial do site da APIYI; há mais materiais no centro de documentação docs.apiyi.com