LiteLLM: un proxy unificado local y cloud

#¿Por qué usar un proxy LiteLLM para modelos locales y en la nube?

Una pila híbrida típica tiene dos problemas. Primero, el código de la aplicación se llena de if provider == 'openai' / elif provider == 'ollama'. Segundo, la decisión "local frente a nube" queda fijada al escribir el código: si Ollama se cae, la aplicación se cae; si quieres cambiar a Claude para una tarea concreta, tienes que volver a desplegarla.

LiteLLM resuelve los dos. En la aplicación, hablas con un endpoint único compatible con OpenAI (chat/completions, embeddings, streaming). En la infraestructura, un archivo config.yaml describe tus modelos: alias lógico, backend, clave API, prioridad de fallback. Cambias la ruta sin tocar el código.

#Cómo funciona

El proxy expone el puerto 4000 por defecto. Tu app envía un POST /chat/completions con model: "chat-fr". LiteLLM revisa su config.yaml, ve que chat-fr apunta a ollama/qwen3.5:9b en localhost:11434, realiza la solicitud, normaliza la respuesta al formato OpenAI, y devuelve el resultado a la app.

En cuanto a la app

Una sola URL (http://localhost:4000), una sola clave virtual, el SDK estándar de OpenAI basta.

En el proxy

Un model_list asigna alias (chat-fr, code-rapide, analyse-doc) a backends reales.

Routing

Varios backends para el mismo alias = balanceo de carga, uso de un backend alternativo en caso de fallo y reintentos automáticos.

Observabilidad

Registros, latencias, costo por solicitud y por clave virtual, exportables hacia Langfuse, Prometheus o un Postgres.

#Prerrequisitos

Python 3.10+

LiteLLM es un paquete pip. Basta con un entorno limpio de venv o pipx.

Ollama en ejecución

En http://localhost:11434 con al menos un modelo descargado. Ver la guía de instalación de Ollama si es necesario.

Claves API para la nube (opcional)

OPENAI_API_KEY, ANTHROPIC_API_KEY si quieres redirigir hacia la nube como fallback.

Un archivo .env

Para no hacer nunca un commit con las claves en texto plano en config.yaml.

#1. Instalación

pip install 'litellm[proxy]'

El extra proxy incluye FastAPI, uvicorn y las dependencias opcionales (Postgres y Redis si quieres una limitación compartida de la tasa de solicitudes). Para una prueba rápida, es suficiente. Para producción, opta mejor por la imagen Docker oficial.

docker run -d --name litellm \
  -p 4000:4000 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  --env-file .env \
  ghcr.io/berriai/litellm:main-stable \
  --config /app/config.yaml

Comprueba que esté funcionando:

curl http://localhost:4000/health/liveliness

#2. Un config.yaml mínimo para LiteLLM

Crea config.yaml junto a tu proyecto. La estructura se compone de tres secciones: model_list (los alias), litellm_settings (comportamiento global) y general_settings (autenticación, base de datos).

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/qwen3.5:9b
      api_base: http://localhost:11434

  - model_name: code-rapide
    litellm_params:
      model: ollama/qwen3-coder:30b
      api_base: http://localhost:11434

litellm_settings:
  drop_params: true
  num_retries: 2
  request_timeout: 60

Inicia el proxy con esta configuración:

litellm --config config.yaml --port 4000

En la aplicación, el SDK de OpenAI para Python se comunica directamente con el proxy. El código de la aplicación no depende de LiteLLM:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000",
    api_key="sk-fake-local",  # le proxy n'exige pas de vraie clé par défaut
)

resp = client.chat.completions.create(
    model="chat-fr",
    messages=[{"role": "user", "content": "Résume la photosynthèse en 3 lignes."}],
)
print(resp.choices[0].message.content)

#3. Añadir OpenAI y Anthropic

Nunca se escriben las claves directamente en el código. Ponlas en un .env junto al archivo de configuración:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Luego haz referencia a las variables con la sintaxis os.environ en el YAML: LiteLLM las sustituye al arrancar:

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/qwen3.5:9b
      api_base: http://localhost:11434

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

  - model_name: analyse-doc
    litellm_params:
      model: anthropic/claude-haiku-4-5-20251001
      api_key: os.environ/ANTHROPIC_API_KEY

En este punto tienes tres alias lógicos. El código de la aplicación elige chat-fr para las conversaciones privadas, chat-gros para las consultas largas y analyse-doc para la lectura de PDF. No aparece ninguna clave en el código.

#4. Ruteo por modelo y fallback automático

Aquí es donde el proxy demuestra su verdadero valor. Dos mecanismos que conviene conocer: varias entradas bajo el mismo model_name (balanceo de carga) y la clave fallbacks (cambio en caso de error).

1. 01
   Varias entradas, un solo alias

   Puedes declarar dos veces model_name: chat-fr: una entrada apuntando a Ollama local y la otra a un Mistral en la nube. LiteLLM distribuye las solicitudes según la estrategia (simple-shuffle por defecto, o usage-based-routing si quieres optimizar el coste).
2. 02
   Fallback explícito

   En litellm_settings, declara qué alias toma el relevo si el primero devuelve un error o se agota el tiempo de espera. El fallback activa automáticamente un reintento en el backend de respaldo.
3. 03
   Comprobación activa del estado del servicio

   LiteLLM envía pings periódicamente a cada modelo. Una instancia de Ollama que deja de responder se marca como unhealthy y se retira del pool hasta que vuelva a responder: tus solicitudes pasan automáticamente a la nube.

model_list:
  - model_name: chat-fr
    litellm_params:
      model: ollama/qwen3.5:9b
      api_base: http://localhost:11434

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

litellm_settings:
  num_retries: 2
  request_timeout: 30
  fallbacks:
    - chat-fr: ["chat-fr-cloud"]
  context_window_fallbacks:
    - chat-fr: ["chat-fr-cloud"]

Con esta configuración, tu aplicación siempre utiliza model: "chat-fr". Si Ollama no está disponible, agota el tiempo de espera o el prompt supera la ventana de contexto que has asignado localmente (num_ctx reducido para ahorrar VRAM), el proxy pasa a GPT-4o-mini de forma transparente. La aplicación no lo nota: solo recibe una respuesta, quizá un poco más lenta.

#5. Seguimiento de costos y limitación de la frecuencia de solicitudes

Una pila híbrida tiene un costo oculto: crees que estás usando un modelo local y, en realidad, el 30 % de las solicitudes se han desviado a GPT-4o. LiteLLM calcula el costo de cada solicitud a partir de una tabla de precios interna (actualizada con las tarifas públicas).

Para conservar los logs y exponer un dashboard, conecta un Postgres:

general_settings:
  master_key: sk-litellm-prod-changeme
  database_url: "postgresql://litellm:pass@localhost:5432/litellm"
  store_model_in_db: true

litellm_settings:
  success_callback: ["langfuse"]   # ou prometheus, datadog, etc.
  cache: true

Una vez que se conecta Postgres, la interfaz de administración (http://localhost:4000/ui) muestra el costo por clave virtual, por modelo, por usuario. También puedes crear claves virtuales con presupuesto limitado — útil para dar acceso a un equipo sin riesgo de superar el límite.

Costos aproximados por 1 millón de tokens de salida (precios públicos de junio de 2026; debes recalcularlos con tu proveedor):

Ollama local (Qwen 3.5 9B Q4)

Coste marginal de 0 $ — tu electricidad y la amortización de la GPU.

OpenAI gpt-4o-mini

Alrededor de 0,60 $ / 1M tokens de salida, ideal para el fallback económico.

Anthropic Claude Haiku 4.5

Alrededor de 5 $ / 1M tokens de salida, más caro pero excelente relación calidad/precio en el análisis de documentos.

OpenAI gpt-4o

Aproximadamente 10 $ por 1 millón de tokens de salida, reservado para tareas donde el 4o-mini no es suficiente.

En cuanto a la limitación de solicitudes, se establecen límites RPM (solicitudes por minuto) y TPM (tokens por minuto) por modelo. LiteLLM pone las solicitudes en cola o devuelve un código 429 según tu configuración:

model_list:
  - model_name: chat-gros
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY
      rpm: 60
      tpm: 100000

#Solución de problemas

"Model not found" aunque el alias exista

Comprueba la indentación YAML. Un espacio de más bajo litellm_params hace que el proxy ignore silenciosamente la entrada. Ejecuta litellm --config config.yaml --debug para ver el model_list realmente cargado.

El fallback no se activa

num_retries debe ser ≥ 1 y debe agotarse el tiempo de espera. Por defecto, request_timeout es muy generoso en Ollama; redúcelo a 30 segundos para que los fallbacks se activen rápidamente.

Error 401 en Ollama

ollama/* no acepta una clave API. Si has añadido api_key a una entrada de Ollama, elimínala. LiteLLM pasa la clave tal cual, lo que provoca un error.

Costes incorrectos o a cero

La tabla de precios depende de la versión de LiteLLM. Actualiza (pip install -U 'litellm[proxy]'). Para un modelo personalizado que no figure en la lista, declara manualmente input_cost_per_token y output_cost_per_token en litellm_params.

Latencia anormal en Ollama

El proxy realiza una comprobación de estado cada minuto. Si Ollama tarda en cargar un modelo (arranque en frío), la comprobación supera el tiempo de espera y marca el modelo como no saludable. Aumenta health_check_interval o precarga los modelos con ollama run X --keepalive 60m.

#Para ir más allá

Con esta configuración tienes un punto de entrada único para toda tu IA, local o en la nube, con un cambio transparente entre ambas. Los siguientes pasos naturales: