Phase 13 - Lesson 21

LLM Routing Layer — LiteLLM, OpenRouter, Portkey

This lesson includes a graded coding exercise that runs in your browser, unlocked with lifetime access.

O bloqueio de fornecedor (provider lock-in) é caro. Diferentes cargas de trabalho de chamada de ferramenta (tool-calling) se adequam a diferentes modelos. Gateways de roteamento oferecem uma única superfície de API, tentativas, failover, rastreamento de custos e guardrails. Três arquétipos dominam em 2026: LiteLLM (código aberto auto-hospedado), OpenRouter (SaaS gerenciado) e Portkey (nível de produção, código aberto lançado em março de 2026). Esta lição aborda os critérios de decisão e demonstra um gateway de roteamento usando a biblioteca padrão (stdlib).

Type: Learn Languages: Python (stdlib, routing + failover + cost tracker) Prerequisites: Phase 13 · 02 (function calling), Phase 13 · 17 (gateways) Time: ~45 minutos

Objetivos de Aprendizado

• Distinguir entre opções de roteamento auto-hospedadas, gerenciadas e de nível de produção.
• Implementar uma cadeia de fallback que realiza novas tentativas em falhas de provedores em uma ordem de prioridade definida.
• Rastrear o custo por requisição e o uso de tokens entre provedores.
• Decidir entre LiteLLM, OpenRouter e Portkey para uma determinada restrição de produção.

O Problema

Cenários onde o roteamento de provedores é importante:

1. Custo. O Claude Sonnet custa o triplo do Haiku. Para uma tarefa de triagem, o Haiku é suficiente; para uma tarefa de síntese, o Sonnet vale a pena. Roteie por requisição.

2. Failover. A OpenAI tem uma hora ruim. Todas as requisições falham. Você deseja um fallback automático para a Anthropic sem precisar reimplantar.

3. Latência. Uma interface de chat em tempo real precisa de um tempo rápido para o primeiro token (time-to-first-token). Um resumidor em lote não. Roteie pelo SLA de latência.

4. Conformidade. Usuários da UE devem permanecer nas regiões da UE. Roteie por região.

5. Experimentação. Teste A/B de dois modelos na mesma carga de trabalho. Roteie por balde de teste (test bucket).

Codificar tudo isso manualmente por integração é repetitivo. Um gateway de roteamento oferece uma única API compatível com a OpenAI e cuida do resto.

O Conceito

Formato de proxy compatível com a OpenAI

Todo mundo fala o formato da OpenAI. O gateway de roteamento expõe /v1/chat/completions, aceita o esquema da OpenAI e, internamente, faz o proxy para Anthropic / Gemini / Cohere / Ollama / qualquer outro. O cliente não se importa.

Aliases de modelo

Em vez de claude-3-5-sonnet-20251022, seu código diz our_smart_model. O gateway mapeia os aliases para modelos reais. Quando a Anthropic lançar o Claude 4, você altera o alias no lado do servidor; seu código permanece intocado.

Cadeias de fallback

primary: openai/gpt-4o
on 5xx: anthropic/claude-3-5-sonnet
on 5xx: google/gemini-1.5-pro
on 5xx: refuse

Os gateways definem isso em uma configuração. As tentativas são contabilizadas em relação a um orçamento para que as cascatas de fallback não estourem os custos.

Cache semântico

Prompts idênticos ou quase idênticos atingem um cache em vez do provedor. A economia em loops de agentes repetidos pode ser de 30 a 60 por cento. As chaves são baseadas em embeddings; prompts quase idênticos compartilham o mesmo espaço de cache.

Guardrails

Nível de gateway:

• Redação de PII (PII redaction). Passagem baseada em Regex ou ML antes de enviar os prompts.
• Violações de políticas. Rejeitar prompts com conteúdo proibido.
• Filtros de saída. Limpar as conclusões (completions) para evitar vazamentos.

Tanto o Portkey quanto o Kong oferecem guardrails opinativos integrados. O LiteLLM os deixa como opcionais.

Limites de taxa por chave

Uma chave de API = uma equipe. Orçamentos por chave evitam que uma única equipe consuma a cota compartilhada. A maioria dos gateways suporta isso.

Escolhas entre auto-hospedado vs gerenciado

O LiteLLM ganha quando você tem uma equipe de SRE e deseja soberania de dados. O OpenRouter ganha quando você quer uma única assinatura e nenhuma infraestrutura. O Portkey ganha quando você precisa de guardrails e conformidade prontos para uso.

Rastreamento de custos

Cada requisição carrega provider, model, input_tokens, output_tokens. Multiplique pelos preços por token de cada modelo (extraídos de uma planilha de preços que o gateway mantém). Agregação por usuário / por equipe / por projeto.

MCP mais roteamento

Um gateway pode rotear tanto chamadas de LLM QUANTO requisições de amostragem (sampling) do MCP. Quando as modelPreferences de uma requisição de amostragem preferem um modelo específico, o gateway traduz para o backend correto. É aqui que a Phase 13 · 17 (MCP gateway) e o gateway de roteamento desta lição às vezes se fundem em um único serviço.

Estratégias de roteamento

• Prioridade estática (Static priority). O primeiro da lista; faz o fallback em caso de erro.
• Balanceamento de carga (Load balancing). Round-robin ou ponderado.
• Sensível ao custo (Cost-aware). Escolhe o modelo mais barato que atenda à latência / qualidade.
• Sensível à latência (Latency-aware). Escolhe o modelo mais rápido nos últimos N minutos.
• Sensível à tarefa (Task-aware). O classificador de prompts roteia codificação para um modelo e sumarização para outro.

Use It

O arquivo code/main.py implementa um gateway de roteamento em cerca de 150 linhas: aceita requisições no formato OpenAI, traduz para stubs de cada provedor, executa uma cadeia de fallback por prioridade, rastreia o custo por requisição e aplica uma etapa de redação de PII nos dados de entrada. Execute-o com três cenários: requisição normal, queda do provedor primário acionando o fallback e vazamento de PII detectado pela redação.

O que observar:

• Dicionário ROUTES: alias -> lista ordenada por prioridade de provedores concretos.
• O loop de fallback tenta novamente em caso de 5xx.
• O rastreador de custos multiplica o uso de tokens pelas tarifas de cada modelo.
• O redator de PII remove padrões com formato de SSN antes de encaminhar.

Ship It

Esta lição produz o arquivo outputs/skill-routing-config-designer.md. Dado um perfil de carga de trabalho (latência, custo, conformidade), a habilidade seleciona LiteLLM / OpenRouter / Portkey e gera uma configuração de roteamento.

Exercícios

1. Execute code/main.py. Acione o cenário de queda; confirme que o fallback vai para o segundo provedor e que o custo é atribuído corretamente.

2. Adicione cache semântico: o SHA256 do prompt é a chave de busca; acertos de cache (cache hits) retornam instantaneamente. Meça a economia de custo em uma chamada repetida.

3. Adicione um classificador de prompts que roteie prompts de "code ..." para um alias que priorize inteligência e prompts de "summarize ..." para um alias que priorize velocidade.

4. Projete orçamentos por equipe: cada equipe tem um limite mensal de gastos; o gateway recusa requisições assim que o limite é atingido. Escolha uma granularidade de aplicação (por requisição ou em janela de tempo).

5. Leia a documentação do LiteLLM, OpenRouter e Portkey lado a lado. Nomeie a funcionalidade exclusiva que cada um oferece e que os outros dois não possuem.

Termos-Chave

Leituras Adicionais

• LiteLLM — documentação — gateway de roteamento auto-hospedado
• OpenRouter — início rápido — SaaS de roteamento gerenciado
• Portkey — documentação — roteamento de produção com guardrails
• TrueFoundry — LiteLLM vs OpenRouter — guia de decisão
• Relayplane — LLM gateway comparison 2026 — levantamento de fornecedores