AI Gateway
Quando o provedor principal falha, um gateway pode escolher outra rota. Essa capacidade melhora a continuidade apenas se a rota alternativa preservar o contrato: modelo compatível, dados autorizados, tempo restante e orçamento disponível. Trocar silenciosamente de provedor pode introduzir nova falha, mudar a qualidade ou duplicar uma ação que o usuário já executou.
Nesta aula construiremos uma fronteira de acesso a modelos com quotas, retries, balanceamento e fallback explícitos. LiteLLM e OpenRouter aparecem como opções de implementação, enquanto o exemplo local torna as decisões auditáveis. A entrega deve demonstrar indisponibilidade de um provedor sem duplicar efeitos de ferramenta e justificar onde o sistema deve parar em vez de continuar tentando.
JavaScriptIA & MLAo terminar esta aula
- Fallback preserva capacidade, autorização e limites.
- Retries não devem duplicar efeitos de ferramentas.
- Gateway comum não elimina diferenças entre provedores.
Antes de continuar: Laboratório: Cost Control & Routing
O contrato do gateway e seus limites
FundamentosUm AI Gateway centraliza acesso a modelos e políticas como autenticação, roteamento e registro de uso. Ele pode oferecer uma interface comum, mas não torna todas as capacidades dos provedores equivalentes. Modelos diferem em formatos, streaming, ferramentas, limites de contexto e suporte a parâmetros. Defina uma capability matrix com requisitos por tarefa. Uma rota incapaz de produzir o esquema exigido não é fallback válido apenas porque aceita uma mensagem de texto.
O gateway deve separar credenciais internas de credenciais do provedor, aplicar autorização por tenant e registrar a rota efetivamente usada. Retorne metadados suficientes para avaliar a resposta e conciliar uso, sem expor segredos. Erros precisam de categorias que preservem semântica: autenticação inválida, limitação, timeout e indisponibilidade não são iguais. Se o SDK converte todo erro em “tente novamente”, o gateway perde informação necessária para decidir de forma segura.
Retry, fallback e o risco da execução ambígua
FundamentosRetry repete uma operação em condições definidas; fallback troca a rota ou estratégia. Um timeout não demonstra que a operação não aconteceu. O servidor pode ter recebido o pedido e produzido a resposta antes de a conexão se perder. Para geração sem efeitos externos, a repetição ainda pode gerar novo custo e outra saída; para uma ferramenta de escrita, pode duplicar uma ação. Separe geração de proposta e execução do efeito, associando o efeito a uma chave de idempotência.
Defina tempo máximo total, timeout por tentativa, quantidade máxima e tipos de erro recuperáveis. Backoff com jitter reduz sincronização, mas sua espera entra no orçamento de latência. Erros de esquema ou autorização não devem desencadear fallback indiscriminado. Quando a rota alternativa exige enviar dados a outro país ou domínio de confiança, a política deve validar isso antes da chamada. Resiliência não significa tentar qualquer destino até obter texto; significa manter o serviço dentro de limites acordados.
Load balancing e saúde de dependências
FundamentosLoad balancing distribui requisições entre instâncias ou rotas disponíveis. Round-robin alterna destinos e é simples, mas ignora diferenças de capacidade e latência. Estratégias baseadas em carga ou limite disponível podem ser mais adequadas, desde que as métricas sejam confiáveis. Não misture balanceamento de instâncias equivalentes com escolha de modelos de qualidade diferente: a segunda decisão exige avaliação por tarefa. Registre rota, motivo e resultado para investigar a política.
Um circuito pode suspender temporariamente chamadas a uma dependência que falha repetidamente e testar recuperação com poucas sondagens. A configuração precisa definir abertura, tempo de espera e condição de fechamento. Health check bem-sucedido não garante que uma chamada real com contexto grande vai funcionar. Dependências comuns também reduzem a independência entre provedores: rede, gateway e banco podem derrubar todas as rotas. A análise de resiliência precisa enxergar esses pontos únicos, não apenas contar nomes de fornecedores.
LiteLLM e OpenRouter como opções, não contratos universais
FundamentosLiteLLM documenta roteamento, balanceamento, limites, cooldowns e fallbacks em seu ecossistema. OpenRouter oferece políticas de seleção de provedores em seu serviço. A escolha depende de operação própria versus serviço intermediário, capacidades desejadas, observabilidade e regras de dados. Consulte a versão de documentação e teste parâmetros: uma configuração aceita não demonstra que todos os destinos obedecem às mesmas condições. Não copie aliases de exemplo sem escolher modelos disponíveis para sua conta.
↗ Router - Load Balancing↗ Provider Routing↗ Budgets, Rate Limits
Para qualquer opção, valide quotas por chave e tenant, isolamento de credenciais e comportamento de falha. Uma quota precisa ser compartilhada quando há várias réplicas do gateway, ou cada réplica pode permitir o limite inteiro. Defina como contabilizar chamadas sem uso final reportado e como conciliar tentativas cobradas. O laboratório local implementa uma política simplificada; ele não substitui um teste de integração com a ferramenta escolhida e uma avaliação de qualidade da rota alternativa.
↗ Router - Load Balancing↗ Provider Routing↗ Budgets, Rate Limits
Qualidade e custo sob indisponibilidade
FundamentosUma estratégia multi-provider deve ser avaliada também quando o primário está fora do ar. Execute os mesmos casos na rota de fallback e verifique esquema, ferramentas, fundamentação e requisitos críticos. Se a qualidade cair abaixo do piso, pode ser melhor encaminhar tarefas sensíveis e manter apenas classes simples. Defina essa degradação como uma política visível, não como surpresa ao usuário.
Compare custo por tarefa concluída incluindo tentativas que falharam e o fallback. Não presuma que dois provedores garantem disponibilidade maior sem considerar falhas correlacionadas. Meça latência ponta a ponta, fila e tempo de backoff. Registre efeitos de ferramentas com uma operação lógica independente da rota de modelo. Quando um pedido é repetido com a mesma chave, ele deve recuperar o resultado existente ou indicar execução em andamento, em vez de executar novamente uma escrita. A persistência dessa proteção é parte da arquitetura, não um detalhe de prompt.
Fallback local com efeito separado e idempotente
FundamentosSalve gateway.cjs e execute node gateway.cjs. O primário simula indisponibilidade; o secundário retorna uma proposta. O executor possui um ledger em memória e a mesma chave produz apenas um efeito. Os provedores são funções locais, então não há prova de disponibilidade ou qualidade de APIs reais.
const assert=require('node:assert/strict');
const ledger=new Map();let effects=0;
const primary=async()=>{const e=new Error('unavailable');e.retryable=true;throw e;};
const secondary=async()=>({action:'create_ticket',subject:'consulta'});
async function generate(){
for(const provider of [primary,secondary]){
try{return await provider();}catch(e){if(!e.retryable)throw e;}
}
throw new Error('no-route');
}
function execute(key,proposal){
const signature=JSON.stringify(proposal);
if(ledger.has(key)){
const old=ledger.get(key);
if(old.signature!==signature)throw new Error('idempotency-conflict');
return old.result;
}
const result={ticketId:'ticket-'+(++effects)};
ledger.set(key,{signature,result});return result;
}
(async()=>{
const proposal=await generate();
const a=execute('request-1',proposal),b=execute('request-1',proposal);
assert.deepEqual(a,b);assert.equal(effects,1);
assert.throws(()=>execute('request-1',{action:'other'}),/conflict/);
console.log({a,effects});
})();O gateway obtém uma proposta no secundário e o executor cria um único ticket. A comparação de assinatura impede reutilizar a chave com outra intenção. Como o ledger é um Map, reiniciar o processo perde a proteção; uma implementação de produção requer registro durável e operação atômica. Um timeout após criação do ticket precisa consultar esse registro antes de decidir repetir.
Exercício aplicado
O primário dá timeout após preparar uma proposta, o secundário retorna outra e a ferramenta de ticket recebe a mesma requestId duas vezes. Defina o contrato que evita duplicação e conflito.
- Separe proposta e efeito em etapas distintas.
- Associe idempotencyKey à operação lógica.
- Persista assinatura e resultado do efeito.
- Recuse a mesma chave com proposta diferente.
Abrir resolução comentada
O fallback pode repetir geração, mas a escrita é deduplicada pelo executor. A mesma intenção retorna o ticket já criado; intenção diferente com a mesma chave é conflito e precisa de resolução explícita. Não execute a segunda proposta silenciosamente.
O Map demonstra a regra apenas durante a vida do processo. Para sobreviver a reinício e concorrência, use armazenamento durável, unicidade e transação ou protocolo equivalente. Também preserve orçamento e deadline para que resiliência não se transforme em tentativas ilimitadas.
const assert=require('node:assert/strict');
const ledger=new Map();let effects=0;
const primary=async()=>{const e=new Error('unavailable');e.retryable=true;throw e;};
const secondary=async()=>({action:'create_ticket',subject:'consulta'});
async function generate(){
for(const provider of [primary,secondary]){
try{return await provider();}catch(e){if(!e.retryable)throw e;}
}
throw new Error('no-route');
}
function execute(key,proposal){
const signature=JSON.stringify(proposal);
if(ledger.has(key)){
const old=ledger.get(key);
if(old.signature!==signature)throw new Error('idempotency-conflict');
return old.result;
}
const result={ticketId:'ticket-'+(++effects)};
ledger.set(key,{signature,result});return result;
}
(async()=>{
const proposal=await generate();
const a=execute('request-1',proposal),b=execute('request-1',proposal);
assert.deepEqual(a,b);assert.equal(effects,1);
assert.throws(()=>execute('request-1',{action:'other'}),/conflict/);
console.log({a,effects});
})();Como conferir seu resultado
- Erro definitivo não dispara fallback.
- Quota recusada produz zero chamadas.
- Mesma chave e mesma proposta geram um efeito.
- Chave reaproveitada com proposta alterada falha.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Definir contrato comum e limites dos provedores.
- Separar fallback de efeito externo.
Primário propõe ticket e timeout; secundário propõe outro texto. requestId J8 chega duas vezes. Desenhe gateway/executor.
Conferir raciocínio e critérios de domínio
Fallback pode refazer geração dentro do contrato, registrando provedor e tentativas.
Ticket usa intenção estável/payload vinculado; propostas incompatíveis não viram dois efeitos.
Timeout pós-efeito exige consulta; saúde/latência não garantem qualidade.
Evidências para autoavaliação ou revisão por pares
- Fallback: Fallback pode refazer geração dentro do contrato, registrando provedor e tentativas.
- Identidade: Ticket usa intenção estável/payload vinculado; propostas incompatíveis não viram dois efeitos.
- Disponibilidade: Timeout pós-efeito exige consulta; saúde/latência não garantem qualidade.
Um erro frequente
Fallback pode repetir qualquer operação.
Fallback exige segurança de repetição e mesmo contrato.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. Um timeout prova que a operação não ocorreu?
2. Balancear instâncias equivale a escolher modelos por qualidade?
3. Dois provedores garantem resiliência?
Não.
Falhas compartilhadas e contratos incompatíveis podem afetar ambas as rotas.
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- Router - Load Balancing
LiteLLM • consulta: 2026-10-06
FundamentosBalanceamento, estratégias por uso/latência/custo, retries, cooldowns e fallbacks entre deployments.
Limites: Routing operacional não garante qualidade sem evals por classe de tarefa; fallback pode mudar comportamento e recursos.
- Provider Routing
OpenRouter • consulta: 2026-10-06
FundamentosSeleção e preferências de provedores, fallback e restrições de roteamento.
Limites: Recursos e políticas dependem do provedor; avaliar qualidade, dados enviados e compatibilidade por rota.
- Budgets, Rate Limits
LiteLLM • consulta: 2026-10-06
FundamentosOrçamentos e limites de requisições/tokens por usuário, chave e equipe.
Limites: Configuração e persistência importam; não citar valores de preço como permanentes.
- Retry pattern
Microsoft • consulta: 2026-10-06
FundamentosRetries de falhas transitórias, política de atrasos, logging e impacto em transações.
Limites: Retries de operações não idempotentes e camadas aninhadas podem duplicar efeitos e ampliar carga.