Quem monta automação com IA cedo ou tarde esbarra no mesmo problema: cada fluxo, script ou app apontando direto para um provedor, cada um com sua chave, seu formato e sua lógica de erro. A saída que eu recomendo é colocar um LiteLLM gateway na frente de tudo: um endpoint único, compatível com o formato da OpenAI, que conversa com seus modelos locais no Ollama e com provedores de nuvem como OpenAI, Anthropic e Gemini. E o melhor: com fallback automático quando um deles cai.
Vou mostrar como subir o gateway com Docker ou Python, montar o config.yaml com modelos locais e de nuvem, configurar o fallback no router_settings e testar tudo com curl e com o SDK da OpenAI apontando para localhost:4000.
O problema: n8n, scripts e apps cada vez mais presos a um único provedor
O cenário é comum: o fluxo do n8n chama a API de um provedor, o script de análise chama outro, e o app interno chama um terceiro. Quando o provedor fica instável ou devolve um erro de limite de requisições, tudo para até você reconfigurar na mão. Trocar de modelo vira projeto, não ajuste.
Com modelos locais, o problema aparece do outro lado: o Ollama expõe um endpoint próprio, e aí você duplica lógica para tratar chamada local e chamada de nuvem. O gateway resolve os dois lados, porque padroniza a entrada em um formato só e decide, por trás, para onde cada chamada vai.
O que é o LiteLLM gateway: um proxy OpenAI-compatível que unifica mais de 100 provedores
O LiteLLM é um gateway de IA open source que oferece uma interface unificada para chamar mais de 100 provedores de LLM — OpenAI, Anthropic, Gemini, Bedrock, Azure, vLLM, Ollama e outros — usando o formato da OpenAI. O Proxy roda por padrão na porta 4000, e qualquer cliente que funciona com a OpenAI funciona com ele sem mudanças de código.
A versão estável mais recente é a LiteLLM v1.103.2, lançada em 1º de outubro de 2026, com a v1.102.1 (de 23 de setembro de 2026) logo atrás — você acompanha as releases na página oficial do projeto. As imagens Docker oficiais publicadas no GHCR são assinadas com cosign, o que permite verificar a origem antes de subir o contêiner.
Além do fallback, o Roteador do LiteLLM cuida de balanceamento de carga, cooldowns, timeouts e retries com backoff fixo e exponencial entre múltiplos deployments e provedores. Ou seja: não é só um tradutor de API, é uma camada de resiliência de verdade.
O que você vai precisar
- Docker — ou Python, instalando com
pip install litellm[proxy]; a documentação recomenda ambiente virtual e, no caso do Windows, WSL2. - Chaves de API dos provedores de nuvem que você for usar (OpenAI, Anthropic, Gemini e por aí vai).
- Ollama rodando local, com pelo menos um modelo baixado — o LiteLLM suporta todos os modelos do Ollama como backend do gateway.
- Qualquer cliente OpenAI para os testes:
curlou o SDK na sua linguagem preferida.
Passo a passo: configurando o config.yaml com model_list
Crie uma pasta para o gateway e um arquivo config.yaml. A estrutura básica tem uma model_list, onde cada entrada vira um model group com um nome que você escolhe. O modelo local usa o prefixo ollama/; os de nuvem usam openai/, anthropic/ e assim por diante.
model_list:
- model_name: principal
litellm_params:
model: ollama/<seu-modelo-local>
- model_name: reserva
litellm_params:
model: anthropic/<modelo-na-nuvem>
api_key: os.environ/ANTHROPIC_API_KEYRepare que o model_name (o nome que seus fluxos vão chamar) é independente do modelo real em litellm_params.model. Isso permite trocar o modelo de trás sem tocar em nenhuma automação. Os campos específicos de cada provedor variam, então confira a página do provedor na documentação oficial antes de completar o arquivo.
Para subir com Docker, o quickstart oficial usa a imagem docker.litellm.ai/berriai/litellm:latest, mapeando a porta 4000 e montando o config em /app/config.yaml:
docker run -d \
-p 4000:4000 \
-v $(pwd)/config.yaml:/app/config.yaml \
docker.litellm.ai/berriai/litellm:latestSe preferir Python, instale com pip install litellm[proxy] em um ambiente virtual e rode com litellm --config your_config.yaml. Para um teste rápido, sem arquivo de configuração, o CLI também aceita litellm --model ollama/<modelo> e sobe um proxy na hora.
Configurando o fallback no router_settings
O fallback é o mecanismo de failover automático do LiteLLM: se uma chamada falha após num_retries tentativas, o Roteador cai para outro model group configurado em router_settings. Na prática, você define quem é o principal e quem entra de reserva.
router_settings:
num_retries: 2
fallbacks:
- principal: ["reserva"]O LiteLLM também tem tipos específicos de fallback, cada um disparando por um motivo diferente:
| Configuração | Quando dispara |
|---|---|
fallbacks | Erros gerais, como RateLimitError |
context_window_fallbacks | Erro de janela de contexto |
content_policy_fallbacks | Violação de política de conteúdo |
Existe ainda um conjunto de endpoints dedicados de Fallback Management, que permite gerenciar fallbacks de modelos separadamente da configuração geral. É útil quando você quer ajustar a cadeia de reserva sem editar o YAML e reiniciar o gateway.
Testando: chamadas com curl e com o SDK OpenAI em localhost:4000
Com o gateway no ar, um teste direto com curl já mostra a cadeia funcionando. Se o modelo local estiver disponível, ele responde; se você derrubar o Ollama de propósito, verá o fallback acontecendo nos logs do gateway.
curl http://localhost:4000/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <sua-chave>" \
-d '{
"model": "principal",
"messages": [{"role": "user", "content": "teste de gateway"}]
}'No SDK da OpenAI, a mudança se resume à base_url:
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:4000/v1",
api_key="<sua-chave>"
)
resposta = client.chat.completions.create(
model="principal",
messages=[{"role": "user", "content": "teste de gateway"}]
)Esse é o ponto que mais economiza trabalho: qualquer código, biblioteca ou plataforma que já fala com a OpenAI passa a falar com o seu gateway só trocando a URL.
Integração com o n8n e outros fluxos, e cuidados com a master key
No n8n, o caminho é o mesmo de qualquer cliente OpenAI: aponte a base URL para o seu gateway na porta 4000 e use o model_name do config como nome do modelo. Trocar provedor, modelo ou ordem de fallback passa a ser mudança de configuração no YAML, não de código nos fluxos.
Sobre segurança: a master key do proxy é a senha do seu gateway inteiro. Trate como chave de produção, guarde em variável de ambiente e não exponha a porta 4000 para a internet sem uma camada de controle na frente. Duas práticas que recomendo por causa do histórico: fixar a versão da imagem e verificar a assinatura cosign antes de subir. Em março de 2026, as versões v1.82.7 e v1.82.8 do pacote no PyPI foram comprometidas, e esse tipo de incidente reforça o quanto verificar a origem importa.
Na prática: como uso isso aqui
Aqui em casa rodo dois gateways LiteLLM: um local e outro para os modelos na nuvem. Assim tenho meus modelos centralizados em um endpoint só, com fallback — hoje os locais são o qwen3.5 de 9B e o gemma4 de 12B, e na nuvem uso o Gemini.
Minha ordem de fallback é local primeiro: se o modelo local falha, a chamada vai para a nuvem. Quando é algo sensível, com informação privada, mantenho a execução nos modelos locais; se realmente precisar ir para a nuvem, a chamada passa antes por um guardrail que disfarça as informações sensíveis.
Depois do incidente do PyPI, mantive a imagem latest — rodo assim há mais de 6 meses sem problema até agora. Mas não é configuração para esquecer numa gaveta: faço manutenção constante, verificando os logs e as falhas sempre que aparecem. E uma observação honesta: o LiteLLM é muito bom para ter um único ponto para seus modelos, com fallback e guardrail configurados, porém exige um certo conhecimento para configurar e manter tudo funcional.
Problemas comuns e como resolver
- O contêiner não sobe: confira o mapeamento da porta 4000 e se o config está montado em
/app/config.yaml. Os logs do Docker mostram erro de sintaxe no YAML na primeira linha. - Erro de autenticação no provedor de nuvem: normalmente a variável de ambiente com a chave não está disponível para o contêiner.
- O fallback não dispara: ele só entra em cena depois de
num_retriestentativas, e o nome do model group emfallbacksprecisa ser exatamente igual aomodel_nameda lista. - Modelo do Ollama não responde: verifique se o Ollama está rodando e se o nome depois de
ollama/é o mesmo do modelo baixado.
Vale a pena montar esse gateway?
A conta é simples: um endpoint OpenAI-compatível na porta 4000, modelos locais e de nuvem atrás dele e failover automático quando algo cai. Para quem roda automações no n8n, em scripts ou em apps, o litellm gateway elimina a dependência de um provedor único e transforma troca de modelo em mudança de configuração, não de código.
Comece com dois modelos no config, valide o fallback derrubando um deles de propósito e vá ampliando a partir daí. A documentação oficial cobre cada provedor em detalhe, inclusive os campos específicos que não entram neste passo a passo.
Perguntas frequentes
O LiteLLM gateway funciona com modelos locais do Ollama?
Sim. O LiteLLM suporta todos os modelos do Ollama como backend do gateway, usando o prefixo ollama/ na configuração do modelo.
Em qual porta o gateway roda por padrão?
Na porta 4000. Qualquer cliente que funciona com a OpenAI pode apontar para esse endpoint sem mudanças de código.
Preciso fixar a versão do LiteLLM?
A recomendação é fixar. Em março de 2026, as versões v1.82.7 e v1.82.8 do pacote no PyPI foram comprometidas; fixar a versão (a estável atual é a v1.103.2) e verificar as assinaturas cosign das imagens oficiais reduz esse risco.
