Implantar um gateway de API LLM unificado LiteLLM em VPS (2026): Docker, chaves virtuais, controle de orçamento e guia de roteamento multimodelo

Se você só usa uma chave da OpenAI sozinho, o LiteLLM pode ser um pouco redundante.

Mas basta aparecer qualquer uma das situações abaixo para ele se tornar muito valioso:

Meu próprio critério é simples:

• Uso pessoal com uma única chave: não é necessário
• Vários projetos, vários modelos, vários membros: muito necessário
• Quer construir uma plataforma interna de API de IA: vale a pena implantar

Ele não é uma interface de chat nem uma plataforma de aplicações de IA. Ele se parece mais com um gateway de API de LLM.

O LiteLLM em si não é pesado; o que realmente consome recursos é o PostgreSQL, o Prometheus, a concorrência de requisições e o volume de logs.

Se você só faz proxy e não roda modelos locais, 2C4G é basicamente suficiente.

Não misture com o Ollama ao calcular recursos. O LiteLLM é um gateway de encaminhamento e não é responsável pela inferência local. O que você conecta são APIs remotas como OpenAI, DeepSeek e Claude, então a pressão de CPU dele mesmo não é alta.

Não se apresse em copiar o Compose.

Há três coisas no LiteLLM que você precisa definir desde o início:

1. LITELLM_MASTER_KEY
2. LITELLM_SALT_KEY
3. As regras de nomenclatura de modelos no config.yaml

MASTER_KEY é a chave de administrador e precisa começar com sk-.

SALT_KEY é mais importante; ele é usado para criptografar as chaves de API dos modelos no banco de dados. A documentação oficial também alerta: depois de adicionar modelos, não altere esse valor de qualquer jeito. Se você alterar, as credenciais criptografadas antigas podem não ser mais descriptografáveis.

Então não escreva:

LITELLM_SALT_KEY=sk-1234

Em vez disso, gere um valor aleatório mais longo:

openssl rand -hex 32

E depois escreva em .env.

Este artigo usa Ubuntu / Debian como exemplo.

apt update && apt upgrade -y
apt install -y ca-certificates curl gnupg ufw nano

Instalar o Docker:

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" > /etc/apt/sources.list.d/docker.list
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Confirmar:

docker --version
docker compose version

mkdir -p /opt/litellm
cd /opt/litellm

Gerar duas chaves:

echo "sk-$(openssl rand -hex 32)"
echo "sk-$(openssl rand -hex 32)"

Uma para LITELLM_MASTER_KEY, outra para LITELLM_SALT_KEY.

Criar .env:

cat > .env << 'EOF'
LITELLM_MASTER_KEY="sk-replace-with-master-key"
LITELLM_SALT_KEY="sk-replace-with-long-salt-key"
OPENAI_API_KEY="sk-replace-with-openai-key"
DEEPSEEK_API_KEY="replace-with-deepseek-key"
POSTGRES_PASSWORD="replace-with-postgres-password"
EOF

Se por enquanto você não usa OpenAI ou DeepSeek, pode deixá-las vazias por ora, mas MASTER_KEY e SALT_KEY precisam ser preenchidas com cuidado.

config.yaml é o núcleo do LiteLLM.

Ele determina:

• Quais são os nomes dos modelos visíveis externamente
• Para qual provedor ele realmente encaminha
• De onde a chave de API é lida
• Como o banco de dados e as configurações do backend são definidos

Criar o arquivo:

nano config.yaml

Escrever uma versão mínima funcional:

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

  - model_name: deepseek-chat
    litellm_params:
      model: deepseek/deepseek-chat
      api_key: os.environ/DEEPSEEK_API_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: "postgresql://litellm:${POSTGRES_PASSWORD}@db:5432/litellm"
  store_model_in_db: true

litellm_settings:
  request_timeout: 600
  set_verbose: false
  json_logs: true

O que mais confunde aqui é:

model_name: gpt-4o-mini

Este é o nome que você expõe externamente.

model: openai/gpt-4o-mini

Este é o provedor e modelo que o LiteLLM reconhece internamente.

Ou seja, você pode expor um nome unificado externamente:

company-fast-model

Mas por trás ele se conecta de fato à DeepSeek, OpenAI ou outro provedor.

Criar docker-compose.yml:

services:
  db:
    image: postgres:16
    container_name: litellm-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./postgres-data:/var/lib/postgresql/data
    ports:
      - "127.0.0.1:5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm -d litellm"]
      interval: 10s
      timeout: 5s
      retries: 5

  litellm:
    image: ghcr.io/berriai/litellm-database:main-stable
    container_name: litellm
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    env_file:
      - .env
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    command: ["--config", "/app/config.yaml", "--port", "4000"]
    ports:
      - "127.0.0.1:4000:4000"

Observe que eu vinculei tanto a 4000 quanto a 5432 a 127.0.0.1.

Muitos exemplos, por conveniência, expõem os serviços diretamente à internet. Não faça isso em produção. Coloque o Caddy ou o Nginx na frente do LiteLLM, e muito menos exponha o banco de dados diretamente.

Iniciar:

docker compose up -d

Ver o status:

docker compose ps
docker logs litellm --tail=100

Teste local:

curl http://127.0.0.1:4000/health

Se a verificação de integridade estiver normal, você pode continuar configurando o HTTPS.

Suponha que o domínio seja:

llm.example.com

Adicione um registro A no DNS apontando para o IP da sua VPS.

Instalar o Caddy:

apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' > /etc/apt/sources.list.d/caddy-stable.list
apt update
apt install -y caddy

Editar a configuração:

nano /etc/caddy/Caddyfile

Escrever:

llm.example.com {
    reverse_proxy 127.0.0.1:4000
}

Verificar e recarregar:

caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy

Acessar no navegador:

https://llm.example.com/ui

Faça login no painel administrativo com sua LITELLM_MASTER_KEY.

Abrir apenas SSH, 80 e 443:

ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable
ufw status

Não abra 4000 e 5432:

ufw deny 4000/tcp
ufw deny 5432/tcp

Se você precisa que sistemas internos o chamem, recomenda-se usar Tailscale, WireGuard ou Cloudflare Tunnel, e não deixar o painel administrativo exposto à internet.

Solicitar o LiteLLM no formato compatível com OpenAI:

curl https://llm.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "用一句话解释什么是 VPS"}
    ]
  }'

Se você quiser testar a DeepSeek:

curl https://llm.example.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-master-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {"role": "user", "content": "给我一个 Docker Compose 备份建议"}
    ]
  }'

Desde que a aplicação já suporte a API da OpenAI, na maioria dos casos basta alterar base_url para o endereço do seu LiteLLM e funciona.

Por exemplo:

OPENAI_BASE_URL=https://llm.example.com/v1
OPENAI_API_KEY=sk-your-virtual-key-or-master-key

O que realmente torna o LiteLLM valioso não é o encaminhamento de proxy, mas as chaves virtuais.

Você pode emitir chaves diferentes para projetos diferentes:

• project-docs-bot
• project-customer-support
• developer-test
• marketing-agent

Definir cada chave individualmente:

• Modelos disponíveis
• Requisições por minuto
• Orçamento mensal
• Data de expiração
• Registros de uso

Isso é muito mais seguro do que distribuir a chave real da OpenAI para todo mundo.

No uso real, eu as dividiria assim:

Quando surge um problema, também é fácil investigar: quem exatamente gastou o dinheiro, qual projeto tem volume de requisições anormal; basta olhar pela dimensão da chave.

Se for apenas para uso pessoal, você pode deixar o Prometheus de fora por enquanto.

Se for compartilhado por uma equipe, recomenda-se adicioná-lo, porque mais cedo ou mais tarde você vai querer saber:

• Qual é o volume de requisições
• Qual modelo é mais usado
• Se a latência está alta
• Se ocorrem erros com frequência

Os exemplos oficiais do LiteLLM usam prometheus.yml, e aqui há uma armadilha: esse arquivo precisa ser um arquivo real.

Se você montar diretamente no Compose:

- ./prometheus.yml:/etc/prometheus/prometheus.yml

Mas o arquivo não existe localmente, o Docker pode criá-lo como diretório e o Prometheus não sobe.

Crie primeiro:

cat > prometheus.yml << 'EOF'
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: "litellm"
    static_configs:
      - targets: ["litellm:4000"]
EOF

Depois estenda o Compose. Não exponha o painel do Prometheus diretamente à internet; no mínimo adicione Basic Auth ou permita apenas acesso pela rede interna.

Faça backup de pelo menos três coisas:

/opt/litellm/.env
/opt/litellm/config.yaml
/opt/litellm/postgres-data

.env contém chaves, não coloque no GitHub de qualquer jeito.

config.yaml pode ir para um repositório Git privado, mas não codifique chaves de API reais nele; tente usar:

api_key: os.environ/OPENAI_API_KEY

O backup do PostgreSQL pode ser feito assim:

cd /opt/litellm
docker exec litellm-db pg_dump -U litellm litellm | gzip > litellm-db-$(date +%F).sql.gz

Depois sincronize o backup com o armazenamento de objetos:

rclone copy litellm-db-$(date +%F).sql.gz r2:backup-bucket/litellm/

Se você fizer backup apenas do Compose e não do banco de dados, as chaves virtuais, os registros de orçamento e as estatísticas de uso serão todos perdidos.

Faça backup antes de atualizar:

cd /opt/litellm
docker exec litellm-db pg_dump -U litellm litellm | gzip > litellm-before-upgrade-$(date +%F).sql.gz
cp config.yaml config.yaml.bak.$(date +%F)
cp .env .env.bak.$(date +%F)

Depois baixe a nova imagem:

docker compose pull
docker compose up -d

Verifique os logs:

docker logs litellm --tail=200

O LiteLLM envolve migrações de banco de dados. Em produção, não atualize em horário de pico; é mais estável validar primeiro em uma máquina de teste.

Essas ferramentas costumam ser comparadas juntas.

Se você é administrador de um site e quer emitir chaves para usuários, gerenciar canais e ver saldos, o New-API se parece mais com um painel pronto.

Se você é uma equipe de desenvolvimento e quer que os projetos internos passem por um ponto de entrada unificado compatível com OpenAI, o LiteLLM é mais prático.

Eles não são completamente substitutos entre si. Você também pode fazer o LiteLLM se conectar a um New-API upstream, ou fazer todas as aplicações internas passarem pelo LiteLLM, e então deixar o LiteLLM fazer o fallback e o controle de orçamento.

Se eu fosse implantar o LiteLLM para uma equipe pequena, eu faria assim:

• VPS: começar com 2 núcleos e 4GB
• Implantação: Docker Compose + PostgreSQL
• Entrada: Caddy HTTPS
• Porta: 4000 escutando apenas em 127.0.0.1
• Banco de dados: não exposto à internet
• Chaves: uma chave virtual por projeto
• Orçamento: orçamento pequeno para chaves de desenvolvimento, limites separados para chaves de produção
• Configuração: config.yaml em repositório privado, chaves de API reais em .env
• Backup: backup diário do PostgreSQL, do .env e do config.yaml

O que mais combina com o LiteLLM não é "quero montar um site de chat", mas sim "tenho várias aplicações que precisam chamar vários modelos, mas não quero que cada aplicação gerencie seu próprio conjunto de chaves de API e adaptações de modelos".

À medida que os provedores de modelos aumentam, um ponto de entrada unificado economiza cada vez mais trabalho. Gaste meia hora agora para montar o gateway e, mais tarde, ao trocar de modelo, adicionar orçamentos ou conferir faturas, você evitará muita dor de cabeça.