◆ IA local — Tu ChatGPT privado y gratuito, en tu máquina, en 1 h · 24 € · o todos los kits 49 € →

#¿Por qué Docker Model Runner?

Docker Model Runner es la respuesta de Docker a Ollama: una forma de ejecutar LLM en local sin salir del ecosistema Docker. Ya no gestionas un daemon separado ni una carpeta de modelos aparte: los modelos se distribuyen como artefactos OCI, se descargan de un registro exactamente igual que las imágenes de contenedores y se controlan mediante una nueva familia de comandos docker model.

Técnicamente, el motor de inferencia que utiliza Model Runner es el mismo que el de Ollama, LM Studio o Jan: llama.cpp. La diferencia, por tanto, no es la velocidad bruta, sino la integración. Si tu ordenador o servidor ya utiliza Docker, Model Runner evita añadir una herramienta más y permite que tus contenedores se comuniquen de forma natural con un modelo local.

En dos palabras

Docker Model Runner = docker model pull/run/rm + una API compatible con OpenAI. Los modelos son artefactos OCI alojados en Docker Hub (espacio de nombres ai/) o en cualquier registro compatible. El motor es llama.cpp, que se ejecuta en el sistema anfitrión para acceder directamente a la GPU, no dentro de un contenedor.

Modelos en formato OCI: Un LLM se descarga, se versiona y se sube como una imagen Docker. Mismo registro, misma autenticación, mismas prácticas.
API compatible con OpenAI: Endpoints /engines/v1/chat/completions, /completions, /models. Cualquier cliente OpenAI se conecta aquí cambiando la URL base.
Sin herramienta adicional: No hace falta instalar Ollama aparte. Basta con la CLI de Docker, y la inferencia se integra con Compose.
GPU utilizada directamente: El motor se ejecuta en el equipo anfitrión (Apple Silicon mediante Metal, NVIDIA mediante CUDA) y no dentro de un contenedor, para no perder la aceleración.

#Prerrequisitos

El kit IA Local

Tu ChatGPT privado y gratuito en tu máquina en 1 hora — LM Studio, Ollama, Open WebUI, tus documentos, sin nube.

Espacio en línea de por vida
PDF + archivos
Actualizaciones de por vida

El kit IA Local →o todos los kits de por vida — 49 € →

Docker Desktop reciente: Model Runner llegó con Docker Desktop 4.40 (macOS con Apple Silicon) y después se amplió a Windows con GPU NVIDIA. Actualiza a la última versión disponible.
O bien Docker Engine en Linux: En un servidor Linux sin Docker Desktop, Model Runner se instala mediante el paquete docker-model-plugin (ver más abajo).
VRAM o memoria unificada: En Q4_K_M, considera aproximadamente 2 GB para un 3B, 5 GB para un 7B, 9 GB para un 14B y 19 GB para un 32B. En Mac, la memoria unificada funciona como VRAM.
Se recomienda una GPU: RTX 3060 de 12 GB para empezar, RTX 4070/4080 en la gama media, RTX 4090 de 24 GB o un Mac M4 Pro (24-48 GB de memoria unificada) para los modelos grandes. Usar solo la CPU funciona, pero es lento.

No es «el LLM en un contenedor»

Un detalle que suele sorprender: Model Runner no ejecuta el modelo dentro de un contenedor Docker. El motor de inferencia se ejecuta en el sistema anfitrión y se carga bajo demanda para mantener el acceso directo a la GPU. Docker orquesta la descarga, el almacenamiento OCI y la API, pero la inferencia sigue siendo nativa.

#1. Activar Docker Model Runner

La funcionalidad no está siempre activa por defecto. En Docker Desktop, se encuentra en los ajustes; en línea de comando, una sola instrucción basta.

01
A través de Docker Desktop
Abre Settings → AI (o «Beta features» según la versión) y luego marca «Enable Docker Model Runner». Para llamar a la API desde el equipo anfitrión, activa también «Enable host-side TCP support» y anota el puerto propuesto (12434 por defecto).
02
A través de la CLI
Un comando activa el servicio y, opcionalmente, abre el puerto TCP del lado del host para acceder a la API desde tu máquina sin pasar por un contenedor.
03
Verificar
docker model status confirme que le runner tourne. docker model version affiche la version du plugin installé.

Activar en CLI (Docker Desktop)

# Activer Model Runner
docker desktop enable model-runner

# Activer + exposer l'API sur le port hôte 12434
docker desktop enable model-runner --tcp 12434

# Vérifier l'état
docker model status

En un servidor Linux con Docker Engine (sin Docker Desktop), Model Runner se añade como un plugin. En una distribución Debian/Ubuntu:

Docker Engine — Linux

sudo apt-get update
sudo apt-get install docker-model-plugin

# Confirmer
docker model version

Una nueva familia de comandos

docker model se comporta como docker image o docker container: pull, run, ls, rm, inspect, logs. Si conoces la CLI de Docker, ya conoces la lógica de Model Runner.

#2. Descargar un modelo en formato OCI

Docker aloja una biblioteca de modelos empaquetados en OCI bajo el namespace ai/ de Docker Hub. Se obtienen exactamente como imágenes, con docker model pull. Los tags codifican el tamaño y la cuantización del modelo.

Descargar modelos

# Un petit modèle pour tester rapidement
docker model pull ai/smollm2

# Un modèle plus capable, tag explicite
docker model pull ai/qwen3.5

# Une variante quantifiée précise (taille + quantization)
docker model pull ai/gemma4:12B-Q4_K_M

# Lister ce qui est stocké localement
docker model ls

ai/smollm2: Modelo muy pequeño, ideal para validar la instalación en unos segundos incluso sin GPU.
ai/qwen3.5 · ai/gemma4 · ai/granite4.2: Los modelos generalistas sólidos de 2026; elige el tamaño según tu VRAM (2B, 4B, 9B, 12B…). Qwen 3.5 9B (≈6,6 GB en Q4) es una buena opción por defecto con 8 GB; todos están bajo licencia Apache 2.0.
Etiquetas de cuantización: Una etiqueta como 9B-Q4_K_M especifica el tamaño y la compresión. Q4_K_M es el equilibrio recomendado entre calidad y memoria; Q5_K_M y Q8_0 pesan más.

El formato OCI significa que estos modelos pueden alojarse en cualquier registro compatible: Docker Hub, pero también un registro privado de empresa. Por tanto, puedes subir un modelo interno igual que subes una imagen, con la misma autenticación y las mismas políticas de acceso.

→

Modelos desde Hugging Face

Además del namespace ai/, Model Runner puede descargar archivos GGUF directamente desde Hugging Face añadiendo el prefijo hf.co/ a la referencia. Útil para un modelo que (todavía) no está publicado en Docker Hub.

#3. Hablar con docker model run

Como docker run inicia un contenedor, docker model run inicia una conversación. Sin argumento de mensaje, abre un chat interactivo en el terminal; con un prompt, responde una vez y devuelve el control — perfecto para scriptear.

Terminal

# Chat interactif
docker model run ai/qwen3.5

# Prompt unique (mode « one-shot », scriptable)
docker model run ai/qwen3.5 "Explique le format OCI en une phrase."

La primera llamada a un modelo lo carga en memoria; las siguientes reutilizan la instancia cargada. El motor retira automáticamente el modelo de la memoria tras un periodo de inactividad para liberar la VRAM, sin que tengas que gestionar un daemon.

Inspeccionar y limpiar

# Détails d'un modèle (taille, quantization, architecture)
docker model inspect ai/qwen3.5

# Logs du moteur d'inférence
docker model logs

# Supprimer un modèle pour récupérer de l'espace disque
docker model rm ai/smollm2

Carga bajo demanda

Model Runner no mantiene todos tus modelos en VRAM. Carga el que le pides, lo mantiene listo para usar durante el uso y luego lo libera. Es similar al comportamiento de Ollama, sin un proceso residente que supervisar.

#4. API compatible con OpenAI

La verdadera ventaja de Docker Model Runner, al igual que la de Ollama, es su API compatible con la de OpenAI. Cualquier herramienta diseñada para la API de OpenAI funciona simplemente cambiando la URL base. Existen dos direcciones según desde dónde hagas la llamada.

Desde el host (TCP): http://localhost:12434/engines/v1/… si vous avez activé le support TCP côté hôte (port 12434 par défaut).
Desde un contenedor: http://model-runner.docker.internal/engines/v1/… — un nom DNS interne résolu automatiquement dans le réseau Docker.

Una llamada directa al chat con curl desde el host, una vez activado el puerto TCP:

Llamada a /engines/v1/chat/completions

curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/qwen3.5",
    "messages": [
      {"role": "system", "content": "Tu réponds en français, de façon concise."},
      {"role": "user", "content": "Qu'\''est-ce qu'\''un artefact OCI ?"}
    ]
  }'

El campo model debe corresponder a un modelo descargado localmente. En el SDK de Python de OpenAI, basta con redirigir base_url; la clave API puede ser cualquier cadena: Model Runner no la exige en local.

Cliente OpenAI en Python

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:12434/engines/v1",
    api_key="docker",  # non vérifiée en local
)

resp = client.chat.completions.create(
    model="ai/qwen3.5",
    messages=[
        {"role": "user", "content": "Donne trois idées de noms pour un projet open source."}
    ],
)
print(resp.choices[0].message.content)

→

Migrar desde Ollama

Ollama expone la misma familia de endpoints en http://localhost:11434/v1. Para cambiar una app de Ollama a Model Runner, modifica la URL base a http://localhost:12434/engines/v1 y el nombre del modelo. El resto del código de OpenAI no cambia.

#5. Conectar un contenedor al modelo

La ventaja de la integración Docker se ve aquí: un contenedor de tu aplicación puede llamar al modelo a través del DNS interno, sin exponer puertos en el host. Desde el código que corre dentro de un contenedor, la URL base se convierte en model-runner.docker.internal.

Desde un contenedor

curl http://model-runner.docker.internal/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/qwen3.5",
    "messages": [{"role": "user", "content": "Bonjour"}]
  }'

En la práctica, se pasa la URL mediante una variable de entorno para que el mismo código funcione en local (puerto 12434) y en un contenedor (DNS interno). Un fragmento de docker-compose.yml que inyecta el endpoint en el servicio de la aplicación:

docker-compose.yml

services:
  app:
    build: .
    environment:
      OPENAI_BASE_URL: http://model-runner.docker.internal/engines/v1
      OPENAI_API_KEY: docker
      MODEL_NAME: ai/qwen3.5

Un modelo compartido entre servicios

Varios contenedores pueden apuntar al mismo endpoint model-runner.docker.internal: el modelo se carga una sola vez en el equipo anfitrión y se sirve a todos. Ideal para una pila RAG o un back-end con múltiples servicios que comparten el mismo LLM local.

#Docker Model Runner o Ollama, según tu flujo de trabajo

Ambos ejecutan llama.cpp y exponen una API compatible con OpenAI. La elección depende del ecosistema en el que trabajas, no del rendimiento bruto.

Elige Model Runner: Cuando Docker ya es tu base: quieres que tus contenedores se comuniquen con el LLM a través de la red Docker, distribuir modelos mediante un registro OCI privado y evitar tener que instalar y mantener una herramienta más.
Elige Model Runner: Para una pila Compose en la que el modelo es un servicio entre otros, versionado y desplegado con los mismos procedimientos que tus imágenes.
Sigue usando Ollama: Cuando quieres el catálogo de modelos más amplio y actualizado, una comunidad amplia y documentación abundante, y una herramienta que funcione igual en Windows, macOS y Linux sin Docker Desktop.
Sigue usando Ollama: Para un uso básico de oficina, fuera de cualquier entorno con contenedores: Ollama en su puerto 11434 sigue siendo la opción más directa, con un ecosistema de interfaces (Open WebUI, LM Studio) ya conectado a él.

Model Runner es reciente

Docker Model Runner es mucho más reciente que Ollama y evoluciona rápidamente: la disponibilidad por plataforma, los comandos y el catálogo cambian con las versiones de Docker. Ollama sigue siendo, hasta la fecha, el ecosistema más maduro. Consulta la documentación oficial de Docker para el estado exacto de las funcionalidades.

#Solución de problemas

« docker: 'model' is not a docker command »: El plugin no está instalado o Model Runner no está activado. Actualiza Docker Desktop, activa la función o instala docker-model-plugin en Docker Engine.
La API no responde en localhost:12434: El soporte TCP del lado del host no está activado. Vuelve a ejecutar docker desktop enable model-runner --tcp 12434, o marca la opción en Settings → AI.
Un contenedor no puede conectarse al modelo: Desde un contenedor, utiliza model-runner.docker.internal, no localhost: localhost apunta al contenedor mismo, no al host.
Carga lenta o « out of memory »: El modelo supera la capacidad de tu VRAM. Descarga una variante más ligera (etiqueta Q4_K_M en lugar de Q5/Q8) o de menor tamaño, y verifica que se detecte correctamente la GPU.
La tarjeta gráfica no se utiliza (Windows): La compatibilidad con GPU NVIDIA en Windows llegó después del lanzamiento inicial. Asegúrate de usar una versión de Docker Desktop que la admita y de que tus controladores estén actualizados.

#Para ir más allá

Docker Model Runner se aprovecha mejor al conectarlo con los demás componentes de la IA local que ya se han tratado en el sitio:

Instalar Ollama: Windows, macOS y Linux: Para comparar directamente con la alternativa de referencia y su puerto 11434, y decidir cuál se adapta a tu flujo de trabajo.
Q4, Q5, Q8: ¿qué cuantización elegir?: Para leer correctamente las etiquetas de los modelos OCI (7B-Q4_K_M, etc.) y sopesar calidad, velocidad y memoria antes de descargarlos.
llama-server: una API OpenAI local con llama.cpp: Para ver el mismo motor expuesto de otra manera, con un control más preciso del offloading a la GPU.

¿Esta guía te ha ayudado?

¿Un comentario, un error, una precisión? Avísanos, eso mejora la guía para todos.

Los kits de QuelLLMLa guía de referencia según el uso

IA local Copiloto Local Agentes Locales RAG Local IA en la empresa IA Sin Filtros Mac Imágenes IA

Todos los kits de por vida — 49 €

Continuación lógica

Instalación · 6 min