AI Gateway com LiteLLM Proxy

Exemplo didático de uma AI Gateway usando o LiteLLM Proxy.

A ideia central: a aplicação não fala direto com os providers (OpenAI, Anthropic). Ela fala apenas com o Proxy, usando um nome interno de capacidade — support-ticket-classifier. Quem decide qual modelo físico responde, quais chaves usar e se há fallback é o Proxy, não a aplicação.

Aplicação Python  ->  LiteLLM Proxy  ->  OpenAI ou Anthropic (fallback)

Vantagens dessa arquitetura:

• A aplicação não importa SDKs nativos de cada provider nem conhece as chaves reais.
• Trocar de modelo/provider é configuração no Proxy (config.yaml / .env), não código.
• O Proxy centraliza autenticação, fallback técnico, limites e observabilidade.

O caso de uso do exemplo é um classificador de tickets de suporte: dada uma mensagem do cliente, o modelo devolve um JSON com a categoria (billing, technical, account, other).

Estrutura

Arquivo	Papel
app/main.py	Aplicação Python. Só conhece o nome interno da gateway.
litellm/config.yaml	Configuração do Proxy: capacidades, providers e fallback.
docker-compose.yml	Sobe o LiteLLM Proxy na porta 4000.
.env.example	Modelo das variáveis (chaves dos providers, master key, modelos).

Como rodar

1. Copie o .env.example para .env e preencha as chaves reais:

   cp .env.example .env
   # edite OPENAI_API_KEY e ANTHROPIC_API_KEY

2. Suba o Proxy:

   docker compose up -d

3. Instale as dependências da aplicação e rode:

   pip install -r app/requirements.txt
   python app/main.py "Fui cobrado duas vezes na minha assinatura."

A aplicação se autentica no Proxy com a LITELLM_MASTER_KEY (nunca com a chave do provider) e chama sempre a capacidade support-ticket-classifier.

As 4 branches (evolução do exemplo)

O repositório é organizado em etapas incrementais. Cada branch adiciona uma camada em cima da anterior, do exemplo mais simples ao mais completo. O main corresponde ao estado da branch 04 (a versão final).

01-app-minima-via-proxy

Exemplo mínimo: uma aplicação Python que fala com um modelo através do LiteLLM Proxy. Mostra o básico da arquitetura — a app usa o base_url do Proxy e um nome interno de capacidade, sem tocar nas chaves do provider.

02-duas-capacidades-openai-anthropic

A gateway passa a expor duas capacidades internas, uma por trás da OpenAI e outra por trás da Anthropic. Demonstra que o nome interno desacopla a aplicação do provider físico: dá para ter vários modelos/providers registrados no Proxy.

03-fallback-tecnico-no-proxy

Adiciona fallback técnico no Proxy: se a capacidade principal (OpenAI) falhar após os retries, o Proxy aciona automaticamente um backup (Anthropic). A aplicação não sabe que isso aconteceu — para ela, foi só uma chamada bem sucedida. Responde à pergunta "foi possível tentar outro caminho?".

04-validacao-limite-do-fallback

Mostra o limite do fallback técnico. Ter fallback não basta se o modelo de backup é fraco: ele responde com HTTP 200, mas entrega algo que não cumpre o contrato da aplicação (por exemplo, JSON embrulhado em markdown em vez de JSON puro). Quem percebe e barra isso é a aplicação, validando o contrato da resposta — não o Proxy. Fallback técnico responde "houve uma tentativa?"; a validação responde "o resultado serve para o fluxo de negócio?".

Para exercitar o cenário de fallback, aponte PRIMARY_MODEL para um modelo inexistente no .env: o primário falha, o Proxy usa o backup fraco e a aplicação barra a resposta que não cumpre o contrato.