LocalAI: API completa de OpenAI, 100 % autoalojada

#¿Por qué LocalAI?

LocalAI (el proyecto mudler/LocalAI en GitHub, bajo licencia MIT, creado y mantenido por Ettore Di Giacinto y el equipo LocalAI) se presenta como un « reemplazo directo » de la API de OpenAI. Concretamente, tus solicitudes hacia /v1/chat/completions, /v1/embeddings, /v1/audio/transcriptions, /v1/audio/speech o /v1/images/generations van hacia un servidor que tú alojas, en lugar de los servidores de OpenAI. Ningún token abandona tu red, no hay facturación por uso, no hay límites de uso.

El interés real de LocalAI no es ejecutar un chat más: es unificar varias modalidades detrás de un único endpoint compatible. Una misma instancia sirve un LLM para texto, un modelo de embeddings para tu RAG, Whisper para la transcripción, Stable Diffusion para imágenes, y ahora modelos de video. Para una aplicación que necesita varias piezas, evita ensamblar y mantener tres o cuatro servidores separados, cada uno con su propia API que aprender.

API compatible con OpenAI

Las mismas rutas, los mismos payloads JSON. Tus SDK oficiales (openai-python, openai-node) funcionan cambiando únicamente la URL base.

Multi-backend

LocalAI se basa en llama.cpp (GGUF), whisper.cpp, diffusers, piper y otros según el modelo. No necesitas instalarlos uno a uno.

Multimodal

Texto, embeddings, audio (STT + TTS) e imágenes en la misma instancia, cada uno en su ruta de la API de OpenAI.

100 % local

Funciona sin conexión una vez descargados los modelos. Sin telemetría de inferencia ni dependencia de la nube.

El proyecto se ha ampliado significativamente a lo largo de las versiones desde su descripción inicial como simple clon de la API de OpenAI. Su compatibilidad 'drop-in' cubre ahora también las API de Anthropic y ElevenLabs, en cada uno de sus backends. Es compatible con más de 60 backends —llama.cpp, vLLM, SGLang, transformers, whisper.cpp, diffusers, MLX y MLX-VLM para Apple Silicon, entre otros—, que se pueden instalar sobre la marcha desde una galería de backends, sin necesidad de incluirlos todos de antemano en una sola imagen.

LocalAI también integra agentes de IA autónomos con uso de herramientas, RAG y soporte del protocolo MCP, así como un modo multiusuario con autenticación mediante clave API, cuotas y control de acceso por rol. La versión 4.1.0 (abril de 2026) añadió un modo de clúster distribuido con enrutamiento inteligente según la VRAM disponible y autoescalado; la 4.2.0 (mayo de 2026) añadió reconocimiento de voz y facial, diarización de hablantes, una API compatible con Ollama y generación de vídeo.

#LocalAI o Ollama, según la necesidad

Los dos ejecutan GGUF a través de llama.cpp y exponen una API compatible con OpenAI para texto. La diferencia está en el alcance y la filosofía. Ollama busca la simplicidad para el texto (y algo de visión) con una CLI sencilla; LocalAI busca una cobertura amplia —varias modalidades, más backends, más ajustes y agentes integrados— a costa de tener que preparar una configuración considerablemente más extensa.

No hay nada que impida ejecutar los dos en la misma máquina: Ollama para el chat interactivo diario, LocalAI como puente multimodal para tus aplicaciones que necesiten embeddings, audio o imágenes a través de la misma API.

#Prerrequisitos

La forma más limpia de desplegar LocalAI es mediante Docker, con una imagen específica para tu hardware. Prevé la memoria necesaria según los modelos que quieras usar: al final, la VRAM (o la RAM si utilizas solo la CPU) determina qué modelos podrás servir realmente.

Docker

Docker Engine o Docker Desktop reciente. Docker Compose se recomienda para un despliegue reproducible.

GPU (opcional)

NVIDIA con el NVIDIA Container Toolkit para la aceleración CUDA 12 o 13. LocalAI también ofrece aceleración con AMD (ROCm), Intel (oneAPI/SYCL) y Apple Silicon (Metal), con Vulkan como alternativa genérica cuando ninguna de estas vías es aplicable. Sin GPU, todo se ejecuta en la CPU, más lentamente.

VRAM por tamaño (Q4)

3B ≈ 2 GB · 7B ≈ 5 GB · 14B ≈ 9 GB · 32B ≈ 19 GB · 70B ≈ 40 GB. Añade margen para un modelo de embeddings y/o Whisper si los sirves en paralelo.

Referencias de GPU

Una RTX 3060 de 12 GB (gama de entrada) o una RTX 4070 de 12 GB permiten ejecutar cómodamente un modelo de 7-14B; una RTX 4090 de 24 GB o un Mac M4 Pro con 24-48 GB de memoria unificada permiten aspirar a modelos más grandes.

Espacio en disco

Cada modelo pesa varios GB, a veces más para imágenes o vídeo. Prevé un volumen dedicado para no tener que volver a descargar nada cada vez que se reinicie el contenedor.

#Desplegar LocalAI en Docker

1. 01
   Iniciar un contenedor de prueba

   La orden más rápida arranca LocalAI y expone la API en el puerto 8080. Usa la imagen « -gpu-nvidia-cuda-12 » (o « -cuda-13 » en los controladores más recientes) si tienes una tarjeta NVIDIA, o la imagen CPU por defecto en caso contrario.
2. 02
   Verificar que la API responde

   Una vez que el contenedor esté listo, la ruta /v1/models debe devolver la lista (vacía al principio) en formato OpenAI. Es el indicio de que el servidor está bien conectado al puerto 8080.
3. 03
   Guardar los modelos de forma persistente

   Monta un volumen en /models (o /build/models según la imagen) para que los modelos descargados se conserven tras el reinicio. Sin volumen, todo se vuelve a descargar cada vez que se ejecuta «docker run».
4. 04
   Migrar a Docker Compose

   Para un uso duradero, describe el servicio en un docker-compose.yml: imagen, puertos, volumen y reserva de GPU. Lo reinicias todo con un «docker compose up -d».

# Lance LocalAI, API OpenAI-compatible sur le port 8080
docker run -p 8080:8080 --name localai \
  -v $PWD/models:/models \
  localai/localai:latest

# Version GPU NVIDIA (CUDA 12) :
# docker run -p 8080:8080 --gpus all \
#   -v $PWD/models:/models \
#   localai/localai:latest-gpu-nvidia-cuda-12

# Version GPU NVIDIA (CUDA 13, plus récente) :
# docker run -p 8080:8080 --gpus all \
#   -v $PWD/models:/models \
#   localai/localai:latest-gpu-nvidia-cuda-13

services:
  localai:
    image: localai/localai:latest-gpu-nvidia-cuda-12
    container_name: localai
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    environment:
      - DEBUG=true
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: unless-stopped

# La route est identique à celle d'OpenAI
curl http://localhost:8080/v1/models

#Instalar un modelo desde la galería

LocalAI ofrece una galería de modelos preconfigurados, accesible también mediante «local-ai models list» en línea de comandos o en models.localai.io: cada entrada incluye el backend adecuado, la plantilla del prompt y los parámetros por defecto. Puedes instalar un modelo por su nombre a través de la API, sin tener que escribir YAML manualmente.

# Installe un modèle de la galerie (nom d'exemple)
curl http://localhost:8080/models/apply -H "Content-Type: application/json" -d '{
  "id": "[email protected]"
}'

# Suivre l'avancement du téléchargement
curl http://localhost:8080/models/jobs

Para un control total, también puedes definir manualmente un modelo en un archivo YAML colocado en el directorio /models. Este archivo describe el nombre expuesto por la API, el backend y el archivo de pesos a cargar.

name: qwen2.5-7b
backend: llama-cpp
parameters:
  model: qwen2.5-7b-instruct-q4_k_m.gguf
context_size: 8192
template:
  chat: |
    <|im_start|>system
    {{.SystemPrompt}}<|im_end|>
    {{.Input}}

#Una sola API para texto, embeddings, audio e imágenes

Es aquí donde LocalAI se destaca. Cada modalidad sigue su ruta estándar de OpenAI; basta con haber instalado el modelo adecuado para cada una. Aquí tienes las cuatro piezas más útiles.

curl http://localhost:8080/v1/chat/completions -H "Content-Type: application/json" -d '{
  "model": "qwen2.5-7b",
  "messages": [{"role": "user", "content": "Explique le RAG en une phrase."}]
}'

curl http://localhost:8080/v1/embeddings -H "Content-Type: application/json" -d '{
  "model": "bert-embeddings",
  "input": "Texte à vectoriser pour ma base vectorielle"
}'

curl http://localhost:8080/v1/audio/transcriptions \
  -H "Content-Type: multipart/form-data" \
  -F file="@reunion.wav" \
  -F model="whisper-1"

curl http://localhost:8080/v1/images/generations -H "Content-Type: application/json" -d '{
  "model": "stablediffusion",
  "prompt": "un phare breton sous la pluie, aquarelle",
  "size": "512x512"
}'

#Migrar una app OpenAI sin cambiar el código

Como las rutas y los payloads son idénticos, migrar una aplicación consiste en cambiar la URL base a la que apunta y sustituir los nombres de los modelos. Los SDK oficiales aceptan una base_url personalizada: es el único parámetro que hay que modificar, tanto si la aplicación apunta a la API de OpenAI como a la de Anthropic o a la de ElevenLabs.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",  # au lieu de l'endpoint OpenAI
    api_key="sk-localai",                 # ignorée si l'auth n'est pas activée
)

resp = client.chat.completions.create(
    model="qwen2.5-7b",                    # au lieu de "gpt-4o-mini"
    messages=[{"role": "user", "content": "Bonjour !"}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:8080/v1",
  apiKey: "sk-localai",
});

const resp = await client.chat.completions.create({
  model: "qwen2.5-7b",
  messages: [{ role: "user", content: "Bonjour !" }],
});
console.log(resp.choices[0].message.content);

URL base

Reemplaza el endpoint OpenAI por http://votre-hote:8080/v1. A menudo solo una variable de entorno OPENAI_BASE_URL.

Nombres de modelos

« gpt-4o » → el nombre de tu modelo local. Es el principal ajuste que debes hacer en el código o en la configuración.

Clave de API

Opcional en local; introduce cualquier valor si el SDK lo exige, o configura una clave real en LocalAI.

Diferencias de comportamiento

Un modelo local de 7B no razona como GPT-4. Ajusta tus prompts y expectativas en lugar de asumir una paridad de calidad.

#Solución de problemas

El contenedor se inicia lentamente en el primer lanzamiento

Las imágenes de LocalAI y la primera descarga del modelo son voluminosas. Es normal; los siguientes arranques son rápidos si el volumen /models es persistente.

« model not found »

El campo «model» de la solicitud debe coincidir exactamente con el «name» de la galería o del YAML. Revísalo con «curl /v1/models».

Sin aceleración GPU

Asegúrate de usar una imagen « -gpu-nvidia-cuda-12 » (o « -cuda-13 »), instala el NVIDIA Container Toolkit y pasa « --gpus all ». Activa DEBUG=true para ver el backend realmente seleccionado.

Respuestas lentas o OOM

El modelo supera la capacidad de tu VRAM y pasa a ejecutarse parcialmente en la CPU con la RAM del sistema. Baja un nivel (Q4_K_M en lugar de Q8_0, o un modelo más pequeño) o reduce context_size.

Una modalidad no responde

Cada ruta requiere su modelo: no hay embeddings sin modelo de embeddings instalado, no hay /audio sin modelo Whisper. Instala la pieza faltante desde la galería.

#Para ir más allá

LocalAI es solo uno de los servidores de inferencia para modelos de pesos abiertos del ecosistema. Para elegir con conocimiento de causa, compáralo con llama-server (el servidor HTTP de llama.cpp) y con el enfoque de Ollama, y afina el equilibrio entre memoria y calidad de tus modelos con la guía sobre cuantización. Después, conecta una interfaz o una aplicación a LocalAI mediante su endpoint OpenAI.

• llama-server: una API OpenAI local con llama.cpp
• Ollama vs llama.cpp: ¿cuál elegir?
• Elegir tu cuantización (Q4, Q5, Q8, FP16)
• RAG local sin programar: Open WebUI, AnythingLLM
• Fuente: repositorio GitHub de LocalAI
• Fuente: documentación oficial de LocalAI
• Fuente: galería de backends LocalAI

#FAQ