Cómo alojar LocalAI en un VPS

Mientras Ollama se centra en el texto, LocalAI apunta a una compatibilidad amplia con la API de OpenAI: expone /v1/chat/completions, /v1/embeddings, /v1/images/generations e incluso la transcripción de audio, en una sola API. Para un equipo que ya tiene código escrito contra el SDK de OpenAI, LocalAI es un reemplazo casi transparente: cambia la URL base y la clave, y el resto funciona. En un VPS obtiene esa polivalencia sin dependencia externa ni coste por llamada. Resulta especialmente pertinente cuando necesita a la vez generación de texto, vectores para RAG y, puntualmente, imágenes, sin multiplicar proveedores ni claves.

Como LocalAI es polivalente, sus necesidades dependen de las funciones activadas. Las cifras siguientes son mínimos medidos — un VPS más potente reduce los tiempos de respuesta sin cambiar la viabilidad.

Solo texto, CPU, modelo 7B (p. ej. Mistral-7B-GGUF): 8 GB de RAM, 4 vCPU, 30 GB de disco. A este tamaño, una llamada a /v1/chat/completions tarda entre 5 y 15 segundos según la cuantización (Q4 es el equilibrio estándar). Un modelo 3B cabe en 4 GB de RAM.

Texto + imágenes (7B + Stable Diffusion): 16 GB de RAM, GPU recomendada, 50 GB de disco. Sin GPU, generar una imagen tarda varios minutos en CPU — prefiera un VPS con GPU para un uso habitual y la opción SINGLE_ACTIVE_BACKEND=true para evitar la saturación al combinar chat e imágenes en el mismo host CPU.

Software requerido: Docker 24+ y Docker Compose v2 (docker compose sin guión), un subdominio dedicado (p. ej. ia.su-dominio.com), el puerto 443 abierto, un registro DNS apuntando a la IP del VPS.

LocalAI soporta varios formatos, pero el formato GGUF (producido por llama.cpp) es el estándar recomendado para CPU: está cuantizado (reduce el uso de RAM), es portable y está bien soportado por la galería.

GGUF vs otros formatos: los formatos GGUF son los únicos cargables directamente vía llama.cpp sin conversión previa. Los modelos Diffusers (imágenes) y ONNX (embeddings ligeros) tienen sus propios backends y no son intercambiables con los GGUF.

Galería vs descarga manual: la galería es la opción más sencilla — descarga el GGUF y genera el YAML de configuración automáticamente. Para un modelo no listado en la galería (un modelo ajustado, un GGUF personalizado), deposite el archivo en ./models/ y cree el YAML manualmente:

name: mi-modelo
backend: llama
parameters:
  model: mi-modelo.Q4_K_M.gguf
context_size: 4096

Listar los modelos cargados:

curl https://ia.su-dominio.com/v1/models \
  -H 'Authorization: Bearer su-clave-secreta'

Los modelos cuyo YAML está presente en ./config/ aparecen en la lista, incluso si su GGUF aún no se ha descargado — en ese caso, la primera llamada desencadena la descarga.

Al ser LocalAI compatible con la API de OpenAI, migrar una aplicación existente se reduce a dos cambios: la URL base y la clave.

Python (openai SDK):

import openai

client = openai.OpenAI(
    base_url="https://ia.su-dominio.com/v1",
    api_key="su-clave-secreta"
)

response = client.chat.completions.create(
    model="mistral-7b-instruct-v0.2.Q4_K_M",
    messages=[{"role": "user", "content": "Resume este texto: ..."}]
)
print(response.choices[0].message.content)

Node.js (openai SDK):

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://ia.su-dominio.com/v1',
  apiKey: 'su-clave-secreta'
});

const completion = await client.chat.completions.create({
  model: 'mistral-7b-instruct-v0.2.Q4_K_M',
  messages: [{ role: 'user', content: 'Hola' }]
});
console.log(completion.choices[0].message.content);

curl directo:

curl https://ia.su-dominio.com/v1/embeddings \
  -H 'Authorization: Bearer su-clave-secreta' \
  -H 'Content-Type: application/json' \
  -d '{"model": "all-minilm", "input": "Texto a vectorizar"}'

Las bibliotecas LangChain, LlamaIndex y la mayoría de los frameworks RAG aceptan un parámetro openai_api_base o base_url — el cambio es idéntico.

404 model not found o model not loaded: el nombre de modelo pasado en model: no coincide con ningún manifiesto YAML en ./config/. Compruebe con GET /v1/models: el nombre mostrado debe usarse exactamente tal cual. Si el modelo no aparece, verifique que el YAML esté en la carpeta montada y reinicie el contenedor.

Inferencia muy lenta o killed (OOM): el modelo supera la RAM disponible. Un modelo 7B Q4 requiere aproximadamente 6 GB de RAM libre en el momento de la carga. Compruebe con docker stats localai durante una inferencia. Soluciones: pasar a una cuantización más ligera (Q3_K_S o Q2_K), reducir el context_size en el YAML, o actualizar el VPS.

SINGLE_ACTIVE_BACKEND error: LocalAI está configurado con SINGLE_ACTIVE_BACKEND=true y una petición intenta cargar un segundo modelo mientras otro está activo. Es el comportamiento esperado en CPU. Espere a que termine la primera inferencia, o desactive la opción si su VPS tiene suficiente RAM para varios modelos simultáneos.

GPU no detectada (CUDA device not found): verifique que está usando la imagen latest-gpu-nvidia-cuda-12, que el driver NVIDIA está instalado en el host (nvidia-smi), y que el contenedor tiene acceso a la GPU (gpus: all en docker-compose.yaml bajo la clave deploy:). Sin estas tres condiciones, LocalAI vuelve silenciosamente a CPU.

401 Unauthorized: la variable API_KEY está definida en docker-compose.yaml pero la cabecera Authorization: Bearer <clave> está ausente o incorrecta en la llamada. Todos los endpoints, incluido /v1/models, requieren la cabecera en cuanto API_KEY está establecido.