LiteLLM Proxy: 1 API para 100+ LLMs (Configuração Docker em 15 min)

LiteLLM Proxy: 1 API para 100+ LLMs (Configuração Docker em 15 min)

A sua equipa partilha chaves da API da OpenAI em mensagens diretas no Slack. Ninguém sabe quem gastou 400 $ na terça-feira passada. Não existe limitação de taxa, não há plano de contingência quando um fornecedor fica indisponível e mudar do GPT-4o para o Claude implica alterar código em doze sítios diferentes. Soa familiar? Um gateway LLM autoalojado resolve tudo isto, e o proxy LiteLLM é a opção open-source mais popular, um único ponto de acesso compatível com a OpenAI que encaminha pedidos para mais de 100 fornecedores de LLM.

Este guia abrange toda a configuração do proxy litellm: Docker Compose com PostgreSQL, chaves virtuais de equipa com orçamentos, monitorização de custos, limites de taxa e ligação de IDEs de IA como o Claude Code e o Cursor. Se está a avaliar ferramentas de gateway LLM, este é o tutorial prático que o leva do zero à produção.

Uma nota importante antes de começarmos: o SDK da LiteLLM (a biblioteca Python) e o Servidor Proxy são coisas distintas. O SDK serve para um único programador chamar várias APIs de LLM a partir de Python. O proxy destina-se a equipas, funcionando como um servidor interposto entre as suas aplicações e os fornecedores de LLM. Se é um programador solo a escrever um script, o SDK é suficiente. Se gere chaves, orçamentos e acessos para uma equipa, precisa do proxy. É isso que vamos configurar aqui.

Resumo do Proxy LiteLLM

Eis como os métodos de implementação se comparam:

Para a maioria das equipas, o Docker Compose com PostgreSQL é o ponto ideal. É para isso que vamos caminhar, mas primeiro, vamos colocar um proxy a funcionar em 60 segundos.

Pré-requisitos e Configuração do Ambiente

Antes de começar, certifique-se de que tem:

• Docker e Docker Compose instalados (o Docker Desktop inclui ambos)
• Pelo menos uma chave de API de LLM (OpenAI, Anthropic ou uma instância local do Ollama)
• Familiaridade básica com terminal / CLI

Verifique se o Docker está pronto e exporte as suas chaves de API:

# Check Docker is installed
docker --version
docker compose version

# Export your LLM API keys (add to your shell profile for persistence)
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Optional: set a master key for your proxy (you'll need this later)
export LITELLM_MASTER_KEY="sk-master-your-secret-key"

É tudo. Não é necessária nenhuma versão especial de Python nem ferramentas específicas do sistema operativo. Se o Docker funcionar na sua máquina, está pronto.

Início Rápido: O Seu Primeiro Proxy LiteLLM em 60 Segundos

Um comando para iniciar um proxy com o GPT-4o:

docker run -d \
  --name litellm-proxy \
  -p 4000:4000 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e LITELLM_MASTER_KEY=$LITELLM_MASTER_KEY \
  ghcr.io/berriai/litellm:main-stable \
  --model openai/gpt-4o

Teste com curl:

curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Say hello from LiteLLM"}]
  }'

Ou teste a partir de Python:

from openai import OpenAI

# Point the standard OpenAI SDK at your proxy
client = OpenAI(
    api_key="sk-master-your-secret-key",
    base_url="http://localhost:4000/v1"
)

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Say hello from LiteLLM"}]
)
print(response.choices[0].message.content)

O que acabou de acontecer? O seu código comunica com localhost:4000 utilizando o formato padrão do SDK da OpenAI. O proxy recebe o pedido, reencaminha-o para a API da OpenAI com a chave real e devolve a resposta. O código da sua aplicação nunca toca na chave de API real.

Esta é a ideia central. Agora vamos construir uma configuração de produção.

Configuração de Produção com Docker Compose e PostgreSQL

O comando único docker run funciona para testes, mas as equipas de produção necessitam de monitorização persistente de custos, chaves virtuais e armazenamento adequado em base de dados. Isso significa Docker Compose com PostgreSQL.

O Ficheiro Docker Compose

# docker-compose.yml
version: "3.9"

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-stable
    container_name: litellm-proxy
    ports:
      - "4000:4000"         # Proxy API port
    volumes:
      - ./config.yaml:/app/config.yaml   # Mount your config file
    environment:
      - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - DATABASE_URL=postgresql://litellm:litellm_password@postgres:5432/litellm
      - LITELLM_SALT_KEY=${LITELLM_SALT_KEY:-sk-salt-random-string}
    command: --config /app/config.yaml --detailed_debug
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    container_name: litellm-db
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: litellm_password
    volumes:
      - litellm_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  litellm_pgdata:

A variável LITELLM_SALT_KEY encripta os dados das chaves virtuais na base de dados. A documentação das melhores práticas de produção da LiteLLM recomenda definir esta chave para qualquer implementação em equipa.

Iniciar a Stack

# Create a .env file with your keys (don't commit this to git)
echo "LITELLM_MASTER_KEY=sk-master-your-secret" > .env
echo "OPENAI_API_KEY=sk-..." >> .env
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env
echo "LITELLM_SALT_KEY=sk-salt-$(openssl rand -hex 16)" >> .env

# Start everything
docker compose up -d

# Check logs
docker compose logs -f litellm

Verificar se Tudo Funciona

# Health check
curl http://localhost:4000/health

# Test a request
curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}]}'

Se vir uma resposta bem-sucedida, a sua stack de produção está a funcionar. O PostgreSQL armazena todos os dados de custos, chaves virtuais e métricas de utilização de forma persistente, mesmo após reinícios dos contentores.

Veredicto: Docker Compose + PostgreSQL é a configuração de produção recomendada. Oferece armazenamento persistente, monitorização de custos e chaves virtuais com cerca de 10 minutos de trabalho. A documentação de implementação Docker cobre Kubernetes e Helm caso precise de escalabilidade automática mais tarde.

Análise do config.yaml: Uma Configuração Real Multi-fornecedor

A maioria dos tutoriais mostra um config.yaml com apenas um modelo. Eis o aspeto de uma configuração real de equipa com três fornecedores, fallbacks e balanceamento de carga.

O Ficheiro de Configuração

# config.yaml -- Real multi-provider setup
model_list:
  # Primary: OpenAI GPT-4o
  - model_name: gpt-4o          # The name YOUR code uses
    litellm_params:
      model: openai/gpt-4o      # The actual provider/model
      api_key: os.environ/OPENAI_API_KEY

  # Secondary: Anthropic Claude
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

  # Local: Ollama for development / cost-free testing
  - model_name: local-llama
    litellm_params:
      model: ollama/llama3.1
      api_base: http://host.docker.internal:11434

  # Fallback: route "gpt-4o" to Claude if OpenAI is down
  - model_name: gpt-4o
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

router_settings:
  routing_strategy: least-busy    # Load balance across same-name models
  num_retries: 3
  retry_after: 5                  # Seconds between retries
  fallbacks: [{"gpt-4o": ["claude-sonnet"]}]

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL

Aliases de Modelos e Roteamento

Note que gpt-4o aparece duas vezes na configuração, uma vez apontando para a OpenAI e outra para a Anthropic. Quando o seu código solicita gpt-4o, a LiteLLM tenta primeiro a OpenAI. Se falhar, a definição fallbacks encaminha automaticamente para o Claude. O código da sua aplicação não sofre qualquer alteração.

Se estiver a utilizar backends de inferência de produção como vLLM ou SGLang, pode adicioná-los da mesma forma, bastando definir o api_base para o seu servidor de inferência.

Referência Rápida de Fornecedores

A definição routing_strategy: least-busy distribui os pedidos pelos modelos com o mesmo model_name. Se tiver duas chaves da OpenAI (talvez de organizações diferentes com limites de taxa distintos), liste ambas sob gpt-4o e a LiteLLM equilibrará a carga.

Chaves Virtuais: Chaves de API por Equipa com Orçamentos e Limites de Taxa

É aqui que a LiteLLM deixa de ser "apenas um proxy" e se torna uma ferramenta de gestão de equipas. As chaves virtuais permitem atribuir a cada membro da equipa ou serviço a sua própria chave de API com limites de gastos e de taxa, tudo roteado através do seu conjunto único de chaves de API dos fornecedores.

Criar uma Chave de Equipa com Orçamento

# Create a virtual key with a $50/month budget
curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "frontend-team",
    "max_budget": 50.0,
    "budget_duration": "1mo",
    "models": ["gpt-4o", "claude-sonnet"],
    "metadata": {"purpose": "frontend AI features"}
  }'

A resposta fornece-lhe uma nova chave como sk-team-abc123.... Entregue-a à equipa de frontend. Eles podem utilizá-la exatamente como uma chave da OpenAI, mas está limitada a 50 $/mês e só tem acesso aos modelos que especificou.

Definir Limites de Taxa

# Create a key with rate limits: 100 requests/minute, 50K tokens/minute
curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "backend-team",
    "max_budget": 200.0,
    "budget_duration": "1mo",
    "rpm_limit": 100,
    "tpm_limit": 50000,
    "models": ["gpt-4o", "claude-sonnet", "local-llama"]
  }'

A documentação de chaves virtuais cobre todos os parâmetros. Também pode definir orçamentos e limites de taxa por utilizador para um controlo ainda mais granular.

Monitorizar a Utilização das Chaves

import requests

# Check a key's current spend and limits
response = requests.get(
    "http://localhost:4000/key/info",
    headers={"Authorization": f"Bearer {MASTER_KEY}"},
    params={"key": "sk-team-abc123..."}
)
info = response.json()
print(f"Spent: ${info['spend']:.2f} / ${info['max_budget']:.2f}")
print(f"RPM used: {info['rpm_limit_used']} / {info['rpm_limit']}")

Precisa de revogar uma chave comprometida? Basta uma chamada à API:

curl -X POST http://localhost:4000/key/delete \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["sk-team-abc123..."]}'

Veredicto: As chaves virtuais são o que transforma a LiteLLM numa ferramenta de equipa, e não apenas num proxy pessoal. Sem elas, está apenas a adicionar um salto entre o seu código e o LLM. Com elas, tem controlo de acessos, aplicação de orçamentos e atribuição de utilização, o tipo de funcionalidades que impedem o seu CFO de entrar em pânico.

Monitorização de Custos e o Painel da LiteLLM

Assim que o PostgreSQL estiver ligado, a LiteLLM rastreia automaticamente o custo de cada pedido. Não precisa de configurar nada; o sistema conhece o preço por token de cada modelo suportado.

O Painel de Controlo

Aceda à interface integrada em http://localhost:4000/ui (inicie sessão com a sua chave mestra). Verá:

• Gasto total em todas as equipas e chaves
• Detalhe por modelo, quais os modelos que estão a consumir o seu orçamento
• Gasto por equipa, quem está a usar o quê
• Volume de pedidos ao longo do tempo

Para equipas seriamente empenhadas em reduzir os custos das APIs de LLM, só o painel justifica a execução do proxy. Também pode ligar a LiteLLM a plataformas de observabilidade de IA externas, como Langfuse ou Helicone, para análises mais profundas.

Comparação de Custos por Fornecedor

Eis quanto custam os principais modelos por milhão de tokens (a partir de abril de 2026):

Quando vê estes números no painel, discriminados por equipa, as conversas sobre "devemos usar um modelo mais barato para este caso de uso?" tornam-se muito concretas.

Veredicto: Só a monitorização de custos justifica o proxy para qualquer equipa que gaste >100 $/mês em APIs de LLM. Não pode otimizar o que não pode medir.

Ligar IDEs de IA: Claude Code, Cursor e Continue

Eis algo que a maioria dos guias da LiteLLM ignora completamente: pode apontar as suas ferramentas de codificação com IA para o proxy também. Um proxy, todas as suas ferramentas de IDE, faturação unificada.

Claude Code

# Set Claude Code to use your LiteLLM proxy
export ANTHROPIC_BASE_URL=http://localhost:4000/v1
export ANTHROPIC_API_KEY=sk-team-your-virtual-key

É tudo. O Claude Code envia pedidos para o seu proxy, que os encaminha para a Anthropic (ou para onde a sua configuração indicar), enquanto rastreia os custos sob a sua chave virtual.

Cursor

Nas definições do Cursor, adicione um endpoint personalizado compatível com a OpenAI:

{
  "openai.apiBaseUrl": "http://localhost:4000/v1",
  "openai.apiKey": "sk-team-your-virtual-key"
}

Continue (VS Code)

No ficheiro config.json do Continue:

{
  "models": [
    {
      "title": "GPT-4o via LiteLLM",
      "provider": "openai",
      "model": "gpt-4o",
      "apiBase": "http://localhost:4000/v1",
      "apiKey": "sk-team-your-virtual-key"
    }
  ]
}

Porquê dar-se ao trabalho? Porque agora toda a utilização das IDEs dos programadores passa pelo proxy. Obtém monitorização de custos por pessoa para assistentes de codificação com IA, limites de taxa para que ninguém queime acidentalmente 500 $ numa sessão de codificação e um local único para mudar de modelos se encontrar uma opção melhor.

Resolução de Problemas Comuns

"Ficheiro de configuração não encontrado"

Isto geralmente significa que o caminho de montagem do volume no Docker está errado. Certifique-se de que o seu config.yaml está no diretório a partir do qual está a montar:

# Check the file exists where you think it does
ls -la ./config.yaml

# The volume mount in docker-compose.yml should match
# volumes:
#   - ./config.yaml:/app/config.yaml

"Connection refused" ao PostgreSQL

A rede do Docker apanha toda a gente pelo menos uma vez. Se a LiteLLM não conseguir aceder ao Postgres, verifique se:

• O nome do serviço em DATABASE_URL corresponde ao nome do serviço do Docker Compose (postgres, e não localhost)
• A opção depends_on com condition: service_healthy está definida (para que a LiteLLM aguarde até o Postgres estar pronto)
• Ambos os serviços estão na mesma rede Docker (estão-no por defeito no Compose)

"Formato de chave de API inválido"

A confusão mais comum: a sua LITELLM_MASTER_KEY serve para operações administrativas (criar chaves virtuais, aceder ao painel). As chaves virtuais (sk-team-...) são o que as suas aplicações utilizam. Não as misture.

"Modelo não encontrado"

O campo model no seu pedido deve corresponder a um model_name no config.yaml. Se a sua configuração define gpt-4o mas o seu código solicita openai/gpt-4o, não haverá correspondência. Verifique a grafia exata.

O proxy inicia mas os pedidos ficam suspensos

Geralmente é um problema de firewall ou de ligação de portas. Verifique se a porta 4000 está exposta e não bloqueada:

# Check if the port is listening
docker port litellm-proxy
# Should show: 4000/tcp -> 0.0.0.0:4000

Segurança: Evite as Versões 1.82.7 e 1.82.8

Em março de 2026, um incidente na cadeia de abastecimento afetou as versões 1.82.7 e 1.82.8 da LiteLLM. As versões comprometidas foram retiradas e foi lançada uma versão limpa na 1.83.0. Fixe sempre a sua imagem Docker numa versão específica e consulte a atualização de segurança oficial antes de atualizar. Se estiver na versão 1.82.7 ou 1.82.8, atualize imediatamente.

Que Método de Configuração da LiteLLM Deve Escolher?

Se está a ler este guia pela primeira vez, comece com Docker Compose + PostgreSQL. Pode sempre migrar para Kubernetes mais tarde; o config.yaml mantém-se igual.

Perguntas Frequentes (FAQ)

O que é o proxy LiteLLM e como funciona?

O proxy LiteLLM é um servidor gateway de IA open-source que se interpõe entre as suas aplicações e fornecedores de LLM como a OpenAI e a Anthropic. Expõe um único endpoint compatível com a OpenAI, pelo que o seu código comunica com um URL enquanto o proxy trata do roteamento, gestão de chaves, monitorização de custos e fallbacks nos bastidores.

Como configuro o proxy LiteLLM com Docker Compose?

Crie um docker-compose.yml com a imagem do proxy LiteLLM e uma base de dados PostgreSQL, monte o seu config.yaml, defina as suas chaves de API como variáveis de ambiente e execute docker compose up -d. A secção Docker Compose de Produção acima tem um ficheiro completo, pronto para copiar e colar.

Como gerir chaves de API de equipa com a LiteLLM?

Utilize chaves virtuais. Aceda ao endpoint /key/generate com a sua chave mestra para criar chaves por equipa ou por utilizador. Cada chave virtual pode ter o seu próprio orçamento mensal, limites de taxa (RPM e TPM) e restrições de acesso a modelos. A secção Chaves Virtuais cobre todo o fluxo de trabalho.

Como adiciono monitorização de custos e limites de taxa à minha API de LLM?

Ligue o PostgreSQL ao proxy (via DATABASE_URL) e a monitorização de custos ocorre automaticamente. Para limites de taxa, defina rpm_limit e tpm_limit ao gerar chaves virtuais. O painel integrado em /ui mostra os gastos por equipa e por modelo.

O proxy LiteLLM é seguro para usar em produção?

Sim, com uma ressalva: evite as versões 1.82.7 e 1.82.8, que foram afetadas por um incidente na cadeia de abastecimento em março de 2026. Utilize a versão 1.83.0 ou superior. Fixe a versão da sua imagem Docker, defina a LITELLM_SALT_KEY para encriptação e siga as melhores práticas de produção oficiais.

Qual é a diferença entre o SDK da LiteLLM e o proxy LiteLLM?

O SDK é uma biblioteca Python para chamar várias APIs de LLM a partir do seu código. O proxy é um servidor autónomo ao qual toda a sua equipa se liga. Utilize o SDK quando for um programador solo a escrever um script. Utilize o proxy quando precisar de controlo de acesso partilhado, monitorização de custos e limitação de taxa numa equipa.

Posso usar o proxy LiteLLM com Ollama e modelos locais?

Absolutamente. Adicione uma entrada ao seu config.yaml com model: ollama/llama3.1 e api_base: http://host.docker.internal:11434 (ou o seu host Ollama). A sua equipa pode então aceder a modelos locais através do mesmo endpoint do proxy, o que é excelente para desenvolvimento e testes sem custos.

Quanto custa o proxy LiteLLM?

O proxy LiteLLM é gratuito e open-source (licença MIT). Autoaloja-o na sua própria infraestrutura. Os únicos custos são o seu servidor (um pequeno VPS é suficiente para a maioria das equipas) e os custos das APIs de LLM que já está a pagar. A BerriAI também oferece uma versão cloud gerida se não quiser fazer autoalojamento.

Que fornecedores a LiteLLM suporta?

Mais de 100, incluindo OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Google Vertex AI, Ollama, Hugging Face, Cohere, Replicate e muitos outros. A lista completa está no repositório GitHub da LiteLLM.

Como atualizo o proxy LiteLLM com segurança?

Fixe sempre uma versão específica na tag da sua imagem Docker (ex.: ghcr.io/berriai/litellm:v1.83.2-stable). Antes de atualizar, verifique o registo de alterações (changelog) para identificar alterações disruptivas. Nunca utilize latest em produção. E verifique sempre se a nova versão não consta da lista de avisos de segurança; o incidente de março de 2026 provou que mesmo pacotes confiáveis podem ser comprometidos.

Veredicto Final e Próximos Passos

Se a sua equipa gasta dinheiro em APIs de LLM e ainda não tem um proxy, comece hoje com Docker Compose + Postgres. A configuração demora 15 minutos e terá visibilidade de custos e controlo de acessos no final.

Assim que estiver a funcionar, explore adicionar guard-rails ao seu pipeline de LLM para filtragem de conteúdo e verificações de segurança. O proxy é a fundação; tudo o resto constrói-se sobre ele.

Fontes

• Início Rápido do Proxy LiteLLM, Documentação Oficial
• Guia de Implementação Docker da LiteLLM
• Documentação de Chaves Virtuais da LiteLLM
• Melhores Práticas de Produção da LiteLLM
• Atualização de Segurança da LiteLLM, Março de 2026
• BerriAI/litellm, Repositório GitHub