Ter uma app que fala com a OpenAI é fácil. Ter uma app que fala com a OpenAI, a Anthropic, o Gemini e o DeepSeek ao mesmo tempo, sem reescrever o código sempre que troca de fornecedor, já é outra história. É exatamente esse problema que o LiteLLM resolve. Este tutorial mostra, passo a passo, como instalar, configurar e colocar em produção um gateway LiteLLM completo, com chaves virtuais, balanceamento de carga, cache e monitorização incluídos.

No final vai ter um projeto funcional: um proxy único que expõe um endpoint compatível com a API da OpenAI e que, por trás, distribui pedidos por vários modelos, controla orçamentos por equipa e faz fallback automático quando um fornecedor falha.

O Que É o LiteLLM e Porque Precisa de um Gateway de IA

O LiteLLM é um gateway de IA de código aberto mantido pela BerriAI, disponível em github.com/BerriAI/litellm. A proposta é simples: em vez de integrar o SDK de cada fornecedor de LLM separadamente, a sua aplicação fala sempre com um único endpoint, no formato da API da OpenAI, e o LiteLLM trata do resto. Isto inclui traduzir o pedido para o formato exigido por cada fornecedor, seja a Anthropic, o Google Gemini, a AWS Bedrock, o Azure OpenAI, a xAI ou a Mistral.

Segundo o repositório oficial no GitHub, o projeto já soma cerca de 57 mil estrelas e mais de 11 mil forks, com lançamentos praticamente semanais. A versão mais recente à data deste tutorial é a v1.98.0, lançada a 22 de agosto de 2026, que introduziu faturação para capacidade reservada (provisioned throughput billing), avaliações-sombra do router automático e grupos de rotas configuráveis. Duas semanas antes, a v1.95.0 já tinha trazido suporte ao Claude Opus 5 e um núcleo reescrito em Rust, pensado para reduzir a latência do proxy.

O ritmo de lançamentos não é acidental. Um resumo interno da equipa, publicado em agosto de 2026, refere 43 modelos novos ou atualizados apenas na versão v1.85.0, além de 24 novos endpoints de API e 54 endpoints de gestão e interface. É esta cobertura ampla de fornecedores, combinada com atualizações frequentes, que torna o LiteLLM uma escolha razoável quando a lista de modelos que a sua equipa quer testar muda mês a mês, algo cada vez mais comum com o ritmo atual de lançamentos de novos modelos por parte da OpenAI, da Anthropic, da Google e de laboratórios chineses como a DeepSeek.

Este tipo de ferramenta chama-se, no jargão do setor, um AI gateway: fica entre a aplicação e os fornecedores de modelos, e resolve problemas que aparecem assim que uma equipa passa de “testar um modelo” para “correr vários modelos em produção”. Chaves de API espalhadas por dezenas de serviços, sem controlo central. Faturas que disparam sem se perceber qual equipa gastou o quê. Um fornecedor em baixo que derruba a aplicação inteira porque não há plano B. É a este conjunto de dores que o LiteLLM responde, e é por isso que faz sentido dedicar um tutorial completo a montá-lo do zero. A documentação oficial em docs.litellm.ai descreve o projeto precisamente como um gateway “unificado”, termo que resume bem a ideia central: uma única porta de entrada para dezenas de fornecedores diferentes.

Porque Trocar Integrações Diretas por um Gateway Central

Antes de instalar seja o que for, vale a pena perceber quando é que este esforço extra compensa. Uma app com um único modelo e um único fornecedor não precisa de gateway algum: chamar o SDK da OpenAI diretamente é mais simples e tem menos peças móveis. O cálculo muda assim que aparece o segundo fornecedor, ou a segunda equipa a partilhar a mesma conta.

Há três sinais concretos de que chegou a essa fase. Primeiro, quando perde tempo a decidir “que chave uso neste projeto” porque há mais do que uma espalhada por ficheiros de configuração diferentes. Segundo, quando um incidente com um fornecedor (uma quebra de serviço, um limite de taxa atingido) já afetou a produção sem que houvesse alternativa automática. Terceiro, quando a fatura mensal cresce e ninguém consegue dizer, com confiança, qual equipa ou funcionalidade gerou a maior parte do custo. O documento sobre os dez maiores riscos em aplicações de LLM, publicado pela OWASP, também aponta a falta de controlo centralizado sobre o consumo de modelos como um fator que amplia o impacto de configurações mal feitas ou de uso indevido de credenciais. Um gateway como o LiteLLM não elimina esse risco sozinho, mas dá o ponto único onde aplicar limites, auditoria e revogação de acesso.

Vale ainda notar que este problema não é exclusivo de grandes empresas. Uma equipa de três programadores a testar dois modelos diferentes já sente a fricção de gerir chaves separadas, ficheiros .env divergentes entre máquinas e nenhuma forma fácil de comparar o custo real de um modelo contra o outro. É esse o público a que este tutorial se dirige: não só grandes plataformas, mas qualquer equipa que já passou de “um modelo, uma app” para “vários modelos, várias apps”.

Pré-requisitos: Versões e Ferramentas Necessárias

Antes de avançar, confirme que tem estas ferramentas instaladas. A tabela abaixo lista as versões mínimas recomendadas para seguir este tutorial sem sobressaltos.

FerramentaVersão mínimaPara que serve
Python3.10 ou superiorCorrer o LiteLLM via pip e o SDK Python
Docker + Docker ComposeDocker 24+, Compose v2Implementação em contentores para produção
LiteLLMv1.98.0 (a mais recente)O próprio gateway/proxy
PostgreSQL15 ou 16Guardar chaves virtuais, orçamentos e histórico de custos
Redis7.xCache de respostas e limites de taxa distribuídos
curl ou PostmanQualquer versão recenteTestar o endpoint depois de configurado

Precisa também de pelo menos uma chave de API de um fornecedor de LLM (OpenAI, Anthropic, Google ou Mistral, por exemplo) para testar o gateway com pedidos reais. Se ainda não configurou nenhuma, o nosso guia prático da API Claude explica como obter e gerir uma chave da Anthropic.

Se nunca instalou o Python no seu sistema, a página oficial em python.org tem instaladores para Windows, macOS e Linux. Quanto ao PostgreSQL e ao Redis, não precisa de os instalar manualmente na máquina: neste tutorial, ambos correm dentro de contentores Docker, geridos automaticamente pelo docker-compose.yml que vamos escrever no Passo 4. Ainda assim, vale a pena conhecer a documentação de referência do PostgreSQL e do Redis, sobretudo se mais tarde quiser afinar parâmetros de desempenho além da configuração base usada aqui.

Passo 1: Instalar o LiteLLM Localmente

O caminho mais rápido para experimentar é instalar o pacote Python com o SDK e o proxy incluídos. Abra um terminal e crie um ambiente virtual antes de instalar, para não misturar dependências com outros projetos.

python3 -m venv litellm-env
source litellm-env/bin/activate
pip install 'litellm[proxy]'

# confirmar a instalação
litellm --version

Se preferir evitar dependências Python na máquina local, pode saltar diretamente para a imagem Docker oficial, que a equipa da BerriAI publica em ghcr.io/berriai/litellm:latest como canal “rolling stable”. Vamos usar essa imagem já no Passo 4, quando montarmos a stack de produção.

Passo 2: Criar o Primeiro Proxy em 60 Segundos

Antes de complicar com Docker, PostgreSQL e Redis, vale a pena ver o gateway a funcionar com a configuração mais simples possível: um único modelo, sem base de dados. Defina a variável de ambiente com a sua chave da OpenAI e arranque o proxy diretamente pela linha de comandos.

export OPENAI_API_KEY="sk-a-sua-chave-aqui"

litellm --model gpt-4o-mini --port 4000

# noutro terminal, teste o endpoint
curl http://localhost:4000/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Diz olá em português"}]
  }'

Repare que o pedido curl não usa o SDK da OpenAI nem nenhuma biblioteca específica: é um pedido HTTP simples, no formato padrão da API OpenAI. É esta compatibilidade que permite, mais tarde, trocar de modelo ou de fornecedor sem tocar no código da aplicação, só mudando o parâmetro model. Se tudo estiver bem configurado, a resposta deve parecer-se com isto:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Olá! Como posso ajudar hoje?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 9,
    "total_tokens": 21
  }
}

Note que a estrutura da resposta é idêntica à que receberia diretamente da OpenAI. Se em vez disso vir um erro de terminal como Connection refused, avance para a secção de resolução de problemas mais adiante neste artigo, que cobre este e outros erros comuns.

Passo 3: Escrever o Ficheiro config.yaml Multi-Fornecedor

O verdadeiro valor do LiteLLM aparece quando junta vários fornecedores no mesmo gateway. Isto faz-se através de um ficheiro config.yaml, onde cada entrada em model_list associa um nome lógico (o que a sua app vai pedir) a um modelo real de um fornecedor específico.

model_list:
  - model_name: gpt-4o-mini
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

  - model_name: claude-opus
    litellm_params:
      model: anthropic/claude-opus-4-8
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: gemini-flash
    litellm_params:
      model: gemini/gemini-2.5-flash
      api_key: os.environ/GEMINI_API_KEY

  - model_name: deepseek-chat
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: os.environ/DEEPSEEK_API_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

Note o prefixo os.environ/: é assim que o LiteLLM lê segredos a partir de variáveis de ambiente em vez de os deixar escritos em texto simples no ficheiro. A tabela seguinte resume alguns dos fornecedores que pode combinar desta forma, com o prefixo correspondente a usar no campo model.

FornecedorPrefixo no config.yamlExemplo de modelo
OpenAIopenai/openai/gpt-4o-mini
Anthropicanthropic/anthropic/claude-opus-4-8
Google Geminigemini/gemini/gemini-2.5-flash
DeepSeekdeepseek/deepseek/deepseek-chat
Mistralmistral/mistral/mistral-large-latest
AWS Bedrockbedrock/bedrock/anthropic.claude-v2
Azure OpenAIazure/azure/o-nome-do-seu-deployment

Se já experimentou correr modelos localmente com o Ollama ou o LM Studio, pode também apontar o LiteLLM para esses servidores locais, usando o prefixo ollama/ ou um endpoint compatível com OpenAI, o que permite misturar modelos locais e modelos na nuvem atrás do mesmo gateway.

Passo 4: Subir o Proxy em Produção com Docker Compose e PostgreSQL

Para uso a sério, o LiteLLM recomenda ligar o proxy a uma base de dados PostgreSQL, onde guarda chaves virtuais, orçamentos e histórico de gastos. O Redis entra como camada de cache e de limitação de taxa partilhada entre várias réplicas do proxy. Crie um ficheiro docker-compose.yml com os três serviços.

services:
  litellm:
    image: ghcr.io/berriai/litellm:latest
    ports:
      - "4000:4000"
    environment:
      - DATABASE_URL=postgresql://litellm:senha@db:5432/litellm
      - REDIS_URL=redis://cache:6379
      - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    volumes:
      - ./config.yaml:/app/config.yaml
    command: ["--config", "/app/config.yaml"]
    depends_on:
      - db
      - cache

  db:
    image: postgres:16
    environment:
      - POSTGRES_USER=litellm
      - POSTGRES_PASSWORD=senha
      - POSTGRES_DB=litellm
    volumes:
      - litellm_pgdata:/var/lib/postgresql/data

  cache:
    image: redis:7

volumes:
  litellm_pgdata:

Suba a stack com docker compose up -d e confirme que os três contentores arrancam sem erros com docker compose ps. Da primeira vez, o LiteLLM cria automaticamente as tabelas necessárias na base de dados PostgreSQL, um processo que costuma demorar poucos segundos.

Passo 5: Testar o Endpoint Compatível com a API OpenAI

Com o proxy no ar, o teste mais direto é reaproveitar o SDK oficial da OpenAI, apontando apenas para o URL base do seu LiteLLM em vez do URL da OpenAI. É esta compatibilidade de formato que evita ter de reescrever integrações já existentes.

from openai import OpenAI

client = OpenAI(
    api_key="sk-litellm-a-sua-chave-virtual",
    base_url="http://localhost:4000"
)

resposta = client.chat.completions.create(
    model="claude-opus",
    messages=[{"role": "user", "content": "Resume em 3 linhas o que é um AI gateway"}]
)

print(resposta.choices[0].message.content)

Repare que o campo model agora é claude-opus, o nome lógico que definiu no config.yaml, mesmo que por trás o pedido siga para a Anthropic. Se o pedido devolver uma resposta e não um erro 401 ou 500, o gateway está a funcionar corretamente e a rotear entre fornecedores como esperado.

Passo 6: Criar Virtual Keys com Orçamentos e Limites de Taxa

Distribuir a sua chave mestra por toda a equipa é uma má ideia: perde controlo sobre quem gasta o quê e não consegue revogar o acesso de uma pessoa sem trocar a chave para todos. As virtual keys resolvem isso, criando chaves derivadas com orçamento, limite de pedidos por minuto e acesso restrito a determinados modelos.

curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["gpt-4o-mini", "claude-opus"],
    "max_budget": 50,
    "budget_duration": "30d",
    "rpm_limit": 100,
    "metadata": {"equipa": "produto"}
  }'

A resposta devolve uma nova chave no formato sk-..., pronta a distribuir à equipa de produto, com um corpo semelhante a este:

{
  "key": "sk-litellm-9f3a2b7c8d1e4f5a",
  "models": ["gpt-4o-mini", "claude-opus"],
  "max_budget": 50.0,
  "budget_duration": "30d",
  "rpm_limit": 100,
  "spend": 0.0,
  "metadata": {"equipa": "produto"}
}

Quando o gasto acumulado (o campo spend) atingir os 50 euros definidos no exemplo, o LiteLLM passa a recusar novos pedidos feitos com essa chave até ao início do próximo ciclo de 30 dias, sem que precise de intervir manualmente. Pode consultar o gasto atual de qualquer chave a qualquer momento fazendo um pedido GET ao endpoint /key/info, o que é útil para montar um relatório simples de custos por equipa sem depender do painel gráfico.

Passo 7: Configurar Load Balancing e Fallback Automático

Um fornecedor de LLM em baixo, mesmo que por poucos minutos, pode derrubar toda a sua aplicação se não houver plano B. O LiteLLM resolve isto com grupos de modelos: define várias entradas com o mesmo model_name, apontando para deployments diferentes, e o proxy distribui os pedidos entre elas ou avança para a seguinte se uma falhar.

model_list:
  - model_name: assistente-producao
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY
  - model_name: assistente-producao
    litellm_params:
      model: azure/gpt4o-deployment
      api_key: os.environ/AZURE_API_KEY

router_settings:
  routing_strategy: usage-based-routing-v2
  fallbacks: [{"assistente-producao": ["claude-opus"]}]
  num_retries: 2

Com esta configuração, os pedidos para assistente-producao alternam entre a OpenAI e o Azure conforme a carga, e se ambos falharem, o router tenta ainda o modelo claude-opus antes de devolver erro ao utilizador final. A versão v1.98.0 do LiteLLM acrescentou a este mecanismo os chamados “routing groups”, que permitem agrupar várias regras de fallback sob um único nome reutilizável em múltiplas apps.

Passo 8: Ativar Cache com Redis

Muitos pedidos repetem-se, sobretudo em apps com prompts de sistema fixos ou perguntas frequentes. Guardar essas respostas em cache poupa dinheiro e reduz a latência sentida pelo utilizador. Como já tem o Redis a correr desde o Passo 4, basta ativar a opção no ficheiro de configuração.

litellm_settings:
  cache: true
  cache_params:
    type: redis
    host: cache
    port: 6379
    ttl: 3600

Com um TTL de 3600 segundos, uma pergunta idêntica feita dentro de uma hora devolve a resposta guardada em Redis em vez de gerar uma nova chamada ao fornecedor, o que é particularmente útil em ambientes de teste e demonstração onde os mesmos prompts se repetem várias vezes ao dia.

Passo 9: Monitorização com Prometheus e Registo de Logs

Sem visibilidade sobre latência, taxa de erros e custo por modelo, é impossível saber se o gateway está de facto a poupar dinheiro ou a introduzir problemas novos. O LiteLLM expõe métricas no formato Prometheus diretamente no endpoint /metrics, prontas a serem recolhidas (scraped) por uma instância existente.

# prometheus.yml
scrape_configs:
  - job_name: 'litellm'
    scrape_interval: 15s
    static_configs:
      - targets: ['litellm:4000']
    metrics_path: /metrics

Nas notas de lançamento mais recentes, a equipa do LiteLLM descreve uma revisão alargada da observabilidade, com correções de cardinalidade de etiquetas no Prometheus, isolamento do handler OpenTelemetry e registo de auditoria configurável para armazenamento em S3. Se já usa o vLLM com Docker para servir modelos localmente, o mesmo painel Prometheus pode agregar métricas de ambos os sistemas.

Além das métricas técnicas, o proxy regista também eventos de negócio: qual virtual key fez o pedido, quanto custou em euros e quantos tokens foram gastos de entrada e de saída. Esses dados ficam disponíveis tanto pelo endpoint de métricas como pelo painel de administração incluído (acessível em /ui), o que evita ter de montar um painel Grafana só para acompanhar gastos no dia a dia. Para equipas maiores, ligar essas métricas a um sistema de alertas (por exemplo, um aviso quando o custo diário ultrapassa um limite) costuma ser o passo seguinte natural depois de a monitorização básica estar a funcionar.

Passo 10: Ligar o Cursor, o Claude Code e o Continue ao Proxy

Uma das razões práticas para montar um gateway central é usar o mesmo ponto de entrada em várias ferramentas de programação assistida por IA, sem espalhar chaves de API por cada uma. A maioria destas ferramentas aceita um URL base personalizado, exatamente como fez no Passo 5.

  • Cursor: em Settings → Models, ative “Override OpenAI Base URL” e aponte para http://localhost:4000, usando uma virtual key como chave de API.
  • Continue (extensão VS Code): no ficheiro config.json, defina "apiBase": "http://localhost:4000" dentro do bloco do modelo escolhido.
  • Scripts próprios ou agentes internos: basta reutilizar o SDK oficial da OpenAI, como no Passo 5, apontando o base_url para o proxy.

Desta forma, cada ferramenta continua a “achar” que está a falar com a OpenAI, mas todos os pedidos passam pelo mesmo gateway, com o mesmo controlo de orçamento e os mesmos registos de auditoria centralizados.

Passo 11: Checklist de Segurança Antes de Ir para Produção

Antes de expor o gateway fora da sua rede local, vale a pena rever alguns pontos que costumam ser esquecidos numa primeira instalação.

ItemPorque importa
Nunca reutilizar a master_key como virtual keyA master_key tem acesso total, e uma fuga expõe orçamento e configuração inteiros
Colocar o proxy atrás de HTTPS/TLSAs chaves de API circulam em texto nos cabeçalhos dos pedidos
Definir max_budget em todas as virtual keysEvita faturas inesperadas em caso de erro de código ou uso indevido
Atualizar regularmente para a versão mais recenteO LiteLLM já corrigiu CVEs em dependências como o aiohttp em atualizações recentes
Restringir o /ui de administração por IP ou VPNO painel de gestão não deve ficar acessível publicamente

Vale referir que a Spring publicou, a 20 de agosto de 2026, um alerta de segurança (CVE-2026-59318) sobre como a chamada de ferramentas em frameworks de IA pode ser explorada por injeção de prompt para acionar ações não pretendidas. Não é uma falha do LiteLLM em si, mas reforça a mesma lição válida para qualquer gateway de IA: nunca dê a um modelo acesso a ferramentas com mais permissões do que seria dado a um utilizador não confiável.

Para equipas em Portugal ou noutros países da União Europeia, há ainda um ponto extra a verificar: onde ficam fisicamente alojados os dados que passam pelo gateway. O PostgreSQL e o Redis descritos neste tutorial correm na sua própria infraestrutura, o que dá controlo total sobre a localização dos dados. Já os fornecedores de modelos ligados ao LiteLLM (OpenAI, Anthropic, Google, entre outros) processam os pedidos nos seus próprios servidores, muitas vezes fora da UE. Antes de enviar dados de clientes através do gateway, vale a pena confirmar os termos de processamento de dados de cada fornecedor específico que escolher usar.

Passo 12: Projeto Completo – Gateway Multi-Fornecedor do Zero

Juntando todos os passos anteriores, o projeto final fica organizado em quatro ficheiros. Esta estrutura é suficiente para levar um gateway LiteLLM para produção com múltiplos fornecedores, cache, orçamentos e monitorização.

meu-gateway-litellm/
├── docker-compose.yml       # proxy + PostgreSQL + Redis
├── config.yaml              # model_list, router_settings, cache
├── prometheus.yml           # scrape config para métricas
└── .env                     # chaves de API e master_key (nunca versionado)

Para arrancar o projeto do zero: crie a pasta, cole os quatro ficheiros com o conteúdo dos passos anteriores, preencha o .env com as suas chaves reais e corra docker compose up -d. Em menos de um minuto tem um endpoint em http://localhost:4000 capaz de rotear entre OpenAI, Anthropic, Gemini e DeepSeek, com chaves virtuais, cache e métricas prontas a consultar. A partir daqui, qualquer aplicação nova na sua equipa integra-se apontando para este único URL, em vez de negociar acesso a cada fornecedor individualmente.

Erros Comuns ao Configurar o LiteLLM

Estes são os enganos mais frequentes de quem configura o LiteLLM pela primeira vez, reunidos a partir da documentação oficial e de relatos de configuração da comunidade.

  • Esquecer o prefixo do fornecedor no campo model: escrever apenas gpt-4o-mini em vez de openai/gpt-4o-mini faz o LiteLLM tentar adivinhar o fornecedor, o que nem sempre corre bem.
  • Guardar chaves de API diretamente no config.yaml: além do risco de segurança se o ficheiro for para um repositório público, dificulta trocar chaves sem reiniciar o proxy manualmente.
  • Não definir max_budget nas virtual keys: sem limite, um bug num script de testes pode gerar milhares de pedidos e uma fatura elevada antes de alguém dar por isso.
  • Correr o proxy sem PostgreSQL em produção: sem base de dados persistente, perde todo o histórico de chaves e gastos a cada reinício do contentor.
  • Ignorar as notas de lançamento: como o LiteLLM lança versões menores praticamente todas as semanas, saltar várias versões de uma vez aumenta o risco de mudanças que quebram configurações antigas.

Resolução de Problemas (Troubleshooting)

Se algo correr mal durante a instalação, comece por aqui antes de procurar ajuda externa.

  • Erro “Connection refused” na porta 4000: confirme que o contentor litellm está mesmo a correr com docker compose ps e que não há outro serviço a usar a mesma porta.
  • Erro 401 Unauthorized em todos os pedidos: verifique se está a usar uma virtual key válida e não a chave original do fornecedor no cabeçalho Authorization.
  • Erro “model not found”: o nome pedido no JSON tem de corresponder exatamente ao model_name definido no config.yaml, incluindo maiúsculas e minúsculas.
  • Contentor da base de dados a reiniciar em ciclo: normalmente indica que o volume do PostgreSQL ficou corrompido de uma tentativa anterior. Remova o volume com docker volume rm e deixe o LiteLLM recriar as tabelas do zero.
  • Cache não parece funcionar: confirme que o Redis está acessível a partir do contentor litellm pela rede interna do Docker Compose, não pelo localhost da máquina anfitriã.
  • Custos não aparecem no dashboard: o registo de custos depende do PostgreSQL estar ligado. Sem a variável DATABASE_URL configurada, o LiteLLM continua a funcionar, mas sem guardar histórico persistente de gastos.
  • Fallback não é acionado quando o fornecedor principal falha: reveja se o router_settings tem mesmo a chave fallbacks bem formatada, um erro comum é confundir o formato de lista com o de dicionário.
  • Latência alta mesmo com cache ativo: um TTL muito curto ou prompts ligeiramente diferentes a cada pedido (por exemplo, com timestamps embutidos) impedem que o cache encontre correspondências.

Dicas Avançadas: Routing Groups, Shadow Evals e Auto-Router

Depois de dominar o básico, vale explorar três funcionalidades mais recentes do LiteLLM. Os “shadow evals”, introduzidos na v1.98.0, permitem correr um modelo alternativo em paralelo, sem devolver a resposta ao utilizador, apenas para comparar qualidade e custo antes de o promover a produção. Os “routing groups” agrupam regras de fallback complexas sob um nome único, reutilizável em vários projetos sem duplicar configuração. E o Auto Router, referido num artigo de blog da equipa do LiteLLM publicado em agosto de 2026, tenta escolher automaticamente entre modelos de gama alta e baixa consoante a complexidade do pedido, com resultados internos descritos como próximos da qualidade do Claude Opus a um custo até 27% inferior.

Faz também sentido perceber onde o LiteLLM se encaixa face a alternativas próximas. A tabela seguinte resume as diferenças mais relevantes.

FerramentaTipoPonto forte
LiteLLMGateway/proxy self-hosted, código abertoControlo total, chaves virtuais, observabilidade própria
OpenRouterMarketplace/agregador alojadoAcesso rápido a muitos modelos sem infraestrutura própria
PortkeyGateway gerido, com camada open sourceInterface pronta a usar, menos configuração manual

Uma diferença prática vale a pena destacar: o LiteLLM pode, inclusive, apontar para o próprio OpenRouter como mais um fornecedor dentro do model_list, o que mostra como estas ferramentas não são necessariamente mutuamente exclusivas. Se já testou o chatbot RAG com a API da Mistral, a mesma lógica de configuração aplica-se ao adicionar a Mistral como fornecedor dentro do LiteLLM.

Quanto Pode Poupar com Routing Inteligente

Um dos argumentos mais fortes a favor de um gateway é financeiro, não apenas técnico. Nem todos os pedidos precisam do modelo mais caro disponível: uma pergunta simples de apoio ao cliente não exige a mesma capacidade que uma tarefa complexa de raciocínio em código. O Auto Router do LiteLLM, mencionado nas notas de lançamento de agosto de 2026, tenta automatizar essa escolha, direcionando pedidos simples para modelos mais baratos e reservando os modelos de topo para pedidos que realmente os justificam. A tabela seguinte ilustra, de forma simplificada, o tipo de decisão que esse router automatiza.

Tipo de pedidoModelo tipicamente usadoRacional
Pergunta curta, resposta direta (FAQ, resumo simples)Modelo compacto (ex: gpt-4o-mini, gemini-flash)Baixa complexidade, latência e custo mais importantes que profundidade
Análise de código, raciocínio em várias etapasModelo de topo (ex: claude-opus)Qualidade da resposta compensa o custo mais elevado
Geração em lote, alto volume, baixa criticidadeModelo mais barato disponível, com cache ativoVolume elevado torna o custo por pedido decisivo
Pedido crítico com fornecedor principal indisponívelModelo de fallback definido no router_settingsContinuidade do serviço prevalece sobre a escolha ideal de modelo

Não existe uma fórmula universal: a poupança real depende da distribuição real dos pedidos da sua aplicação. Ainda assim, a lógica por trás desta tabela é o ponto de partida recomendado pela própria equipa do LiteLLM antes de ativar o Auto Router em produção: mapear manualmente que tipos de pedido existem na sua aplicação e só depois decidir que modelos atribuir a cada categoria.

Manutenção e Boas Práticas de Atualização

Como o LiteLLM segue um ritmo de lançamento praticamente semanal, a equipa do projeto recomenda uma disciplina simples: versões menores (minor) trazem funcionalidades novas todas as semanas, enquanto versões de correção (patch) ficam reservadas apenas para resolver problemas urgentes. Num recapitulativo interno de agosto de 2026, a equipa referiu 79 correções de segurança, 375 correções de bugs e 142 alterações de funcionalidades nos lançamentos recentes, além da criação de um cargo de Diretor de Segurança e de um painel público de estado do serviço.

Na prática, isto significa duas coisas para quem gere um gateway em produção: primeiro, vale a pena rever as notas de lançamento antes de atualizar, mesmo que seja só uma vez por mês. Segundo, atualizações de segurança não devem ser adiadas, já que dependências como o aiohttp já tiveram múltiplas CVEs corrigidas em versões recentes da stack.

Um padrão que funciona bem para equipas pequenas é fixar a versão da imagem Docker (em vez de usar sempre :latest) e testar cada atualização primeiro num ambiente de homologação, com tráfego reduzido, antes de a promover para produção. Como o formato do config.yaml tem-se mantido relativamente estável entre versões menores, a maior parte das atualizações não exige alterações na configuração, mas vale sempre confirmar isso nas notas de lançamento antes de atualizar um sistema já em produção.

Perguntas Frequentes

O LiteLLM é gratuito?
Sim, o gateway principal e o SDK Python são código aberto e gratuitos para autoalojar, sem limite de pedidos imposto pelo próprio projeto. A empresa por trás do projeto também oferece funcionalidades empresariais adicionais, como suporte dedicado e recursos de governação mais avançados, mas os preços específicos dessa camada não são divulgados publicamente na documentação atual. Para a maioria das equipas que seguiram este tutorial, a versão open source é suficiente.

Preciso de PostgreSQL para usar o LiteLLM?
Não para testar localmente, como fez no Passo 2, onde o proxy corre sem qualquer base de dados. Mas para produção, com chaves virtuais, orçamentos e histórico de custos persistente entre reinícios, o PostgreSQL é necessário, conforme mostrado no Passo 4. Sem ele, cada reinício do contentor apaga o histórico acumulado de gastos e chaves criadas.

O LiteLLM funciona com modelos locais como o Ollama?
Sim. Pode apontar uma entrada do model_list para um servidor Ollama local, misturando modelos que correm na sua própria máquina com modelos na nuvem atrás do mesmo gateway. Isto é particularmente útil em fases de desenvolvimento, quando quer testar sem gastar créditos de API, e só trocar para um modelo pago quando o código estiver pronto para produção.

Qual a diferença entre o LiteLLM e o OpenRouter?
O OpenRouter é um marketplace alojado que dá acesso a muitos modelos através de uma única conta, sem que precise de gerir infraestrutura própria. O LiteLLM é um gateway que aloja você mesmo, com mais controlo sobre chaves, orçamentos e observabilidade, e que pode inclusivamente usar o OpenRouter como mais um fornecedor dentro da sua configuração. A escolha entre um e outro depende de quanto controlo e personalização a sua equipa precisa, contra quanto tempo de manutenção está disposta a assumir.

É seguro expor o proxy LiteLLM publicamente?
Só com HTTPS, autenticação por virtual keys e, idealmente, o painel de administração restrito a uma rede privada ou VPN, como descrito no Passo 11. Expor o endpoint /key/generate sem proteção adequada, por exemplo, permitiria a qualquer pessoa com acesso à rede criar chaves com orçamento próprio, o que anula todo o propósito de controlo de custos.

O LiteLLM suporta a API Realtime da OpenAI?
Sim, desde a versão v1.85.0, com suporte de primeira classe à API Realtime, incluindo informação de preços e registo dedicado dos pedidos no endpoint /openai/v1/realtime. Isto é relevante para quem está a construir aplicações de voz ou assistentes com resposta em tempo real, que dependem desse tipo de ligação persistente em vez de pedidos e respostas isolados.

Como monitorizo custos por equipa ou por projeto?
Atribuindo metadata a cada virtual key, como fez no Passo 6, e consultando depois o histórico guardado no PostgreSQL ou o painel /ui incluído no proxy. Também pode exportar essas métricas para o Prometheus, como mostrado no Passo 9, e construir alertas automáticos quando uma equipa se aproxima do seu orçamento mensal.

Vale a pena usar o LiteLLM numa aplicação pequena, com um único fornecedor?
Nem sempre. Se a aplicação usa apenas um modelo e não precisa de orçamentos por equipa nem de fallback, integrar o SDK do fornecedor diretamente pode ser mais simples e evita uma peça extra de infraestrutura para manter. O LiteLLM compensa quando há múltiplos fornecedores, múltiplas equipas a partilhar orçamento, ou a necessidade de trocar de modelo sem alterar código em produção.