LiteLLM: um proxy unificado local e cloud

#Por que usar um proxy LiteLLM para modelos locais e na nuvem

Uma stack híbrida típica tem dois problemas. Primeiro, o código da aplicação fica repleto de if provider == 'openai' / elif provider == 'ollama'. Depois, a decisão "local versus nuvem" fica definida no momento em que o código é escrito: se o Ollama cair, a aplicação cai; se você quiser mudar para o Claude para uma tarefa específica, precisará fazer uma nova implantação.

LiteLLM resolve os dois. No lado da aplicação, você fala com um endpoint único compatível com a OpenAI (chat/completions, embeddings, streaming). No lado da infraestrutura, um arquivo config.yaml descreve seus modelos: alias lógico, backend, chave API, prioridade de fallback. Você muda a rota sem tocar no código.

#Como funciona

O proxy expõe a porta 4000 por padrão. Sua aplicação envia um POST /chat/completions com model: "chat-fr". O LiteLLM analisa seu config.yaml, vê que chat-fr aponta para ollama/qwen3.5:9b no localhost:11434, faz a requisição, normaliza a resposta no formato OpenAI e retorna o resultado para a aplicação.

Do lado do aplicativo

Uma única URL (http://localhost:4000), uma única chave virtual, o SDK padrão da OpenAI é suficiente.

Do lado do proxy

Um model_list mapeia aliases (chat-fr, code-rapide, analyse-doc) para backends reais.

Routing

Vários backends para o mesmo alias = balanceamento de carga, fallback, nova tentativa automática.

Observabilidade

Logs, latências, custo por requisição e por chave virtual, exportáveis para o Langfuse, Prometheus ou um Postgres.

#Pré-requisitos

Python 3.10+

LiteLLM é um pacote pip. Uma venv limpa ou uma instalação limpa com pipx basta.

Ollama em execução

Em http://localhost:11434 com pelo menos um modelo baixado. Consulte o guia de instalação Ollama se necessário.

Chaves API de nuvem (opcional)

OPENAI_API_KEY, ANTHROPIC_API_KEY se você quiser redirecionar para a nuvem como fallback.

Um arquivo .env

Para nunca commitar chaves em texto claro no config.yaml.

#1. Instalação

pip install 'litellm[proxy]'

O extra proxy inclui FastAPI, uvicorn e as dependências opcionais (Postgres, Redis se você quiser limitação de taxa compartilhada). Para um teste rápido, isso é suficiente. Para produção, prefira a imagem Docker oficial.

docker run -d --name litellm \
  -p 4000:4000 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  --env-file .env \
  ghcr.io/berriai/litellm:main-stable \
  --config /app/config.yaml

Verifique se está funcionando:

curl http://localhost:4000/health/liveliness

#2. Um config.yaml mínimo do LiteLLM

Crie o config.yaml ao lado do seu projeto. A estrutura é composta por três seções: model_list (os aliases), litellm_settings (comportamento global) e general_settings (autenticação, banco de dados).

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/qwen3.5:9b
      api_base: http://localhost:11434

  - model_name: code-rapide
    litellm_params:
      model: ollama/qwen3-coder:30b
      api_base: http://localhost:11434

litellm_settings:
  drop_params: true
  num_retries: 2
  request_timeout: 60

Inicie o proxy com esta configuração:

litellm --config config.yaml --port 4000

Na aplicação, o SDK da OpenAI para Python se comunica diretamente com o proxy. Nenhuma dependência do LiteLLM no código da aplicação:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000",
    api_key="sk-fake-local",  # le proxy n'exige pas de vraie clé par défaut
)

resp = client.chat.completions.create(
    model="chat-fr",
    messages=[{"role": "user", "content": "Résume la photosynthèse en 3 lignes."}],
)
print(resp.choices[0].message.content)

#3. Adicionar OpenAI e Anthropic

Nunca inserimos as chaves diretamente no código. Coloque-as em um .env ao lado do arquivo de configuração:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Em seguida, referencie as variáveis com a sintaxe os.environ no YAML — o LiteLLM as substitui na inicialização:

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/qwen3.5:9b
      api_base: http://localhost:11434

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

  - model_name: analyse-doc
    litellm_params:
      model: anthropic/claude-haiku-4-5-20251001
      api_key: os.environ/ANTHROPIC_API_KEY

Neste estágio, você tem três aliases lógicos. O código do aplicativo escolhe chat-fr para conversas privadas, chat-gros para requisições longas, analyse-doc para leitura de PDF. Nenhuma chave aparece no código.

#4. Roteamento por modelo e fallback automático

É aqui que o verdadeiro valor do proxy aparece. Dois mecanismos que você precisa conhecer: várias entradas com o mesmo model_name (balanceamento de carga) e a chave fallbacks (alternância em caso de erro).

1. 01
   Várias entradas, um único alias

   Você pode declarar model_name: chat-fr duas vezes — uma entrada apontando para o Ollama local, a outra para um Mistral na nuvem. O LiteLLM distribui as requisições conforme a estratégia (simple-shuffle por padrão, ou usage-based-routing se você quiser otimizar o custo).
2. 02
   Fallback explícito

   Em litellm_settings, declare qual alias assume o lugar se o primeiro retornar um erro ou timeout. O fallback ativa automaticamente um retry no backend de reserva.
3. 03
   Verificação de funcionamento ativa

   O LiteLLM envia pings periodicamente a cada modelo. Uma instância do Ollama que deixa de responder é marcada como unhealthy e retirada do pool até voltar a responder — suas requisições passam automaticamente para a nuvem.

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/qwen3.5:9b
      api_base: http://localhost:11434

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

litellm_settings:
  num_retries: 2
  request_timeout: 30
  fallbacks:
    - chat-fr: ["chat-fr-cloud"]
  context_window_fallbacks:
    - chat-fr: ["chat-fr-cloud"]

Com essa configuração, seu app sempre faz chamadas com model: "chat-fr". Se o Ollama estiver indisponível, atingir o tempo limite ou se o prompt ultrapassar a janela de contexto que você alocou localmente (num_ctx reduzido para economizar VRAM), o proxy alterna de forma transparente para GPT-4o-mini. O app não percebe nada — apenas recebe uma resposta, talvez um pouco mais lenta.

#5. Acompanhamento de custos e limitação de requisições

Uma stack híbrida tem um custo oculto: você acredita estar usando um modelo local, mas 30% das requisições, na verdade, foram direcionadas para o GPT-4o. O LiteLLM calcula o custo de cada requisição com base em uma tabela de preços interna (atualizada conforme as tabelas públicas de preços).

Para armazenar os logs de forma persistente e disponibilizar um dashboard, conecte um banco Postgres:

general_settings:
  master_key: sk-litellm-prod-changeme
  database_url: "postgresql://litellm:pass@localhost:5432/litellm"
  store_model_in_db: true

litellm_settings:
  success_callback: ["langfuse"]   # ou prometheus, datadog, etc.
  cache: true

Depois de conectar o Postgres, a interface de administração (http://localhost:4000/ui) mostra o custo por chave virtual, por modelo e por usuário. Você também pode criar chaves virtuais com um teto de orçamento — útil para conceder acesso a uma equipe sem risco de gastos fora de controle.

Custos aproximados para 1 milhão de tokens de saída (preços públicos de junho de 2026, que você deve recalcular junto ao seu fornecedor):

Ollama local (Qwen 3.5 9B Q4)

Custo marginal de 0 $ — sua eletricidade e a amortização da GPU.

OpenAI gpt-4o-mini

Aproximadamente 0,60 $ / 1M de tokens de saída, ideal para fallback barato.

Anthropic Claude Haiku 4.5

Aproximadamente 5 $ / 1M tokens de saída, mais caro, mas excelente relação qualidade/preço na análise de documentos.

OpenAI gpt-4o

Aproximadamente 10 $ por 1 milhão de tokens de saída; reservar para tarefas em que o 4o-mini não é bom o suficiente.

No que diz respeito ao limite de taxa, definimos limites RPM (requisições por minuto) e TPM (tokens por minuto) por modelo. O LiteLLM coloca em fila ou retorna um erro 429 conforme sua configuração:

model_list:
  - model_name: chat-gros
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY
      rpm: 60
      tpm: 100000

#Solução de problemas

"Model not found" mesmo que o alias exista

Verifique a indentação do YAML. Um espaço a mais sob litellm_params faz o proxy ignorar silenciosamente a entrada. Execute litellm --config config.yaml --debug para ver o model_list efetivamente carregado.

O fallback não é ativado

num_retries deve ser ≥ 1 e o tempo limite deve ser atingido. Por padrão, request_timeout é muito generoso no Ollama — reduza-o para 30 segundos para que os fallbacks sejam acionados rapidamente.

Erro 401 no Ollama

ollama/* não aceita chave de API. Se você colocou api_key em uma entrada Ollama, remova-a. O LiteLLM repassa a chave sem alterações, o que causa uma falha.

Custos incorretos ou zerados

A tabela de preços depende da versão do LiteLLM. Atualize (pip install -U 'litellm[proxy]'). Para um modelo personalizado não listado, declare input_cost_per_token e output_cost_per_token manualmente em litellm_params.

Latência anormal no Ollama

O proxy realiza uma verificação de integridade a cada minuto. Se o Ollama demorar para carregar um modelo (cold start), a verificação excede o tempo limite e marca o modelo como unhealthy. Aumente health_check_interval ou pré-carregue os modelos com ollama run X --keepalive 60m.

#Para se aprofundar

Com essa configuração, você tem um ponto de entrada único para toda a sua IA, local ou na nuvem, com alternância transparente entre as duas. Os próximos passos naturais: