LocalAI QuickStart: Ejecute LLM compatibles con OpenAI localmente

LocalAI es un servidor de inferencia autohospedado y local-first diseñado para comportarse como una API de OpenAI de reemplazo directo para ejecutar cargas de trabajo de IA en tu propio hardware (portátil, estación de trabajo o servidor local).

El proyecto tiene como objetivo la compatibilidad práctica de “reemplazar la URL de la API en la nube”, mientras soporta múltiples backends y modalidades (texto, imágenes, audio, embeddings y más).

Qué es LocalAI y por qué los ingenieros lo utilizan

LocalAI presenta una API REST HTTP que refleja los puntos finales clave de OpenAI, incluidas las completaciones de chat, embeddings, generación de imágenes y puntos finales de audio, de modo que la herramienta existente compatible con OpenAI pueda apuntar a tu propia infraestructura.

Más allá de la generación básica de texto, el conjunto de funciones de LocalAI abarca los “bloques de construcción de producción” comunes, como embeddings para RAG, generación de imágenes basada en difusión, transcripción de voz a texto y texto a voz, con aceleración GPU opcional y patrones distribuidos.

Si estás evaluando servicios de LLM autohospedados, LocalAI es interesante porque se centra en la compatibilidad de API (para una integración más sencilla) y también proporciona una interfaz web integrada y un flujo de trabajo de galería de modelos para reducir la fricción de instalar y configurar modelos.

Para una comparación más amplia de las opciones de alojamiento de LLM autohospedado y en la nube, incluidas Ollama, vLLM, Docker Model Runner y proveedores de nube gestionados, consulta la guía de alojamiento de LLM para 2026.

Si deseas un desglose lado a lado de LocalAI frente a Ollama, vLLM, LM Studio y otros, comparando las principales herramientas de LLM locales en 2026 cubre el soporte de API, la compatibilidad de hardware y la preparación para producción. Para el caso más amplio de mantener los modelos en tu propia infraestructura, autohospedaje de LLM y soberanía de IA cubre las motivaciones de residencia de datos y cumplimiento.

Opciones de instalación de LocalAI que funcionan bien en la práctica

LocalAI se puede instalar de múltiples formas, pero para la mayoría de los equipos, el punto de partida más rápido y de menor riesgo son los contenedores (Docker o Podman). Si deseas una referencia de comandos mientras trabajas con los ejemplos a continuación, la hoja de trucos de Docker cubre los comandos de Docker más frecuentes y útiles.

Inicio más rápido con Docker

Esto inicia el servidor LocalAI y vincula la API y la interfaz web en el puerto 8080:

docker run -p 8080:8080 --name local-ai -ti localai/localai:latest

La documentación de contenedores de LocalAI llama a esto el camino más rápido para poner un servidor funcional en marcha, con la API accesible en http://localhost:8080.

Elegir la imagen de contenedor de LocalAI adecuada

LocalAI publica múltiples sabores de contenedores para que puedas coincidir con tu hardware:

• Una imagen para CPU para compatibilidad amplia.
• Imágenes específicas para GPU para NVIDIA CUDA, AMD ROCm, Intel oneAPI y Vulkan.
• Imágenes Todo-en-uno (AIO) que vienen preconfiguradas con modelos mapeados a nombres de modelos similares a OpenAI.

El README upstream de GitHub incluye ejemplos concretos de docker run para CPU solo y varias opciones de GPU (variantes de NVIDIA CUDA, AMD ROCm, Intel, Vulkan), además de variantes AIO.

Persistir modelos entre reinicios

Si no montas almacenamiento, tus modelos descargados podrían no persistir a través de cambios en el ciclo de vida del contenedor. La guía del contenedor recomienda montar un volumen de modelos, por ejemplo:

docker run -ti --name local-ai -p 8080:8080 \
  -v "$PWD/models:/models" \
  localai/localai:latest-aio-cpu

Esto hace que /models dentro del contenedor sea persistente en tu host.

Un Docker Compose QuickStart mínimo

LocalAI también proporciona un docker-compose.yaml de referencia en el repositorio, demostrando un patrón común: vincular el puerto 8080, montar un volumen /models, establecer MODELS_PATH=/models, y opcionalmente precargar un modelo especificándolo en la lista de comandos (el ejemplo del repositorio muestra phi-2). La hoja de trucos de Docker Compose es una referencia útil mientras adaptas esto a tu configuración.

Una configuración de Compose “buena por defecto” (CPU) se ve así:

services:
  localai:
    image: localai/localai:latest
    container_name: local-ai
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    environment:
      - MODELS_PATH=/models

La idea clave es la misma que en el ejemplo upstream: directorio de modelos del host ↔ /models del contenedor.

Si también estás utilizando la herramienta nativa de Docker docker model junto a LocalAI, la hoja de trucos de Docker Model Runner cubre los comandos de pull, run, package y configuración.

Instalaciones de LocalAI no basadas en contenedores

LocalAI también soporta instalaciones mediante métodos específicos de la plataforma (por ejemplo, un DMG de macOS y binarios de Linux), y opciones de despliegue más amplias como Kubernetes.

Si prefieres instalaciones escritas en scripts en Linux, el inicio rápido de DeepWiki describe un camino install.sh que detecta automáticamente el hardware y configura el sistema en consecuencia.

Una secuencia de uso predecible

Un flujo de trabajo confiable de LocalAI es:

Iniciar LocalAI → instalar o importar un modelo → verificar modelos cargados → llamar a puntos finales compatibles con OpenAI.

Esta secuencia coincide con la guía oficial “Pruébalo” y “Configuración de modelos”, que enmarca el proceso alrededor de iniciar el servidor, instalar modelos a través de la galería o CLI, y luego probar puntos finales con curl.

Iniciar el servidor y confirmar que está saludable

Una vez que el servidor está en ejecución, una verificación de sentido común común es el punto final de preparación:

curl http://localhost:8080/readyz

La guía de solución de problemas utiliza /readyz como primer diagnóstico para confirmar que LocalAI es receptivo.

Instalar un modelo desde la galería o importar una URI

LocalAI proporciona dos flujos principales de incorporación de modelos:

• Instalación en la Galería de Modelos a través de la interfaz web, donde abres la UI, vas a la pestaña Modelos, navegas por los modelos y haces clic en Instalar.
• Instalación y ejecución impulsada por CLI, usando local-ai models list, local-ai models install y local-ai run.

La documentación también soporta importar modelos por URI (repositorios de Hugging Face, URIs de archivos de modelo directos y otros registros), y la interfaz web incluye un flujo dedicado de Importar Modelo con un editor YAML para configuración avanzada.

Verificar qué piensa LocalAI que puede servir

Para listar modelos implementados a través de la API compatible con OpenAI:

curl http://localhost:8080/v1/models

Esto se recomienda explícitamente tanto como un “siguiente paso” después de la instalación del contenedor como como un diagnóstico de solución de problemas.

Principales parámetros de línea de comandos que vale la pena aprender

La CLI de LocalAI se construye alrededor del comando local-ai run, con una superficie de configuración completa. Necesitamos resaltar dos comportamientos operativos importantes:

• Cada indicador de CLI se puede establecer mediante una variable de entorno.
• Las variables de entorno tienen precedencia sobre los indicadores de CLI.

A continuación se muestran los parámetros que los profesionales terminan usando al principio, agrupados por intención. Todos los valores predeterminados y nombres de variables de entorno se toman de la referencia CLI upstream. Si estás evaluando Ollama junto a LocalAI, la hoja de trucos de CLI de Ollama cubre sus comandos serve, run, ps y de gestión de modelos para comparación.

Indicadores principales de servidor y almacenamiento

El FAQ de LocalAI también documenta las ubicaciones de almacenamiento de modelos predeterminadas y recomienda explícitamente LOCALAI_MODELS_PATH o --models-path si deseas modelos fuera del directorio predeterminado (por ejemplo, para evitar llenar un directorio de inicio).

Indicadores de rendimiento y capacidad

Para compatibilidad más amplia y restricciones de aceleración, la tabla de compatibilidad de modelos documenta qué backends soportan qué modos de aceleración (CUDA, ROCm, SYCL, Vulkan, Metal, CPU), y también nota que los modelos no configurados explícitamente pueden cargarse automáticamente, mientras que la configuración YAML te permite fijar el comportamiento. Para despliegues multi-GPU de mayor rendimiento con PagedAttention, la guía de inicio rápido de vLLM recorre un servidor comparable compatible con OpenAI con configuración orientada a producción.

Indicadores de API, seguridad y UI

Si expondrás LocalAI remotamente, deberías proteger los puntos finales y puedes restringir el acceso con una clave de API, la clave de API otorga efectivamente acceso completo.

Tour de la interfaz web y cómo se mapea al sistema

Por defecto, LocalAI sirve una interfaz web integrada junto a la API (a menos que la deshabilites). La documentación indica que la UI es accesible en el mismo host y puerto que el servidor, típicamente http://localhost:8080.

Qué puedes hacer en la interfaz web integrada

La UI web es una interfaz basada en navegador que cubre:

• Gestión de modelos y la experiencia de navegación de la galería
• Interacciones de chat
• Interfaces de generación de imágenes y texto a voz
• Configuración distribuida y P2P

La estructura de rutas ofrece un modelo mental claro del área de la interfaz:

• / para el panel de control
• /browse para el navegador de galería de modelos
• /chat/ para chat
• /text2image/ para generación de imágenes
• /tts/ para texto a voz
• /talk/ para interacción de voz
• /p2p para configuración y monitoreo P2P

Flujo de trabajo de “Galería de Modelos” e “Importar Modelo”

Para los ingenieros, la característica más importante de la interfaz es la incorporación de modelos. La guía oficial “Configurando Modelos” describe:

• Instalar modelos a través de la pestaña Modelos con instalación de un clic.
• Importar modelos a través de una UI de Importar Modelo que soporta un modo simple (URI + preferencias) y un modo avanzado con editor YAML y herramientas de validación.

Esto es importante porque LocalAI ejecuta modelos basados en configuración YAML: puedes gestionar archivos YAML individuales en el directorio de modelos, usar un solo archivo con múltiples definiciones de modelo mediante --models-config-file, o referenciar URLs de YAML remotos al inicio.

Ejemplos que puedes pegar en una terminal

Los puntos finales compatibles con OpenAI de LocalAI están diseñados para aceptar formatos de solicitud familiares y devolver respuestas JSON (con puntos finales de audio que devuelven cargas de trabajo de audio).

Ejemplo de completaciones de chat con curl

La página “Pruébalo” de LocalAI muestra llamar al punto final de completaciones de chat directamente:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      { "role": "user", "content": "Escribe una explicación de un párrafo sobre qué es LocalAI." }
    ],
    "temperature": 0.2
  }'

Las imágenes AIO vienen con modelos preconfigurados mapeados a nombres similares a OpenAI como gpt-4, y la documentación del contenedor explica que estos están respaldados por modelos de código abierto.

Si no estás usando una imagen AIO, reemplaza "model" con el nombre del modelo que instalaste (verifica con /v1/models).

Ejemplo de embeddings para pipelines de RAG

LocalAI soporta embeddings y documentos con los que el punto final de embeddings es compatible con varios backends, incluyendo llama.cpp, bert.cpp y sentence-transformers.

Una solicitud mínima de “incrustar este texto” contra el punto final compatible con OpenAI se ve así:

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": "Los embeddings de LocalAI son útiles para búsqueda semántica y RAG."
  }'

La documentación de embeddings de LocalAI también muestra cómo se habilitan los embeddings mediante configuración YAML estableciendo embeddings: true.

Ejemplo usando un cliente compatible con OpenAI

LocalAI está diseñado para que puedas usar bibliotecas de clientes estándar de OpenAI apuntándolas a la URL base de LocalAI (y opcionalmente estableciendo una clave de API si habilitaste autenticación). Este objetivo de “reemplazo directo” se describe tanto en el README upstream como en la documentación de compatibilidad con OpenAI.

Una configuración típica es:

• URL base: http://localhost:8080/v1
• Clave de API: ya sea no requerida (predeterminado) o requerida si configuraste --api-keys

Esenciales de seguridad y solución de problemas

Asegurar un servidor LocalAI antes de exponerlo

LocalAI puede ejecutarse completamente abierto en localhost por defecto. Si vinculas a una interfaz pública o lo expondrás a través de un ingress, agrega al menos uno de estos controles:

• Habilitar autenticación de clave de API usando --api-keys / API_KEY.
• Colocar un proxy inverso y controles de red delante de él (firewall, lista de permisos, VPN).
• Deshabilitar la interfaz web si solo necesitas la API (--disable-webui).
• Mantener CORS deshabilitado a menos que un cliente basado en navegador realmente lo necesite.

Cuando las claves de API están habilitadas, los puntos finales compatibles con OpenAI aceptan credenciales en lugares comunes como un encabezado Bearer Authorization o encabezado x-api-key.

Diagnósticos rápidos cuando algo no funciona

La guía de solución de problemas de LocalAI sugiere un conjunto pequeño de comprobaciones que resuelven la mayoría de incidentes de “¿está ejecutándose?”:

# preparación
curl http://localhost:8080/readyz

# listar modelos
curl http://localhost:8080/v1/models

# versión
local-ai --version

También documenta habilitar registro de depuración mediante DEBUG=true o --log-level=debug, y para despliegues de Docker, verificar los registros del contenedor con docker logs local-ai.