Arquitetura de um gateway LLM: roteamento, cache, fallbacks e controle de custos

Uma dúzia de funcionalidades da sua empresa chama três provedores de modelos. Cada equipe guarda a própria chave de API, ninguém sabe qual equipe gastou quanto no mês passado e, quando o provedor principal devolveu erros 429 por uma hora, cada app falhou de um jeito diferente. Um deles trocou de modelo e quebrou sua saída JSON.

Um gateway LLM, também chamado de gateway de IA ou proxy LLM, faz toda chamada a um modelo passar por um único serviço que cuida das chaves, do roteamento e da medição. Este post percorre o caminho da requisição etapa por etapa e depois trata de roteamento, cache, limites de tokens, métricas, segurança e dos gateways que você pode adotar.

Por que colocar um gateway na frente dos provedores de modelos

Os limites e as faturas dos provedores não seguem o seu organograma. A OpenAI define limites de taxa por organização e projeto, não por usuário, e a Anthropic por organização, com limites opcionais por workspace. Um job em lote noturno no mesmo projeto de um chat de clientes pode esgotar os tokens por minuto do chat. Um gateway dá a você um único lugar para chaves, roteamento, limites por equipe e atribuição de custos.

Ele não substitui o seu API gateway. Um API gateway conta requisições; um gateway LLM conta tokens e dólares, entende respostas em streaming e trata o 429 de um provedor como motivo para tentar outro modelo.

O caminho da requisição, etapa por etapa

As verificações baratas rodam primeiro: nada chega a um provedor até que a requisição seja permitida e ainda não tenha sido respondida.

1. Autenticar. Associe a chave virtual a um app, a uma equipe e aos modelos permitidos dela, ou devolva 401.
2. Verificar limites. Compare os contadores de tokens e o orçamento da equipe no Redis. Acima do limite, devolva 429 com Retry-After.
3. Aplicar a política. Aplique a lista de modelos permitidos e um teto de max_tokens, e mascare dados pessoais, como endereços de e-mail.
4. Verificar o cache. Um acerto devolve a resposta armazenada, sem chamar o provedor.
5. Rotear. Escolha um modelo e uma cadeia ordenada de fallbacks.
6. Chamar o adaptador. Traduza a requisição para a API do provedor, anexe a chave do provedor e inicie um timeout para o primeiro token.
7. Tentar de novo ou fazer fallback em 429, 5xx, no erro de sobrecarga 529 da Anthropic ou em um timeout, mas só antes de o primeiro token chegar ao app. Um provedor pode enviar um erro depois que um 200 já iniciou o stream, e trocar de modelo no meio da resposta costura duas respostas.
8. Transmitir e medir. Repasse os server-sent events e grave um evento de uso de forma assíncrona. A API Chat Completions da OpenAI envia o uso em um último chunk apenas com stream_options.include_usage, e um stream cortado o perde, então continue lendo depois que o cliente se desconectar.

Os passos 1 a 4 devem ser consultas em memória ou no Redis; logs e avaliações ficam fora do caminho da requisição.

Estratégias de roteamento

O fallback mais seguro é o mesmo modelo em outro host, como um modelo Claude na API da Anthropic e no Amazon Bedrock. Uma família de modelos diferente precisa das próprias evals, já que chamadas de ferramentas e saída JSON são as primeiras a quebrar, e todo fallback precisa de cota sobrando.

Tente de novo em uma única camada: o SDK Python da OpenAI tenta duas vezes por padrão, e a documentação do LiteLLM avisa que retentativas empilhadas transformam uma requisição em (1 + N)² chamadas ao provedor. Dê descanso a um deployment que falha em vez de martelá-lo, como o LiteLLM faz por 5 segundos após um 429 por padrão; o padrão circuit breaker generaliza isso.

Cache: exato, semântico e do provedor

O cache de correspondência exata é seguro, mas estreito: o Cloudflare AI Gateway calcula o hash do provedor, do endpoint, do modelo, do cabeçalho de autenticação e do corpo completo, então qualquer mudança é uma nova entrada. Coloque o tenant na sua chave de cache, ou a resposta de um cliente pode chegar a outro. O cache semântico também reconhece paráfrases, mas «cancelar meu pedido» e «cancelar minha assinatura» podem ficar muito próximos, então use-o só onde um erro por pouco seja inofensivo.

O cache do provedor costuma economizar mais. A Anthropic faz cache de prefixos marcados com cache_control por 5 minutos, renovados a cada acerto, e as leituras de cache custam 0,1 vez o preço base de entrada na maioria dos modelos. A OpenAI faz cache por padrão nos modelos compatíveis, com entrada em cache até 95% mais barata (no momento da escrita, novembro de 2026). Mantenha os prompts de sistema idênticos byte a byte, sem timestamps no início, redija de forma determinística e fixe uma conversa em um único deployment, porque cada conta de provedor tem o próprio cache.

Com um valor assumido de US$ 3,00 por milhão de tokens de entrada, um prompt de sistema de 6.000 tokens mais uma pergunta de 500 tokens custa US$ 0,0195. Com o prefixo lido do cache, 6.000 × US$ 0,30/M + 500 × US$ 3,00/M = US$ 0,0033, cerca de 83% a menos por acerto. O post sobre estratégias de cache trata da invalidação.

Limites de tokens e orçamentos por equipe

Requisições por minuto são um limite ruim para tráfego LLM: uma requisição pode carregar 50 tokens ou 200.000. Limite os tokens por minuto por equipe, imponha um teto a max_tokens e defina um orçamento mensal em dólares. O tamanho de uma requisição só é conhecido quando ela termina, então escolha uma abordagem:

• Reservar e depois reconciliar. Conte de antemão a entrada estimada mais max_tokens e corrija depois. A OpenAI conta o maior entre max_tokens e uma estimativa baseada em caracteres contra os próprios limites.
• Contar durante. A Anthropic conta os tokens de saída conforme são gerados, e as leituras de cache não contam para os tokens de entrada por minuto na maioria dos modelos.
• Contar depois. Simples, mas picos ultrapassam o limite. A Cloudflare diz que requisições concorrentes podem exceder brevemente seus limites de gasto.

Mantenha os contadores no Redis, compartilhados por todas as instâncias do gateway; o system design de um rate limiter trata dos algoritmos e de uma queda do Redis. Precifique o uso com uma tabela de preços versionada, alerte em 80% de um orçamento e decida se 100% significa parada total ou um modelo mais barato.

O que medir

Acompanhe o tempo até o primeiro token por provedor e modelo, os tokens de entrada, saída e em cache por equipe, o custo por equipe e funcionalidade, os erros por tipo e as taxas de fallback e de acerto de cache. As convenções de IA generativa do OpenTelemetry nomeiam atributos como gen_ai.usage.input_tokens, mas ainda estão em desenvolvimento, então fixe a versão que você emite. O diagrama de arquitetura de observabilidade mostra para onde vão os sinais.

Segurança: o que um gateway não resolve

Um gateway guarda todas as chaves dos provedores e vê todos os prompts, então dê a ele poucos administradores, mudanças de configuração auditadas e logs que mantenham metadados de toda chamada, mas prompts apenas amostrados, redigidos e de curta duração.

Ele ajuda contra o que o OWASP Top 10 para aplicações LLM chama de consumo ilimitado: limites e orçamentos impedem que um agente em loop ou uma chave vazada estourem a fatura. Ele não resolve a injeção de prompt; a OWASP diz que não está claro se existe prevenção infalível, e instruções escondidas em um documento recuperado parecem dados para um gateway. As defesas são ferramentas com privilégio mínimo, aprovações e tratamento rigoroso da saída, como no diagrama de arquitetura de um agente de IA.

Construir ou adotar

O Envoy AI Gateway entrou na Agentic AI Foundation como Agent Router em setembro de 2026. Construa só o que é específico do seu caso, como o roteamento por classe de dados; a parte cara é manter os adaptadores de provedor atualizados. Um gateway gerenciado coloca um terceiro no caminho de todo prompt; um auto-hospedado faz do Redis, do Postgres e das atualizações um trabalho seu.

O diagrama do gateway LLM

Como ler:

• Dois apps chamam um único endpoint no formato OpenAI com as próprias chaves virtuais e sem chave de provedor.
• Cinco etapas rodam em ordem, com uma nota acima de cada uma sobre o que ela decide. Uma requisição pode parar em Auth (401, 429) ou em um acerto de cache.
• Três destinos: a OpenAI como principal, a Anthropic como fallback tracejado em 429 ou 5xx, e um modelo vLLM auto-hospedado para dados sensíveis.
• Abaixo das etapas: Postgres para chaves e orçamentos, Redis para contadores e respostas em cache, e o log de uso, gravado de forma assíncrona.
• O bloco Markdown lista configurações de exemplo para uma equipe.

Como desenhar diagramas de gateway LLM com clareza

• Desenhe etapas, não uma caixa só. Um único retângulo de gateway esconde se a redação acontece antes do cache.
• Coloque as condições nas arestas: «fallback on 429/5xx», «sensitive data», «miss».
• Marque onde os dados saem da sua rede, para que provedores externos pareçam diferentes do modelo auto-hospedado.
• Use linha tracejada nos caminhos assíncronos, como a medição e o log.
• Deixe o catálogo de modelos de fora; ele pertence à configuração.

Monte no Archboard

1. Entre com Google ou GitHub e crie um diagrama.
2. Adicione uma Moldura do pack Básico chamada LLM gateway.
3. Dentro dela, adicione cinco nós Componente do pack C4 Model em uma linha: 1 Auth, 2 Policy, 3 Cache, 4 Router e 5 Adapters, com uma nota Texto de Básico acima de cada um.
4. Abaixo deles, adicione Postgres e Redis do pack Dados e um Armazém de dados para o log de uso e custos.
5. À esquerda da moldura, adicione dois nós Contêiner do pack C4 Model para os apps; à direita, dois nós Sistema externo para OpenAI API e Anthropic API e um Ponto de extremidade do pack ML para o modelo auto-hospedado.
6. Desenhe arestas com rótulo; deixe o fallback e os eventos de uso tracejados.
7. Adicione um bloco Markdown do pack Básico com as configurações de exemplo.

Se você mantém o caminho como um fluxograma Mermaid, o conversor Mermaid o transforma em um primeiro rascunho editável. O exemplo usa 15 nós de diagrama e fica dentro do plano Free.

Perguntas frequentes

O que é um gateway LLM? Um serviço pelo qual toda chamada a um modelo passa. Ele guarda as chaves dos provedores, roteia e faz fallback entre modelos, faz cache, aplica limites de tokens e orçamentos e registra o uso por equipe.

Qual é a diferença entre um gateway de IA e um API gateway? Um API gateway limita requisições HTTP. Um gateway de IA também entende tokens, streaming e erros de provedor, então pode limitar por tokens, atribuir custos e fazer fallback para outro modelo.

Qual é a diferença entre cache semântico e prompt caching? O cache semântico roda no seu gateway e devolve uma resposta armazenada para uma pergunta parecida. O prompt caching roda no provedor e reaproveita um prefixo de prompt já processado; o modelo ainda escreve uma resposta nova.

Como limitar requisições a um LLM por tokens? Mantenha um token bucket por equipe no Redis, reserve a entrada estimada mais max_tokens antes de cada chamada, corrija depois e devolva 429 com Retry-After ao atingir o limite.

Um gateway LLM pode impedir a injeção de prompt? Não. Ele pode filtrar ataques óbvios e limitar o dano com orçamentos, mas instruções injetadas em documentos parecem dados. Defenda-se na aplicação, com ferramentas de privilégio mínimo e aprovações.

Comece grátis — um assento, sem cartão de crédito.