LiteLLM como Gateway de LLMs: Presupuestos, Fallbacks y un Setup Seguro

1. El Problema: Keys de Proveedores por Todos Lados, Visibilidad por Ninguno

Llamar a los proveedores directo parece simple hasta la tercera integración. Cada servicio guarda su propia copia de las keys, cada SDK tiene su formato de errores y su lógica de reintentos, y finanzas recibe una factura por proveedor sin desglose por feature ni por equipo. Cuando un proveedor tiene una mala hora, cada servicio lo maneja distinto, casi siempre fallando.

Un gateway lo resuelve en la capa de red. Los clientes le hablan la API de OpenAI a una sola base URL; el proxy mapea nombres de modelos a proveedores, impone quién puede gastar qué, reintenta y hace fallback cuando un proveedor falla, y escribe cada request con su costo en una base de datos. LiteLLM es la opción open source a la que recurren la mayoría de los equipos, y el resto de la guía la arma paso a paso.

2. Conceptos Mínimos Antes de Tocar Código

Seis ideas cubren el 90% de lo que necesitás. Con esto claro, la config de abajo se lee como castellano simple.

3. Paso 1 — Correr el Proxy: Imagen Pineada + config.yaml

Arrancá por la config. Los alias son el contrato con tus clientes, así que nombralos por rol (fast, smart), no por proveedor. Las keys de los proveedores se leen del entorno con os.environ/..., nunca se escriben en el archivo. Las virtual keys, los presupuestos y los spend logs necesitan una base de datos, así que el proxy también necesita DATABASE_URL.

litellm_config.yaml — alias, master key, higiene de logs

# litellm_config.yaml
model_list:
  - model_name: fast            # alias clients request, named by role
    litellm_params:
      model: anthropic/claude-haiku-5-5
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: fast-backup     # same role, different provider
    litellm_params:
      model: openai/gpt-5-mini  # swap for the IDs your providers list today
      api_key: os.environ/OPENAI_API_KEY
  - model_name: smart
    litellm_params:
      model: anthropic/claude-sonnet-5
      api_key: os.environ/ANTHROPIC_API_KEY

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  disable_error_logs: true
  maximum_spend_logs_retention_period: "30d"
  maximum_spend_logs_retention_interval: "1d"

Ahora corrélo. Pineá un tag exacto de la imagen en vez de latest (1.105.1 es la última estable en la página de releases mientras escribo; hay release candidates de 1.106, así que chequeá cuando leas esto) y bindeá el puerto a localhost detrás de tu propio reverse proxy con TLS. Generá la master key y la salt key una sola vez y guardalas en un secret manager.

Correrlo — master key, salt key, imagen pineada

export LITELLM_MASTER_KEY="sk-$(openssl rand -hex 32)"
export LITELLM_SALT_KEY="sk-$(openssl rand -hex 32)"  # keep it; never change after adding models
export DATABASE_URL="postgresql://litellm:<password>@<db-host>:5432/litellm"

docker run -d --name litellm \
  -p 127.0.0.1:4000:4000 \
  -v "$(pwd)/litellm_config.yaml:/app/config.yaml:ro" \
  -e LITELLM_MASTER_KEY -e LITELLM_SALT_KEY -e DATABASE_URL \
  -e LITELLM_MODE=PRODUCTION \
  -e ANTHROPIC_API_KEY -e OPENAI_API_KEY \
  ghcr.io/berriai/litellm:v1.105.1 \
  --config /app/config.yaml

4. Paso 2 — Teams, Virtual Keys, Presupuestos y Rate Limits

Con el proxy arriba, usá la master key para crear la estructura y después nunca más desde una app. Un team lleva el presupuesto compartido; las keys debajo llevan límites más ajustados por workload. Cada campo de abajo está documentado en las páginas de virtual keys y de presupuestos.

curl — un team y una key acotada

# 1) team: shared budget + defaults (the response includes a team_id)
curl -s http://localhost:4000/team/new \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_alias": "support-bot",
    "max_budget": 50,
    "budget_duration": "30d",
    "rpm_limit": 60,
    "models": ["fast", "fast-backup"]
  }'

# 2) key for ONE workload inside that team (the response includes the sk-... key)
curl -s http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "<team_id from step 1>",
    "models": ["fast", "fast-backup"],
    "max_budget": 10,
    "budget_duration": "7d",
    "rpm_limit": 30,
    "tpm_limit": 100000,
    "duration": "30d",
    "metadata": {"owner": "support-team"}
  }'

Después los clientes usan el SDK de OpenAI tal cual. Apuntá base_url al gateway, pasá la virtual key como api_key y etiquetá los requests con metadata.tags para poder cortar los spend logs por feature.

Python — SDK de OpenAI contra el gateway, con tags de gasto

from openai import OpenAI

client = OpenAI(
    api_key="sk-<virtual-key>",          # the scoped key, never the master key
    base_url="http://localhost:4000",    # the gateway
)

resp = client.chat.completions.create(
    model="fast",                        # alias from model_list
    messages=[{"role": "user", "content": "Summarise this ticket in one line."}],
    extra_body={"metadata": {"tags": ["feature:ticket-summary"]}},
)
print(resp.choices[0].message.content)

5. Paso 3 — Fallbacks entre Proveedores y Spend Logs

La confiabilidad vive en router_settings. num_retries reintenta el mismo grupo de modelos; si sigue fallando, fallbacks manda el request al próximo grupo, acá otro proveedor. Tras allowed_fails fallos, un deployment entra en cooldown por cooldown_time segundos, así dejás de martillar un endpoint caído. Los números son placeholders: dimensionalos con tu propio tráfico.

router_settings — reintentos, cooldown, fallback entre proveedores

router_settings:
  routing_strategy: simple-shuffle   # default, recommended for production
  num_retries: 2                     # per model group, before falling back
  allowed_fails: 3                   # failures per minute before cooldown
  cooldown_time: 30                  # seconds out of rotation
  fallbacks: [{"fast": ["fast-backup"]}]

Dos keys relacionadas: context_window_fallbacks (necesita enable_pre_call_checks: true) reenruta un prompt que no entra en el contexto del modelo, y content_policy_fallbacks cubre los rechazos de contenido del proveedor. También podés mandar fallbacks por request en el body, o bloquearlos para una key con metadata.disable_fallbacks. Y después leés la plata de vuelta:

curl — leer el gasto de vuelta

# per-request rows, paginated (page_size max 1000)
curl -s "http://localhost:4000/spend/logs/v2?start_date=2026-10-07%2000:00:00&end_date=2026-10-14%2023:59:59&page=1&page_size=100" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

# spend grouped by team
curl -s "http://localhost:4000/global/spend/report?start_date=2026-10-01&end_date=2026-10-14&group_by=team" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

# one key: spend so far and its limits
curl -s "http://localhost:4000/key/info?key=sk-<virtual-key>" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

6. Correrlo Seguro: Lo Que Enseña el Incidente de Marzo de 2026

El 24 de marzo de 2026 se publicaron en PyPI litellm 1.82.7 y 1.82.8 con un ladrón de credenciales adentro. El security update del propio LiteLLM, NetSPI, Snyk y el hilo de GitHub coinciden en lo central: dos releases maliciosos, un payload que juntaba variables de entorno, SSH keys y credenciales cloud y de Kubernetes y las mandaba a models.litellm.cloud (un dominio no oficial), y un archivo litellm_init.pth en 1.82.8 que se ejecuta en cada arranque de Python, sin importar litellm.

LiteLLM informa que la imagen Docker oficial del proxy y la 1.82.6 o anteriores no fueron afectadas, que el compromiso arrancó por una dependencia de Trivy en su pipeline de CI, y que el 30 de marzo salió un 1.83.0 limpio con un pipeline reconstruido. Las fuentes difieren en cuánto tiempo estuvieron publicados los paquetes (unos 40 minutos según LiteLLM, cerca de tres horas según Snyk), así que no te apoyes en la ventana: si alguna de las dos versiones pasó por una máquina, asumí exposición.

Verificá antes de correr

# A) Container: verify the signature (key pinned to an immutable commit)
cosign verify \
  --key https://raw.githubusercontent.com/BerriAI/litellm/0112e53046018d726492c814b3644b7d376029d0/cosign.pub \
  ghcr.io/berriai/litellm:v1.105.1

# B) pip: exact pin + hashes for the whole dependency tree
#    requirements.in contains: litellm[proxy]==1.105.1
pip-compile --generate-hashes requirements.in -o requirements.txt
pip install --require-hashes -r requirements.txt

# C) Audit: was a bad build ever installed here?
pip show litellm | head -n 2
find / -name litellm_init.pth 2>/dev/null

7. Errores Comunes (Todos Arreglables en Minutos)

Casi cada incidente de gateway que leí cae en uno de estos baldes. La columna izquierda es lo que hacen los deployments sensatos; la derecha es lo que te despierta de noche.

Conclusión

Ya tenés el loop completo: un proxy LiteLLM pineado con alias por rol, un team y virtual keys acotadas con presupuestos y rate limits, fallbacks entre proveedores con cooldowns, gasto que podés consultar por key, team y tag, y una checklist para correrlo después del incidente de marzo.

Hacé una sola cosa esta semana: poné un servicio interno detrás del gateway con su propia key, un presupuesto chico y un fallback, y leé sus spend logs después de unos días. SSO, Redis y Kubernetes pueden venir después. No le hice pruebas de carga a este setup, así que dimensioná workers, pool de conexiones y Redis con la guía de producción antes de recibir tráfico real.

Fuentes

• Docs de LiteLLM — Docker quick start (master key, salt key, requisito de base de datos)
• Docs de LiteLLM — Virtual keys (/key/generate, /key/info, rotación)
• Docs de LiteLLM — Presupuestos y rate limits (teams, users, keys)
• Docs de LiteLLM — Confiabilidad (reintentos, fallbacks, cooldowns)
• Docs de LiteLLM — Tracking de gasto (/spend/logs, tags, reportes)
• Docs de LiteLLM — Mejores prácticas de producción
• Docs de LiteLLM — Mejores prácticas de seguridad (Admin UI, pineo de imagen)
• LiteLLM — Security update de marzo de 2026 (versiones afectadas, timeline, remediación)
• NetSPI — Compromiso de supply chain de LiteLLM
• Snyk — Poisoned security scanner backdooring litellm
• GitHub — Issue #24512: litellm_init.pth malicioso en litellm 1.82.8
• GitHub — Release v1.105.1 de LiteLLM (verificación con cosign)
• pip — Instalaciones seguras (modo de verificación de hashes)