8341TokenFactory
LLM APIAPI GatewayAggregation

Fábrica de Token8341: quatro modelos para uma única funcionalidade — GPT-4o como fallback, DeepSeek como principal, Qwen para chinês, Doubao para atendimento ao cliente

SiCore TokenWorks Team·2026-11-08

Para a mesma funcionalidade, o frontend precisa chamar quatro modelos: GPT-4o responsável pelo fallback, DeepSeek executando a inferência principal, Qwen tratando textos longos em chinês, e Doubao assumindo os scripts de atendimento ao cliente. Quatro SDKs, quatro conjuntos de autenticação, quatro documentações. Na primeira semana após o lançamento, só para alinhar essas diferenças consumimos dois dias-homem.

Isso não é exagero. Fizemos um levantamento: após integrar os quatro provedores de modelos, a parte do código de negócio relacionada às chamadas de modelos inflou quase três vezes. Cada vez que se troca um modelo, é preciso alterar a forma de chamada, a lógica de parsing e o tratamento de erros. Pior ainda: toda vez que o fornecedor atualiza o SDK, é preciso testar tudo de novo. Este artigo organiza de forma completa as armadilhas que enfrentamos e a solução de gateway que finalmente implementamos, na esperança de ajudar equipes que também estão se debatendo entre múltiplos modelos.

1. Autenticação: quatro sistemas, quatro formas de escrever

A autenticação foi o primeiro obstáculo. A família OpenAI usa Bearer Token, basta colocar Authorization: Bearer sk-xxx no cabeçalho da requisição. O Qwen exige assinatura com AccessKey: a cada requisição é preciso calcular HMAC com AK/SK, além de montar timestamp e string aleatória. O Doubao usa AK/SK mais timestamp, mas o algoritmo de assinatura é diferente do Qwen. O DeepSeek, embora seja compatível com o formato OpenAI, tem seu próprio base_url e mapeamento de nomes de modelos, e a forma de inicialização também não é totalmente idêntica ao SDK oficial.

O resultado é que o código está cheio de if-else. Uma instância de client por fornecedor, um conjunto de configuração por instância. O gerenciamento de chaves é ainda mais doloroso — as Keys dos quatro fornecedores ficam em quatro lugares diferentes, e na hora da rotação é preciso alterar em quatro pontos; esquecer um só gera incidente em produção.

Depois unificamos na camada de integração: externamente expomos apenas uma API Key, e internamente fazemos a tradução de protocolo. A abordagem concreta é que a camada de integração mantém uma tabela de roteamento de fornecedores, cada fornecedor correspondendo ao seu próprio adaptador de autenticação. O lado de negócio recebe apenas uma Key, a requisição chega à camada de integração, que localiza o fornecedor correspondente pelo nome do modelo e usa o adaptador para concluir a assinatura e o encaminhamento.

Posteriormente unificamos o base_url no token8341 e testamos: com uma única Key é possível chamar GPT-4o, Claude, Gemini, DeepSeek, Qwen, ERNIE e Doubao, compatível com o SDK OpenAI, e basta alterar uma linha do base_url para trocar. O trabalho sujo de autenticação fica barrado fora da camada de integração, e o código de negócio ficou bem mais limpo. A rotação de chaves também se tornou uma operação em um único ponto, e o custo operacional caiu uma ordem de magnitude diretamente.

2. Blocos de streaming SSE: quatro formatos, uma renderização

Os blocos de streaming SSE foram o segundo obstáculo, e mais oculto que a autenticação. No chunk do GPT-4o, o delta.content pode ser null, especialmente no primeiro e no último chunk; se o frontend renderizar sem verificar nulo, aparece um undefined piscando. O DeepSeek inclui usage no último chunk, e a estrutura do campo usage não é exatamente igual à da OpenAI. O Qwen subdivide mais os tipos de evento, com add, finish, error e outros tipos de evento, cada um com estrutura de payload diferente. O marcador de término do Doubao é diferente de novo: ele usa um campo finish_reason especial para indicar o fim do stream.

O frontend recebendo quatro formatos faz a lógica de renderização simplesmente rachar. Nossa abordagem inicial foi adaptar no frontend, escrevemos quatro funções de parsing, mas acabou que cada novo modelo exigia alterar o frontend. Depois mudamos para normalização na camada de gateway: unificar na estrutura de chunk da OpenAI, filtrar diretamente deltas vazios, e extrair o usage separadamente para acumular. A regra concreta é — todas as respostas de streaming dos fornecedores são convertidas para o formato data: {"choices":[{"delta":{"content":"..."}}]}, o término é uniformemente marcado com data: [DONE], e o usage é retornado no último chunk no formato OpenAI.

O frontend reconhece apenas um formato, sem precisar se preocupar com quem está conectado no backend. Essa mudança reduziu o código relacionado a modelos no frontend de mais de 400 linhas para cerca de 80, e ao adicionar novos modelos o frontend não precisa de nenhuma alteração.

3. Códigos de erro: erros escondidos dentro de HTTP 200

O grau de confusão dos códigos de erro superou as expectativas. Para o mesmo rate limit, a OpenAI retorna 429 com rate_limit_exceeded, o Qwen retorna um erro de negócio com campo code, e o Doubao simplesmente enfia o erro no body de um HTTP 200 — o status code é 200, mas há um campo error no body. O DeepSeek na maioria das vezes é consistente com a OpenAI, mas ocasionalmente retorna algumas estruturas de erro customizadas.

Monitoramento e alertas simplesmente não conseguem ser unificados. Você não pode escrever uma regra dizendo "se 429, alertar", porque alguns fornecedores não retornam 429 no rate limit. Também não pode olhar apenas o status code HTTP, porque o 200 do Doubao pode ser um erro.

Na camada de integração criamos uma tabela de mapeamento, convergindo os códigos de erro de cada fornecedor em um sistema interno de erros: rate limit, timeout, falha de autenticação, moderação de conteúdo, serviço indisponível. A lógica concreta de mapeamento é — primeiro olhar o status code HTTP, depois o error code no body, combinando os dois para julgar. Por exemplo, se o Doubao retorna 200 mas há error no body, mapeia pelo error code; se o Qwen retorna 400 com code de negócio, mapeia pelo code. As regras de alerta são escritas apenas uma vez, e na investigação consulta-se o código de erro original.

Essa tabela de mapeamento mantivemos com cerca de mais de 60 regras, cobrindo os cenários de erro comuns dos quatro fornecedores. Após o lançamento, a taxa de acerto dos alertas subiu de cerca de 60% para mais de 95%, e os falsos positivos praticamente desapareceram.

4. Estatísticas de uso: quatro números que não batem

A diferença de critérios nas estatísticas de uso é o que mais facilmente passa despercebido, mas certamente se revela na conciliação financeira. A contagem de tokens do GPT-4o inclui o system prompt, os tokens com cache hit do DeepSeek são precificados separadamente, o Qwen calcula entrada e saída separadamente, e a unidade de cobrança do Doubao é diferente de novo. Na conciliação financeira os quatro números não batem, e não há como calcular claramente o custo real de cada modelo.

A solução de agregação é registrar no gateway o model, input_tokens, output_tokens e cache_hit de cada requisição, persistindo uniformemente pelo critério de cobrança por token. A abordagem concreta é — o gateway registra o horário de início e fim da requisição ao encaminhar, extrai o campo usage de cada fornecedor da resposta e converte uniformemente para o formato padrão. Para fornecedores com unidades de cobrança diferentes, faz-se uma conversão na camada de gateway, convertendo tudo para custo per-token.

Assim, independentemente de quem está conectado no backend, o custo pode ser nivelado e visualizado na mesma tabela. Posteriormente também criamos um painel de custos baseado nessa tabela, com visualização separável por modelo, por linha de negócio e por dia. Uma vez descobrimos que o custo de uma linha de negócio subiu repentinamente 40%; investigando, descobrimos que a estratégia de roteamento estava direcionando um grande volume de requisições para o GPT-4o, e após ajustar o roteamento o custo caiu imediatamente. Sem a agregação unificada de uso, esse tipo de problema seria impossível de detectar.

5. A arquitetura de quatro camadas do gateway de modelos

Quais camadas o gateway de modelos deve assumir? Minha divisão é em quatro camadas.

Primeira camada: tradução de protocolo. Unificar os formatos de requisição e resposta de cada fornecedor em uma interface compatível com OpenAI. Esta é a única camada que o código de negócio toca diretamente; ela é responsável por traduzir a requisição no formato padrão OpenAI para o formato de cada fornecedor, e depois traduzir a resposta de volta.

Segunda camada: roteamento. Selecionar o modelo por tipo de tarefa, por exemplo, textos longos em chinês vão para o Qwen, código vai para o DeepSeek, fallback vai para o GPT-4o. A estratégia de roteamento pode ser configurável, suportando múltiplas dimensões como tipo de tarefa, prioridade e custo. Também adicionamos lógica de degradação — se o modelo principal der timeout ou rate limit, alterna automaticamente para o modelo de fallback.

Terceira camada: agregação de uso. Cobrança e cota unificadas. O consumo de tokens, cache hit e tempo de resposta de cada requisição são registrados nesta camada, que fornece externamente uma interface unificada de consulta de uso.

Quarta camada: observabilidade. Logs, rastreamento de links, convergência de códigos de erro. Cada requisição tem um trace_id, rastreável em toda a cadeia da entrada à saída. Os códigos de erro são mapeados uniformemente nesta camada, e as regras de alerta também são configuradas apenas aqui.

O código de negócio chama apenas a interface da primeira camada; as três camadas seguintes são transparentes para ele. A vantagem disso é — trocar modelo não exige alterar o código de negócio, adicionar modelo não exige alterar o código de negócio, ajustar a estratégia de roteamento também não exige alterar o código de negócio. A equipe de negócio só precisa se preocupar com "quero chamar um modelo", e o resto fica com o gateway.

6. Lembretes para evitar armadilhas

Não faça import direto dos SDKs de cada fornecedor no código de negócio. Uma vez que o fornecedor atualize a interface ou você queira trocar de modelo, a superfície de alteração se espalha enormemente. Já vimos equipes que chamavam os SDKs diretamente no código de negócio e, ao trocar de modelo depois, alteraram mais de 30 arquivos e testaram por uma semana antes de colocar em produção.

Gastar dois dias a mais na camada de integração economiza duas semanas depois. Essa relação custo-benefício foi comprovada na prática aqui — após o lançamento do gateway, adicionar um novo modelo exige apenas acrescentar um adaptador na camada de gateway, com zero alteração no código de negócio, e a integração e os testes ficam prontos em meio dia.

Mais duas sugestões rápidas: primeiro, faça a agregação de uso o quanto antes, não espere a conciliação financeira para descobrir que não dá para calcular direito; segundo, a tabela de mapeamento de códigos de erro deve ser mantida continuamente, e a primeira coisa ao integrar um novo fornecedor é completar o mapeamento de códigos de erro.

Autor: Sun Haoran

Data de publicação: 9 de novembro de 2026