O que é o LiteLLM

Se você já integrou mais de um modelo de IA no mesmo projeto, conhece a dor: cada provedor tem seu próprio SDK, seu próprio formato de resposta, sua própria forma de contar tokens e de tratar erros. Trocar de OpenAI para Anthropic, ou testar um modelo local no Ollama, vira uma reescrita de código.

O LiteLLM resolve exatamente isso. É um projeto open source criado pela BerriAI, escrito em Python, que expõe mais de 100 provedores de LLM através de uma única interface no formato da API da OpenAI. Você escreve o código uma vez e troca o modelo mudando apenas uma string.

Ele existe em duas formas: uma biblioteca Python (SDK) que você importa no seu código, e um servidor proxy, também chamado de AI Gateway, que roda como serviço na sua infraestrutura e centraliza chaves, custos, limites e logs de todas as chamadas de IA da empresa. É essa segunda forma que está em alta no Dev.to esta semana, com tutoriais de deploy usando Docker e Postgres.

Como funciona

A ideia central é a tradução de formatos. O LiteLLM recebe uma requisição no padrão /chat/completions da OpenAI, identifica o provedor pelo prefixo do nome do modelo (por exemplo anthropic/, bedrock/, ollama/) e converte a chamada para o formato nativo daquele provedor. A resposta volta convertida para o formato OpenAI.

No modo proxy, o LiteLLM sobe um servidor HTTP (por padrão na porta 4000) que aceita as requisições dos seus aplicativos. Qualquer cliente compatível com a API da OpenAI funciona: basta apontar o base_url para o endereço do proxy e usar uma chave virtual gerada pelo próprio LiteLLM em vez da chave real do provedor.

Por trás disso, o proxy usa um banco Postgres para guardar chaves virtuais, orçamentos, times e histórico de gastos, e opcionalmente um Redis para cache de respostas e para compartilhar estado entre várias instâncias. Pense nele como um API Gateway tradicional, só que entende o vocabulário de LLMs: tokens, modelos, custo por milhão e streaming.

Principais recursos

O que faz o LiteLLM se destacar não é só a tradução de formatos, mas o conjunto de recursos operacionais em volta dela. Os principais:

  • API unificada: OpenAI, Anthropic, Google Gemini e Vertex AI, AWS Bedrock, Azure OpenAI, Mistral, Groq, Ollama, vLLM e dezenas de outros, todos com a mesma chamada.
  • Chaves virtuais: gere uma chave por aplicação, time ou usuário, com orçamento e validade próprios, sem expor a chave real do provedor.
  • Rastreamento de custo: cada requisição é precificada automaticamente e registrada no Postgres, com relatórios por chave, modelo e time.
  • Rate limits e orçamentos: limites de requisições por minuto, tokens por minuto e gasto máximo por período, por chave ou por time.
  • Fallbacks e balanceamento: defina vários deployments para o mesmo nome de modelo e o proxy faz retry, failover e distribuição de carga.
  • Cache de respostas: cache em memória ou Redis para prompts repetidos, reduzindo custo e latência.
  • Observabilidade: callbacks prontos para Langfuse, OpenTelemetry, Datadog, Prometheus e outros.
  • Guardrails: hooks para bloquear conteúdo, mascarar dados sensíveis e validar entradas antes de chegar ao modelo.

O diferencial em relação a soluções hospedadas como o OpenRouter é que tudo roda na sua infraestrutura. Os prompts e as respostas não passam por um terceiro, o que importa muito para empresas com dados sensíveis ou exigências da LGPD.

Outro ponto é a interface administrativa. O proxy vem com um painel web onde você cria chaves, define orçamentos, vê gastos por modelo e consulta os logs das requisições sem escrever uma linha de SQL.

Como começar: instalação passo a passo

Existem dois caminhos. O mais rápido para experimentar é o SDK Python. O caminho de produção é o proxy com Docker. Vamos ver os dois.

Passo 1: SDK Python. Instale o pacote e faça uma chamada. A chave do provedor vai na variável de ambiente correspondente, como OPENAI_API_KEY ou ANTHROPIC_API_KEY.

pip install litellm

# exemplo.py
from litellm import completion

resposta = completion(
    model='anthropic/claude-sonnet-5',
    messages=[{'role': 'user', 'content': 'Explique o que é um AI Gateway em uma frase.'}]
)
print(resposta.choices[0].message.content)

Passo 2: proxy local para testes. Instale com o extra proxy, crie um config.yaml com a lista de modelos e suba o servidor.

pip install 'litellm[proxy]'

# config.yaml
model_list:
  - model_name: gpt-rápido
    litellm_params:
      model: openai/gpt-5-mini
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude-forte
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

# subir o proxy
litellm --config config.yaml --port 4000

Passo 3: proxy em produção com Docker. Para ter chaves virtuais, orçamentos e rastreamento de custo, você precisa do Postgres. O jeito mais simples é um Docker-compose.yml com os dois serviços.

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    ports:
      - '127.0.0.1:4000:4000'
    volumes:
      - ./config.yaml:/app/config.yaml
    command: ['--config', '/app/config.yaml']
    environment:
      DATABASE_URL: PostgreSQL://litellm:senha@db:5432/litellm
      LITELLM_MASTER_KEY: sk-troque-esta-chave
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
    depends_on:
      - db
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: senha
      POSTGRES_DB: litellm
    volumes:
      - pgdata:/var/lib/PostgreSQL/data
volumes:
  pgdata:
⚠️
Atenção

A LITELLM_MASTER_KEY é a chave de administrador do proxy. Quem tem ela cria chaves virtuais, altera orçamentos e vê todos os logs. Gere um valor longo e aleatório e nunca a commite no repositório.

Passo 4: crie uma chave virtual. Com o proxy no ar, gere uma chave para a sua aplicação usando a master key. Depois disso, o app nunca mais precisa conhecer as chaves reais dos provedores.

curl -X POST http://127.0.0.1:4000/key/generate \
  -H 'Authorization: Bearer sk-troque-esta-chave' \
  -H 'Content-Type: application/json' \
  -d '{"models": ["gpt-rápido", "claude-forte"], "max_budget": 20, "duration": "30d"}'

Exemplo prático

Imagine um SaaS brasileiro com três serviços que usam IA: um chatbot de atendimento, um resumidor de documentos e um classificador de tickets. Hoje cada um tem a chave da OpenAI hardcoded e ninguém sabe quanto cada serviço gasta por mês.

Com o LiteLLM no meio, o cenário muda. Você sobe o proxy, cadastra os modelos no config.yaml e gera uma chave virtual para cada serviço, cada uma com seu orçamento mensal. Os serviços continuam usando o SDK oficial da OpenAI, só que apontando para o proxy.

from openai import OpenAI

cliente = OpenAI(
    base_url='http://127.0.0.1:4000',
    api_key='sk-chave-virtual-do-chatbot'
)

resposta = cliente.chat.completions.create(
    model='claude-forte',
    messages=[{'role': 'user', 'content': 'Resuma este ticket: cliente não consegue emitir nota fiscal.'}]
)
print(resposta.choices[0].message.content)

Repare que o código chama claude-forte, um apelido definido por você. Se amanhã você quiser trocar o modelo por trás desse apelido, ou adicionar um fallback para a OpenAI quando a Anthropic estiver instável, muda só o config.yaml. Nenhum serviço precisa de deploy.

model_list:
  - model_name: claude-forte
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: claude-forte
    litellm_params:
      model: openai/gpt-5
      api_key: os.environ/OPENAI_API_KEY

router_settings:
  routing_strategy: simple-shuffle
  num_retries: 2

No fim do mês, o painel mostra quanto o chatbot gastou, quanto o resumidor gastou e qual modelo consumiu mais tokens. Se o classificador estourar o orçamento, o proxy bloqueia as chamadas dele sem afetar os outros dois.

💡
Dica

Use nomes de modelo genéricos no config.yaml, como 'rápido', 'forte' e 'barato', em vez de nomes de versão específicos. Assim você atualiza o modelo real quando sair uma versão nova sem mexer nas aplicações.

Comparação com alternativas

O LiteLLM não é o único jogador nessa categoria. Vale entender onde ele se encaixa em relação às opções mais conhecidas.

  • OpenRouter: serviço hospedado que faz a mesma unificação de API, mas os dados passam pelos servidores deles e há uma taxa sobre o uso. Ideal para prototipar rápido, menos ideal para dados sensíveis.
  • Portkey: gateway com versão open source e versão hospedada, foco forte em observabilidade e guardrails. Concorrente direto, com uma interface mais polida no plano pago.
  • Cloudflare AI Gateway: proxy gerenciado na borda, com cache e logs. Ótimo se você já usa Cloudflare, mas menos flexível para rotear entre provedores e definir orçamentos por time.
  • Kong AI Gateway: plugins de IA em cima do Kong tradicional. Faz sentido para quem já tem Kong na infraestrutura e quer tratar LLMs como mais uma API.
  • Helicone: mais voltado para observabilidade e análise de custo do que para roteamento; muitas equipes usam Helicone junto com LiteLLM.

Quando usar cada um: se você quer controle total, self-hosted e gratuito, LiteLLM. Se quer zero operação e aceita passar os dados por terceiros, OpenRouter. Se já tem Kong ou Cloudflare como padrão da empresa, vale avaliar as extensões nativas antes de adicionar mais um componente.

O ponto forte único do LiteLLM é a combinação de SDK e proxy no mesmo projeto, com a maior lista de provedores suportados da categoria e uma comunidade muito ativa. Quase todo provedor novo aparece no LiteLLM dias depois do lançamento.

Pontos positivos e limitações

Do lado positivo, o LiteLLM é gratuito, open source com licença MIT e roda em qualquer lugar que rode Python ou Docker. A curva de aprendizado é baixa para quem já usa a API da OpenAI, porque o formato é o mesmo. O rastreamento de custo por chave sozinho já justifica a adoção em times com mais de dois projetos de IA.

Do lado das limitações, o proxy é um componente a mais na sua infraestrutura, com banco de dados e, opcionalmente, Redis. Ele precisa de monitoramento, backup e atualização como qualquer outro serviço. Se o proxy cair, todas as chamadas de IA caem junto, então alta disponibilidade vira preocupação sua.

Outra limitação real é que a tradução de formatos nem sempre é perfeita. Recursos muito específicos de um provedor, como certos modos de tool use ou parâmetros exclusivos, podem exigir configuração extra ou não funcionar via proxy. A documentação é extensa mas cresceu rápido, e às vezes o comportamento de uma flag muda entre versões. Fixe a versão da imagem Docker em produção.

🔴
Cuidado

Nunca exponha a porta 4000 do proxy diretamente na internet. Coloque o LiteLLM atrás de um reverse proxy com HTTPS (NGINX, Caddy ou Traefik) e restrinja o acesso. As chaves virtuais dão acesso a modelos pagos: vazamento vira conta alta em minutos.

Casos de uso reais

O LiteLLM serve de verdade para quem tem mais de uma aplicação ou mais de um provedor de IA. Alguns perfis onde ele brilha:

  • Startup com vários produtos de IA: uma chave virtual por produto, orçamento por produto e um único lugar para ver o gasto total do mês.
  • Empresa com exigência de LGPD: mantém os prompts dentro da própria infraestrutura, com logs auditáveis e mascaramento de dados pessoais antes de chegar ao modelo.
  • Time de plataforma interna: oferece IA como serviço para os outros times da empresa, com self-service de chaves e relatórios por time, sem distribuir chaves reais dos provedores.
  • Dev solo testando modelos: o SDK permite comparar OpenAI, Anthropic, Gemini e modelos locais no Ollama com o mesmo script, trocando só o nome do modelo.

Um caso muito comum no Brasil é o de agências e consultorias que atendem vários clientes. Cada cliente vira um time no LiteLLM, com suas chaves e orçamentos, e a agência fatura o consumo real de IA de cada um com base nos relatórios do proxy.

Também aparece bastante em projetos de agentes de IA, onde um único fluxo pode fazer dezenas de chamadas a modelos diferentes. Centralizar tudo no gateway evita que o custo saia do controle enquanto o agente está em desenvolvimento.

Dicas e boas práticas

Quem roda LiteLLM em produção há algum tempo costuma seguir alguns padrões que evitam dor de cabeça. Os principais:

💡
Dica

Habilite o cache Redis desde o início, mesmo em ambiente pequeno. Prompts de sistema repetidos e perguntas frequentes de chatbot geram economia imediata, e o cache também protege contra picos quando um provedor fica lento.

🚀
Pro tip

Configure fallbacks entre provedores diferentes, não só entre modelos do mesmo provedor. Uma instabilidade na OpenAI não afeta a Anthropic, e vice-versa. Com dois provedores no mesmo apelido de modelo, seu app sobrevive a incidentes sem intervenção.

⚠️
Atenção

Defina max_budget e duration em toda chave virtual, sem exceção. Chave sem orçamento é convite para gasto descontrolado, principalmente em ambientes de desenvolvimento onde loops de agente podem disparar milhares de chamadas.

🚀
Pro tip

Integre o proxy com o Langfuse ou OpenTelemetry desde o primeiro dia. Ver o prompt exato, a resposta e o custo de cada chamada em um painel economiza horas de debug quando um modelo começa a responder errado.

Erros comuns de iniciantes: rodar o proxy sem Postgres e depois descobrir que as chaves virtuais não persistem; usar a master key nas aplicações em vez de gerar chaves por serviço; e não fixar a versão da imagem Docker, o que traz mudanças de comportamento a cada deploy.

Por fim, trate o config.yaml como código: versione no Git, revise mudanças em pull request e nunca coloque chaves reais nele. Use sempre a sintaxe os.environ/NOME_DA_VARIAVEL para ler das variáveis de ambiente.

Vale a pena?

Para quem tem duas ou mais aplicações usando IA, ou usa mais de um provedor, o LiteLLM vale muito a pena. O controle de custo por chave, os fallbacks automáticos e a liberdade de trocar de modelo sem deploy pagam o custo de operar mais um serviço em poucas semanas.

Para quem tem um único script chamando um único modelo, provavelmente é excesso. Nesse caso o SDK do LiteLLM ainda pode ser útil para manter o código portável entre provedores, mas o proxy completo com Postgres e Redis é mais infraestrutura do que o problema pede.

O próximo passo sugerido é simples: instale o SDK, rode o exemplo de completion com dois provedores diferentes e sinta a diferença de trocar o modelo com uma string. Se gostar, suba o proxy com Docker Compose num servidor de testes e crie a primeira chave virtual com orçamento. A partir daí, a adoção nos outros projetos é natural.