Autoalojar LiteLLM Proxy: claves virtuales, presupuestos y comparativa con New API y Magpie

Meter las claves de API principales de tus proveedores directamente en cada aplicación o portátil del equipo impide limitar cuánto puede gastar un servicio y obliga a cambiar la configuración en todas partes cuando toca rotar una clave. LiteLLM es uno de los proxies de modelos de código abierto más usados en el ecosistema de Python e ingeniería de IA: unifica más de 100 proveedores tras un único endpoint compatible con OpenAI, e incluye el panel de administración /ui, claves virtuales (Virtual Keys), límites de presupuesto (Budgets) y registro de gasto por petición.

En esta guía usamos la plantilla de LiteLLM de Zenavo para desplegar LiteLLM junto con PostgreSQL en tu propio servidor Linux, y lo comparamos con New API y Magpie. El servidor, Zenavo y las API de los modelos se facturan por separado.

1. Despliega LiteLLM y PostgreSQL

Conecta un servidor Linux a Zenavo (se recomienda al menos 1 GB de memoria), abre la plantilla de LiteLLM, elige el servidor y despliega.

El proyecto arranca con dos servicios conectados a través de la red privada del proyecto:

Servicio / Variable	Valor o finalidad
litellm	Imagen ghcr.io/berriai/litellm:v1.109.1, puerto HTTP 4000
postgresql	Imagen postgres:16, base de datos litellm, volumen persistente /var/lib/postgresql/data
LITELLM_MASTER_KEY	Clave maestra sk-... generada automáticamente para iniciar sesión en /ui y usar las API de administración
LITELLM_SALT_KEY	Sal de cifrado generada automáticamente para cifrar en PostgreSQL las claves de API de tus proveedores
STORE_MODEL_IN_DB	True, para que los modelos añadidos desde /ui se guarden en PostgreSQL

No cambies nunca LITELLM_SALT_KEY después de guardar credenciales: LiteLLM usa LITELLM_SALT_KEY para cifrar y descifrar las claves de los proveedores en la base de datos. Si la cambias más adelante, las claves guardadas dejarán de poder leerse. Copia LITELLM_MASTER_KEY y LITELLM_SALT_KEY en tu gestor de contraseñas (por ejemplo, Vaultwarden autoalojado) nada más desplegar.

2. Asocia un dominio e inicia sesión en /ui

1. En la pestaña Networking del servicio litellm, asocia un dominio personalizado como llm.example.com al puerto 4000 y añade un registro DNS A que apunte a tu servidor. Consulta Dominios y HTTPS.
2. En la pestaña Variable del servicio litellm, copia LITELLM_MASTER_KEY.
3. Abre https://llm.example.com/ui e inicia sesión con el usuario admin y tu LITELLM_MASTER_KEY.

postgresql solo se comunica con litellm por la red privada y no necesita acceso público.

3. Añade modelos y emite claves virtuales

Añade modelos de proveedores

Como la plantilla activa STORE_MODEL_IN_DB="True", no hace falta editar ningún archivo YAML:

1. En /ui, abre Models → Add Model.
2. Elige un proveedor (OpenAI, Anthropic, DeepSeek, Gemini, Azure, Bedrock, etc.), escribe el alias del modelo que pedirán tus clientes (como claude-sonnet o gpt-4o) y pega la clave de API del proveedor.
3. Guarda y envía una petición de prueba en Test Key / Playground para confirmar que responde.

Emite claves virtuales con presupuesto (Virtual Keys)

No uses LITELLM_MASTER_KEY en el código de tus aplicaciones ni en tus herramientas diarias. Abre Virtual Keys → Create New Key:

• Crea una clave distinta para cada aplicación, compañero o herramienta (por ejemplo, nextjs-prod, open-webui, claude-code-alex);
• Limita qué modelos puede llamar esa clave;
• Define un presupuesto máximo (Max Budget, por ejemplo $20), un periodo de reinicio (diario o mensual) y límites de velocidad (TPM / RPM).

4. Conecta aplicaciones, agentes de programación e interfaces de chat

Cualquier SDK o cliente que admita una URL base de OpenAI personalizada se conecta directamente a LiteLLM:

• Backends de aplicaciones (OpenAI SDK / LangChain / Vercel AI SDK): usa https://llm.example.com/v1 como Base URL y una clave virtual como API Key. Si tu aplicación corre en el mismo proyecto de Zenavo (como una app Next.js con PostgreSQL), llama directamente a http://litellm.zenavo.internal:4000/v1 por la red privada.
• Claude Code y Codex CLI: LiteLLM también sirve /v1/messages y /v1/responses; configúralos con las mismas variables de entorno explicadas en la guía de New API. Si además quieres ver registros, desplegar y revertir servicios de Zenavo desde Claude Code, consulta Desplegar y depurar proyectos de Zenavo desde Claude Code.
• Interfaces de chat y agentes personales: en Open WebUI, LobeHub u OpenClaw autoalojados, apunta la URL del proxy de OpenAI a https://llm.example.com/v1 (o http://litellm.zenavo.internal:4000/v1 dentro del mismo proyecto).

5. LiteLLM vs New API vs Magpie: ¿qué pasarela elegir?

El catálogo de Zenavo ofrece tres pasarelas de modelos de código abierto, cada una pensada para un caso de uso distinto:

Plantilla de pasarela	Enfoque principal	Almacenamiento	Ideal para
LiteLLM	Proxy OpenAI orientado a ingeniería y SDK, con claves virtuales, presupuestos, guardrails e integración con Langfuse / OpenTelemetry	PostgreSQL 16	Backends de aplicaciones de IA en producción y equipos de ingeniería que controlan presupuestos y registros por servicio
New API	Centro multiusuario de reparto y contabilidad de modelos, con cuentas de usuario, cuotas de tokens y balanceo de canales	SQLite (/data) por defecto	Repartir cuentas o tokens por persona en un equipo para usar Open WebUI, LobeHub, Claude Code y Codex
Magpie	Pasarela ligera en un solo contenedor que traduce entre Anthropic Messages, OpenAI Responses/Chat y Gemini, con conmutación por error entre claves y suscripciones	Volumen /config	Desarrolladores individuales y equipos pequeños que usan Claude Code y Codex CLI y quieren enrutar entre protocolos con un panel /me de autoconsulta

6. Copias de seguridad y actualizaciones

LiteLLM guarda sus modelos, claves virtuales y registros de gasto en el servicio postgresql:

1. Abre la pestaña Backup & Restore del servicio postgresql para crear y descargar copias de seguridad de la base de datos o programar copias automáticas. Consulta Copias de seguridad y restauración.
2. Guarda siempre LITELLM_SALT_KEY junto con las copias de seguridad de la base de datos: sin la LITELLM_SALT_KEY original, una base de datos restaurada no podrá descifrar las claves de los proveedores que contiene.
3. Antes de actualizar, haz primero una copia de seguridad de PostgreSQL y luego cambia la etiqueta de la imagen (por defecto v1.109.1) en Settings → Source del servicio litellm.

Preguntas frecuentes

¿Por qué /ui devuelve 502 recién terminado el despliegue? Al arrancar, LiteLLM espera a PostgreSQL y ejecuta sus migraciones de base de datos con Prisma; la plantilla incluye un margen de 40 segundos en la comprobación de estado (start_period: 40). Espera a que el servicio pase a Running o abre el Zenavo Agent integrado en el borde derecho de la consola para revisar los registros de arranque.

Al añadir un modelo en /ui dice que no puede guardarlo en la base de datos. Comprueba que la variable STORE_MODEL_IN_DB="True" sigue activa en el servicio litellm y que el servicio postgresql está en estado Running.

Un cliente recibe BudgetExceededError. Esa clave virtual ha alcanzado su Max Budget. Abre Virtual Keys en /ui para ampliar su presupuesto, reiniciar el gasto acumulado o configurar un reinicio mensual automático.

¿Puedo usar LiteLLM y New API juntos? Sí. Algunos equipos gestionan el grupo de canales de proveedores en New API y colocan LiteLLM delante de sus microservicios para controlar el presupuesto por aplicación y enviar trazas a Langfuse, conectando ambos por .zenavo.internal.

Despliega la plantilla de LiteLLM y pon tus proveedores de modelos tras un proxy con PostgreSQL y control de presupuesto en cuestión de minutos.