LiteLLM Proxy: 1 API para +100 LLMs (configuración Docker en 15 min)

Configuración del Proxy LiteLLM: Claves, Costos y Límites de Tasa

Tu equipo comparte claves API de OpenAI en DMs de Slack. Nadie sabe quién gastó $400 el martes pasado. No hay límites de tasa, no hay fallback cuando un proveedor se cae, y cambiar de GPT-4o a Claude significa modificar código en doce lugares. ¿Te suena familiar? Un gateway LLM auto-alojado soluciona todo esto, y el proxy LiteLLM es la opción de código abierto más popular -- un único endpoint compatible con OpenAI que enruta solicitudes a más de 100 proveedores LLM.

Esta guía cubre la configuración completa del proxy LiteLLM: Docker Compose con PostgreSQL, claves virtuales de equipo con presupuestos, seguimiento de costos, límites de tasa y conexión de IDEs de IA como Claude Code y Cursor. Si estás evaluando herramientas de gateway LLM, este es el tutorial práctico que te lleva de cero a producción.

Una nota importante antes de empezar: el SDK de LiteLLM (la biblioteca Python) y el Servidor Proxy son cosas diferentes. El SDK es para un desarrollador individual que llama a múltiples APIs LLM desde Python. El proxy es para equipos -- se sienta como servidor entre tus apps y los proveedores LLM. Si eres un dev en solitario escribiendo un script, el SDK es suficiente. Si gestionas claves, presupuestos y acceso para un equipo, necesitas el proxy. Eso es lo que configuramos aquí.

El Proxy LiteLLM de un Vistazo

Así se comparan los métodos de despliegue:

Para la mayoría de los equipos, Docker Compose con PostgreSQL es el punto medio ideal. Eso es lo que construiremos -- pero primero, hagamos que un proxy funcione en 60 segundos.

Requisitos Previos y Configuración del Entorno

Antes de empezar, asegúrate de tener:

• Docker y Docker Compose instalados (Docker Desktop incluye ambos)
• Al menos una clave API LLM (OpenAI, Anthropic o una instancia local de Ollama)
• Conocimientos básicos de terminal / CLI

Verifica que Docker esté listo y exporta tus claves API:

# Comprobar que Docker está instalado
docker --version
docker compose version

# Exportar tus claves API LLM (añade a tu perfil de shell para persistencia)
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

# Opcional: establecer una clave maestra para tu proxy (la necesitarás más adelante)
export LITELLM_MASTER_KEY="sk-master-tu-clave-secreta"

Eso es todo. Sin versión especial de Python, sin herramientas específicas del sistema operativo. Si Docker funciona en tu máquina, estás listo.

Inicio Rápido -- Tu Primer Proxy LiteLLM en 60 Segundos

Un comando para iniciar un proxy con GPT-4o:

docker run -d \
  --name litellm-proxy \
  -p 4000:4000 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e LITELLM_MASTER_KEY=$LITELLM_MASTER_KEY \
  ghcr.io/berriai/litellm:main-stable \
  --model openai/gpt-4o

Pruébalo con curl:

curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Say hello from LiteLLM"}]
  }'

O prueba desde Python:

from openai import OpenAI

# Apunta el SDK estándar de OpenAI a tu proxy
client = OpenAI(
    api_key="sk-master-tu-clave-secreta",
    base_url="http://localhost:4000/v1"
)

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Say hello from LiteLLM"}]
)
print(response.choices[0].message.content)

¿Qué acaba de pasar? Tu código habla con localhost:4000 usando el formato estándar del SDK de OpenAI. El proxy recibe la solicitud, la reenvía a la API de OpenAI con la clave real y devuelve la respuesta. El código de tu aplicación nunca toca la clave API real.

Esa es la idea central. Ahora construyamos una configuración de producción.

Configuración de Producción con Docker Compose y PostgreSQL

El único comando docker run funciona para pruebas, pero los equipos de producción necesitan seguimiento de costos persistente, claves virtuales y almacenamiento de base de datos adecuado. Eso significa Docker Compose con PostgreSQL.

El Archivo Docker Compose

# docker-compose.yml
version: "3.9"

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-stable
    container_name: litellm-proxy
    ports:
      - "4000:4000"         # Puerto API del proxy
    volumes:
      - ./config.yaml:/app/config.yaml   # Montar tu archivo de configuración
    environment:
      - LITELLM_MASTER_KEY=${LITELLM_MASTER_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - DATABASE_URL=postgresql://litellm:litellm_password@postgres:5432/litellm
      - LITELLM_SALT_KEY=${LITELLM_SALT_KEY:-sk-salt-random-string}
    command: --config /app/config.yaml --detailed_debug
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    container_name: litellm-db
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: litellm_password
    volumes:
      - litellm_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  litellm_pgdata:

La LITELLM_SALT_KEY cifra los datos de claves virtuales en la base de datos. La documentación de mejores prácticas de producción de LiteLLM recomienda configurarla para cualquier despliegue de equipo.

Iniciando el Stack

# Crear un archivo .env con tus claves (no lo subas a git)
echo "LITELLM_MASTER_KEY=sk-master-tu-secreto" > .env
echo "OPENAI_API_KEY=sk-..." >> .env
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env
echo "LITELLM_SALT_KEY=sk-salt-$(openssl rand -hex 16)" >> .env

# Iniciar todo
docker compose up -d

# Revisar logs
docker compose logs -f litellm

Verificando que Todo Funciona

# Verificación de salud
curl http://localhost:4000/health

# Probar una solicitud
curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "ping"}]}'

Si ves una respuesta exitosa, tu stack de producción está funcionando. PostgreSQL almacena todos los datos de costos, claves virtuales y métricas de uso de forma persistente a través de los reinicios de contenedores.

Veredicto: Docker Compose + PostgreSQL es la configuración de producción recomendada. Te da almacenamiento persistente, seguimiento de costos y claves virtuales con unos 10 minutos de trabajo. La documentación de despliegue con Docker cubre Kubernetes y Helm si necesitas auto-escalado más adelante.

Explicación de Config.yaml -- Una Configuración Real Multi-Proveedor

La mayoría de los tutoriales muestran una config.yaml con un modelo. Así se ve una configuración real de equipo con tres proveedores, fallbacks y balanceo de carga.

El Archivo de Configuración

# config.yaml -- Configuración real multi-proveedor
model_list:
  # Principal: OpenAI GPT-4o
  - model_name: gpt-4o          # El nombre que usa TU código
    litellm_params:
      model: openai/gpt-4o      # El proveedor/modelo real
      api_key: os.environ/OPENAI_API_KEY

  # Secundario: Anthropic Claude
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

  # Local: Ollama para desarrollo / pruebas sin costo
  - model_name: local-llama
    litellm_params:
      model: ollama/llama3.1
      api_base: http://host.docker.internal:11434

  # Fallback: enrutar "gpt-4o" a Claude si OpenAI está caído
  - model_name: gpt-4o
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY

router_settings:
  routing_strategy: least-busy    # Balancear carga entre modelos con el mismo nombre
  num_retries: 3
  retry_after: 5                  # Segundos entre reintentos
  fallbacks: [{"gpt-4o": ["claude-sonnet"]}]

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL

Alias de Modelos y Enrutamiento

Observa que gpt-4o aparece dos veces en la configuración -- una vez apuntando a OpenAI, una vez a Anthropic. Cuando tu código solicita gpt-4o, LiteLLM intenta primero OpenAI. Si falla, el parámetro fallbacks enruta automáticamente a Claude. El código de tu aplicación no cambia en absoluto.

Si usas backends de inferencia en producción como vLLM o SGLang, puedes añadirlos de la misma forma -- simplemente establece api_base a tu servidor de inferencia.

Referencia Rápida de Proveedores

El ajuste routing_strategy: least-busy distribuye solicitudes entre modelos con el mismo model_name. Si tienes dos claves de OpenAI (quizás diferentes organizaciones con diferentes límites de tasa), listarlas ambas bajo gpt-4o y LiteLLM equilibra la carga.

Claves Virtuales -- Claves API por Equipo con Presupuestos y Límites de Tasa

Aquí es donde LiteLLM deja de ser "solo un proxy" y se convierte en una herramienta de gestión de equipos. Las claves virtuales te permiten dar a cada miembro del equipo o servicio su propia clave API con límites de gasto y topes de tasa -- todo enrutado a través de tu único conjunto de claves API de proveedor.

Crear una Clave de Equipo con Presupuesto

# Crear una clave virtual con un presupuesto de $50/mes
curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "frontend-team",
    "max_budget": 50.0,
    "budget_duration": "1mo",
    "models": ["gpt-4o", "claude-sonnet"],
    "metadata": {"purpose": "frontend AI features"}
  }'

La respuesta te da una nueva clave como sk-team-abc123.... Dásela al equipo de frontend. Pueden usarla exactamente como una clave de OpenAI, pero está limitada a $50/mes y solo tiene acceso a los modelos que especificaste.

Establecer Límites de Tasa

# Crear una clave con límites de tasa: 100 solicitudes/minuto, 50K tokens/minuto
curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "backend-team",
    "max_budget": 200.0,
    "budget_duration": "1mo",
    "rpm_limit": 100,
    "tpm_limit": 50000,
    "models": ["gpt-4o", "claude-sonnet", "local-llama"]
  }'

La documentación de claves virtuales cubre cada parámetro. También puedes establecer presupuestos y límites de tasa por usuario para un control aún más granular.

Monitorear el Uso de Claves

import requests

# Verificar el gasto actual y los límites de una clave
response = requests.get(
    "http://localhost:4000/key/info",
    headers={"Authorization": f"Bearer {MASTER_KEY}"},
    params={"key": "sk-team-abc123..."}
)
info = response.json()
print(f"Gastado: ${info['spend']:.2f} / ${info['max_budget']:.2f}")
print(f"RPM usado: {info['rpm_limit_used']} / {info['rpm_limit']}")

¿Necesitas revocar una clave comprometida? Una llamada API:

curl -X POST http://localhost:4000/key/delete \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keys": ["sk-team-abc123..."]}'

Veredicto: Las claves virtuales hacen de LiteLLM una herramienta de equipo, no solo un proxy personal. Sin ellas, solo estás añadiendo un salto entre tu código y el LLM. Con ellas, tienes control de acceso, cumplimiento de presupuesto y atribución de uso -- el tipo de cosas que evitan que tu CFO entre en pánico.

Seguimiento de Costos y el Panel de Control de LiteLLM

Una vez que PostgreSQL está conectado, LiteLLM rastrea automáticamente el costo de cada solicitud. No necesitas configurar nada -- conoce el precio por token para cada modelo compatible.

El Panel de Control

Accede a la interfaz integrada en http://localhost:4000/ui (inicia sesión con tu clave maestra). Verás:

• Gasto total en todos los equipos y claves
• Desglose por modelo -- qué modelos consumen tu presupuesto
• Gasto por equipo -- quién usa qué
• Volumen de solicitudes a lo largo del tiempo

Para los equipos serios sobre la reducción de los costos de API LLM, el panel de control solo ya justifica ejecutar el proxy. También puedes conectar LiteLLM a plataformas externas de observabilidad de IA como Langfuse o Helicone para análisis más profundos.

Comparación de Costos por Proveedor

Aquí está lo que cuestan los principales modelos por millón de tokens (a abril de 2026):

Cuando ves estas cifras en el panel desglosadas por equipo, las conversaciones sobre "¿deberíamos usar un modelo más económico para este caso de uso?" se vuelven muy concretas.

Veredicto: El seguimiento de costos por sí solo justifica el proxy para cualquier equipo que gaste más de $100/mes en APIs LLM. No puedes optimizar lo que no puedes medir.

Conectar IDEs de IA -- Claude Code, Cursor y Continue

Aquí hay algo que la mayoría de las guías de LiteLLM omiten por completo: también puedes apuntar tus herramientas de codificación de IA al proxy. Un proxy, todas tus herramientas IDE, facturación unificada.

Claude Code

# Configurar Claude Code para usar tu proxy LiteLLM
export ANTHROPIC_BASE_URL=http://localhost:4000/v1
export ANTHROPIC_API_KEY=sk-team-tu-clave-virtual

Eso es todo. Claude Code envía solicitudes a tu proxy, que las enruta a Anthropic (o donde diga tu configuración) mientras rastrea los costos bajo tu clave virtual.

Cursor

En la configuración de Cursor, añade un endpoint personalizado compatible con OpenAI:

{
  "openai.apiBaseUrl": "http://localhost:4000/v1",
  "openai.apiKey": "sk-team-tu-clave-virtual"
}

Continue (VS Code)

En el config.json de Continue:

{
  "models": [
    {
      "title": "GPT-4o vía LiteLLM",
      "provider": "openai",
      "model": "gpt-4o",
      "apiBase": "http://localhost:4000/v1",
      "apiKey": "sk-team-tu-clave-virtual"
    }
  ]
}

¿Por qué molestarse? Porque ahora el uso de IDE de cada desarrollador pasa por el proxy. Obtienes seguimiento de costos por persona para asistentes de codificación de IA, límites de tasa para que nadie queme accidentalmente $500 en una sesión de codificación, y un único lugar para cambiar de modelo si encuentras una opción mejor.

Solución de Problemas Comunes

"Archivo de configuración no encontrado"

Esto generalmente significa que la ruta de montaje del volumen es incorrecta en Docker. Asegúrate de que tu config.yaml esté en el directorio desde el que montas:

# Comprobar que el archivo existe donde crees
ls -la ./config.yaml

# El montaje del volumen en docker-compose.yml debe coincidir
# volumes:
#   - ./config.yaml:/app/config.yaml

"Conexión rechazada" a PostgreSQL

Las redes Docker atrapan a todos al menos una vez. Si LiteLLM no puede llegar a Postgres, verifica que:

• El nombre del servicio en DATABASE_URL coincida con el nombre del servicio Docker Compose (postgres, no localhost)
• El depends_on con condition: service_healthy esté configurado (para que LiteLLM espere a que Postgres esté listo)
• Ambos servicios estén en la misma red Docker (lo están por defecto en Compose)

"Formato de clave API inválido"

La confusión más común: tu LITELLM_MASTER_KEY es para operaciones administrativas (crear claves virtuales, acceder al panel). Las claves virtuales (sk-team-...) son lo que usan tus aplicaciones. No las mezcles.

"Modelo no encontrado"

El campo model en tu solicitud debe coincidir con un model_name en config.yaml. Si tu configuración define gpt-4o pero tu código solicita openai/gpt-4o, no coincidirá. Verifica la ortografía exacta.

El proxy inicia pero las solicitudes se cuelgan

Generalmente un problema de firewall o de enlace de puerto. Verifica que el puerto 4000 esté expuesto y no bloqueado:

# Comprobar si el puerto está escuchando
docker port litellm-proxy
# Debe mostrar: 4000/tcp -> 0.0.0.0:4000

Seguridad: Evita las Versiones 1.82.7 y 1.82.8

En marzo de 2026, un incidente de cadena de suministro afectó las versiones 1.82.7 y 1.82.8 de LiteLLM. Las versiones comprometidas fueron retiradas y se publicó una versión limpia en 1.83.0. Siempre fija tu imagen Docker a una versión específica y verifica la actualización de seguridad oficial antes de actualizar. Si estás en 1.82.7 o 1.82.8, actualiza inmediatamente.

¿Qué Método de Configuración de LiteLLM Debes Elegir?

Si lees esta guía por primera vez, comienza con Docker Compose + PostgreSQL. Siempre puedes migrar a Kubernetes más tarde -- el config.yaml se mantiene igual.

FAQ

¿Qué es el proxy LiteLLM y cómo funciona?

El proxy LiteLLM es un servidor de gateway de IA de código abierto que se sitúa entre tus aplicaciones y los proveedores LLM como OpenAI y Anthropic. Expone un único endpoint compatible con OpenAI, de modo que tu código habla con una URL mientras el proxy maneja el enrutamiento, la gestión de claves, el seguimiento de costos y los fallbacks entre bastidores.

¿Cómo configuro el proxy LiteLLM con Docker Compose?

Crea un docker-compose.yml con la imagen del proxy LiteLLM y una base de datos PostgreSQL, monta tu config.yaml, configura tus claves API como variables de entorno y ejecuta docker compose up -d. La sección de "Configuración de Producción con Docker Compose" anterior contiene un archivo completo listo para copiar y pegar.

¿Cómo gestiono las claves API del equipo con LiteLLM?

Usa claves virtuales. Llama al endpoint /key/generate con tu clave maestra para crear claves por equipo o por usuario. Cada clave virtual puede tener su propio presupuesto mensual, límites de tasa (RPM y TPM) y restricciones de acceso a modelos. La sección "Claves Virtuales" cubre el flujo de trabajo completo.

¿Cómo añado seguimiento de costos y límites de tasa a mi API LLM?

Conecta PostgreSQL al proxy (a través de DATABASE_URL) y el seguimiento de costos ocurre automáticamente. Para los límites de tasa, establece rpm_limit y tpm_limit al generar claves virtuales. El panel integrado en /ui muestra el gasto por equipo y por modelo.

¿Es seguro usar el proxy LiteLLM en producción?

Sí, con una advertencia: evita las versiones 1.82.7 y 1.82.8, que fueron afectadas por un incidente de cadena de suministro en marzo de 2026. Usa la versión 1.83.0 o posterior. Fija la versión de tu imagen Docker, configura la LITELLM_SALT_KEY para el cifrado y sigue las mejores prácticas de producción oficiales.

¿Cuál es la diferencia entre el SDK de LiteLLM y el proxy de LiteLLM?

El SDK es una biblioteca Python para llamar a múltiples APIs LLM desde tu código. El proxy es un servidor independiente al que se conecta todo tu equipo. Usa el SDK cuando seas un dev en solitario escribiendo un script. Usa el proxy cuando necesites control de acceso compartido, seguimiento de costos y límites de tasa en todo un equipo.

¿Puedo usar el proxy LiteLLM con Ollama y modelos locales?

Absolutamente. Añade una entrada a tu config.yaml con model: ollama/llama3.1 y api_base: http://host.docker.internal:11434 (o tu host de Ollama). Tu equipo puede entonces acceder a modelos locales a través del mismo endpoint proxy, lo cual es ideal para el desarrollo y las pruebas sin costo.

¿Cuánto cuesta el proxy LiteLLM?

El proxy LiteLLM es gratuito y de código abierto (licencia MIT). Lo alojas tú mismo en tu propia infraestructura. Los únicos costos son tu servidor (un pequeño VPS es suficiente para la mayoría de los equipos) y los costos de API LLM que ya estás pagando. BerriAI también ofrece una versión gestionada en la nube si no quieres auto-alojarlo.

¿Qué proveedores admite LiteLLM?

Más de 100, incluyendo OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Google Vertex AI, Ollama, Hugging Face, Cohere, Replicate y muchos más. La lista completa está en el repositorio GitHub de LiteLLM.

¿Cómo actualizo el proxy LiteLLM de forma segura?

Siempre fija una versión específica en tu tag de imagen Docker (p. ej. ghcr.io/berriai/litellm:v1.83.2-stable). Antes de actualizar, revisa el changelog en busca de cambios que rompan compatibilidad. Nunca uses latest en producción. Y siempre verifica que la nueva versión no esté en la lista de avisos de seguridad -- el incidente de marzo de 2026 demostró que incluso los paquetes de confianza pueden verse comprometidos.

Veredicto Final y Próximos Pasos

Si tu equipo gasta dinero en APIs LLM y aún no tienes un proxy, empieza con Docker Compose + Postgres hoy. La configuración lleva 15 minutos, y al final tendrás visibilidad de costos y control de acceso.

Una vez que estés en marcha, explora la opción de añadir guardrails a tu pipeline LLM para el filtrado de contenido y las comprobaciones de seguridad. El proxy es la base -- todo lo demás se construye encima de él.

Fuentes

• Inicio Rápido del Proxy LiteLLM -- Documentación oficial
• Guía de Despliegue Docker de LiteLLM
• Documentación de Claves Virtuales de LiteLLM
• Mejores Prácticas de Producción de LiteLLM
• Actualización de Seguridad de LiteLLM -- Marzo 2026
• BerriAI/litellm -- Repositorio GitHub