Cómo instalar LocalAI con Docker paso a paso

Instalar LocalAI con Docker es una de las formas más rápidas y limpias de levantar un entorno local para ejecutar modelos de IA sin depender de servicios externos. En esta entrada te contamos cómo hacerlo: desde los requisitos previos a la instalación hasta un recorrido breve por la interfaz de Local AI. También veremos cómo descargar y usar modelos según el tipo de hardware instalado.

¿Qué es LocalAI y por qué instalarlo con Docker?

Antes de instalar LocalAI con Docker, conviene entender qué es exactamente esta herramienta. En pocas palabras, LocalAI es un proyecto de código abierto que se presenta como una alternativa gratuita a la API de OpenAI. Además de ser gratuito, aventaja porque todo el procesamiento se realiza en el hardware local: privacidad absoluta.

Como alternativa a la API de OpenAI, permite usar las mismas rutas, los mismos parámetros y la misma estructura de peticiones, pero ejecutando los modelos en tu máquina. Además, con LocalAI puedes cargar modelos de distintos formatos, como GGUF y GPT4All, y con propósitos diferentes: lenguaje, visión, audio e imágenes.

Algo más que sobresale de LocalAI es que no requiere de una GPU dedicada. Si bien aprovecha la aceleración hardware si está disponible, funciona de manera fluida en arquitecturas x86_64 y ARM64 en modo CPU. También cuenta con soporte nativo para agentes y la especificación Model Context Protocol (MCP).

¿Y por qué instalar LocalAI con Docker? Porque desplegarlo con contenedores Docker elimina los conflictos de dependencias en el sistema anfitrión. Además, esta es la opción más accesible y conveniente para la inmensa mayoría de usuarios y desarrolladores. El siguiente paso a paso de instalación funciona perfectamente en cualquier sistema operativo: Windows, macOS o Linux.

Requisitos para instalar LocalAI con Docker

Naturalmente, antes de empezar necesitarás tener Docker instalado en tu sistema. Si aún no lo tienes, puedes seguir la documentación oficial para tu sistema operativo. Encontrarás guías paso a paso en las entradas Cómo instalar Docker en Linux y Cómo instalar Docker en Windows 10. Una vez instalado, verifica que está funcionando correctamente ejecutando el comando docker –version.

A nivel de hardware, los requisitos para instalar LocalAI con Docker dependen del modelo o modelos que quieras correr. Recuerda que la herramienta descarga y ejecuta modelos en local. Esto significa que, mientras más grande y potente el modelo, más hardware hará falta: espacio de almacenamiento, núcleos de CPU y GB de RAM.

Paso a paso para instalar LocalAI con Docker

Vamos a ver el paso a paso para instalar LocalAI con Docker. Primero, veremos cómo hacer un despliegue rápido con Docker CLI, ideal si quieres probar la herramienta. Después explicaremos como desplegar LocalAI si tienes instalada una GPU NVIDIA (el comando cambia ligeramente). Y, por último, veremos cómo hacer un despliegue avanzado con Docker Compose si necesitas aplicar ajustes más específicos.

Paso 1: Creación de la Estructura de directorios

Lo primero es crear una estructura de directorios, es decir, una carpeta dedicada donde se almacenarán los modelos descargados y las configuraciones personalizadas en YAML. Además de mantener una organización más limpia, este paso garantiza la persistencia de datos aunque el contenedor sea destruido o actualizado. Conviene hacerlo como punto de partida sin importar el método de instalación. Abre tu terminal y ejecuta:

mkdir -p ~/localai/models
cd ~/localai

Paso 2: Selección de la imagen Docker adecuada

Menos que un paso, es una aclaración para que la tengas presente al instalar LocalAI con Docker. La herramienta ofrece imágenes optimizadas para distintas arquitecturas de hardware. Por eso, elegir la etiqueta (tag) correcta es vital para conseguir el rendimiento adecuado:

• CPU solamente: localai/localal:latest
• NVIDIA CUDA 12: localai/localai/:latest-gpu-nvidia-cuda-12
• AMD ROCm (hipBLAS): localai/localai:latest-gpu-hipblas
• Intel GPU (oneAPI): localai/localai/:latest/gpu/intel
• Aceleración Vulkan: localai/localai/:latest-gpu-vulkan

Paso 3: Instalar LocalAI con Docker CLI

Este es el punto principal y el paso más importante que te llevará a realizar una instalación rápida y básica de LocalAI con Docker. Dependiendo de tu hardware, utiliza el comando correspondiente con la etiqueta adecuada. Para una instalar LocalAI con Docker en una PC sin GPU (CPU solamente), usa el siguiente comando:

docker run -d \
  --name local-ai \
  -p 8080:8080 \
  -v $(pw)/models:/build/models:rw \
  --restart unless-stopped \
  localai/localai:latest

Por otro lado, si tu equipo cuenta con una GPU NVIDIA, el comando para instalar LocalAI con Docker cambia ligeramente. Antes de ejecutarlo, asegúrate de tener instalado el último controlador de NVIDIA y la herramienta nvidia-container-toolkit. Después, ejecuta el siguiente comando:

docker run -d \
  --name local-ai \
  -p 8080:8080 \
  --gpus all \
  -v $(pw)/models:/build/models:rw \
  --restart unless-stopped \
  localai/localai:latest-gpu-nvidia-cuda-12

Paso 4: Despliegue avanzado con Docker Compose (recomendado)

Por último, puedes instalar LocalAI con Docker Compose si buscas un despliegue avanzado, configurable y permanente de la herramienta. Este método permite definir variables de entorno, límites de memoria y configuraciones de red en un único archivo declarativo. Para ello necesitas crear un archivo llamado docker-compose.yml dentro del directorio ~/localai (mira el Paso 1) ejecutando el siguiente comando:

version: '3.8'

services:
  local-ai:
   image: localai/localai:latest-gpu-nvidia-cuda-12
   container_name: local-ai
   restart: unless-stopped
   ports:
     - "8080:8080"
   environment:
     - THREADS=8
     - DEBUG=true
     - MODELS_PATH=/build/models
     - UPLOAD_LIMIT=15M
  volumes:
   - ./models:/build/models:rw
  deploy:
   resources:
     reservations:
      devices:
        - driver: nvidia
        count: all
        capabilities: [gpu]

Este comando está adaptado para un equipo con GPU NVIDIA. Pero, si estás ejecutando en un entorno de solo CPU, cambia la imagen a localai/localai/latest y remueve la sección deploy.resources.reservations.

Paso 5: Inicia el servicio y gestiona los modelos desde la interfaz

Tras instalar LocalAI con Docker Compose, solo queda iniciar el servicio en segundo plano con el comando docker compose up -d. Si quieres, de inmediato puedes verificar los registros en tiempo real para comprobar que el servidor se ha iniciado correctamente con docker compose logs -f local-ai.

Sea con Docker Compose o con Docker CLI, en este punto ya puedes ir a la dirección http://localhost:8080 para acceder al panel de administración web (WebUI) de la herramienta. Una vez dentro, clica en la pestaña Models (Modelos) y busca un modelo ligero optimizado para pruebas, o instala el que la plataforma recomiende según el hardware instalado.

Por último, clica en Install y LocalAI descargará el archivo y generará la configuración YAML de forma automática en tu directorio. Ahora ya puedes chatear con el modelo directamente desde la WebUI de Local AI o conectarlas con otras herramientas vía servidor. Ahora solo queda explorar y experimentar con todos los modelos que quieras.