#Pourquoi Docker Model Runner ?

Docker Model Runner est la réponse de Docker à Ollama : un moyen de faire tourner des LLM en local sans quitter l'écosystème Docker. Vous ne gérez plus un daemon séparé ni un dossier de modèles à part — les modèles sont distribués comme des artefacts OCI, tirés depuis un registre exactement comme des images de conteneurs, et pilotés par une nouvelle famille de commandes docker model.

Techniquement, le moteur d'inférence sous Model Runner est le même que celui d'Ollama, de LM Studio ou de Jan : llama.cpp. La différence n'est donc pas la vitesse brute, mais l'intégration. Si votre poste ou votre serveur tourne déjà sur Docker, Model Runner évite d'ajouter un outil de plus et fait dialoguer naturellement vos conteneurs avec un modèle local.

En deux mots

Docker Model Runner = docker model pull/run/rm + une API OpenAI-compatible. Les modèles sont des artefacts OCI hébergés sur Docker Hub (namespace ai/) ou tout registre compatible. Le moteur est llama.cpp, exécuté sur l'hôte pour l'accès direct au GPU — pas dans un conteneur.

Modèles au format OCI: Un LLM se tire, se versionne et se pousse comme une image Docker. Même registre, même authentification, mêmes réflexes.
API OpenAI-compatible: Endpoints /engines/v1/chat/completions, /completions, /models. N'importe quel client OpenAI s'y branche en changeant l'URL de base.
Zéro outil supplémentaire: Pas d'Ollama à installer à côté. La CLI docker suffit, et l'inférence s'intègre à Compose.
GPU exploité directement: Le moteur tourne sur l'hôte (Apple Silicon via Metal, NVIDIA via CUDA) et non dans un conteneur, pour ne pas perdre l'accélération.

#Prérequis

Docker Desktop récent: Model Runner est arrivé avec Docker Desktop 4.40 (macOS Apple Silicon), étendu ensuite à Windows avec GPU NVIDIA. Mettez à jour vers la dernière version disponible.
Ou Docker Engine sur Linux: Sur un serveur Linux sans Docker Desktop, Model Runner s'installe via le paquet docker-model-plugin (voir plus bas).
De la VRAM ou de la mémoire unifiée: En Q4_K_M, comptez ≈2 Go pour un 3B, ≈5 Go pour un 7B, ≈9 Go pour un 14B, ≈19 Go pour un 32B. Sur Mac, la mémoire unifiée fait office de VRAM.
Un GPU conseillé: RTX 3060 12 Go pour démarrer, RTX 4070/4080 en milieu de gamme, RTX 4090 24 Go ou un Mac M4 Pro (24-48 Go unifiés) pour les gros modèles. Le CPU seul fonctionne, mais lentement.

Ce n'est pas « le LLM dans un conteneur »

Contrepied fréquent : Model Runner ne fait pas tourner le modèle à l'intérieur d'un conteneur Docker. Le moteur d'inférence s'exécute sur l'hôte, chargé à la demande, pour garder un accès direct au GPU. Docker orchestre le téléchargement, le stockage OCI et l'API, mais l'inférence reste native.

#1. Activer Docker Model Runner

La fonctionnalité n'est pas toujours active par défaut. Dans Docker Desktop, elle se trouve dans les réglages ; en ligne de commande, une seule instruction suffit.

01
Via Docker Desktop
Ouvrez Settings → AI (ou « Beta features » selon la version), puis cochez « Enable Docker Model Runner ». Pour appeler l'API depuis l'hôte, activez aussi « Enable host-side TCP support » et notez le port proposé (12434 par défaut).
02
Via la CLI
Une commande active le service et, en option, ouvre le port TCP côté hôte pour joindre l'API depuis votre machine sans passer par un conteneur.
03
Vérifier
docker model status confirme que le runner tourne. docker model version affiche la version du plugin installé.

Activer 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

Sur un serveur Linux avec Docker Engine (sans Docker Desktop), Model Runner s'ajoute sous forme de plugin. Sur une distribution Debian/Ubuntu :

Docker Engine — Linux

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

# Confirmer
docker model version

Une nouvelle famille de commandes

docker model se comporte comme docker image ou docker container : pull, run, ls, rm, inspect, logs. Si vous connaissez la CLI Docker, vous connaissez déjà la logique de Model Runner.

#2. Tirer un modèle au format OCI

Docker héberge une bibliothèque de modèles empaquetés en OCI sous le namespace ai/ de Docker Hub. On les tire exactement comme des images, avec docker model pull. Les tags encodent la taille et la quantification du modèle.

Tirer des modèles

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

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

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

# Lister ce qui est stocké localement
docker model ls

ai/smollm2: Très petit modèle, idéal pour valider l'installation en quelques secondes même sans GPU.
ai/qwen2.5 · ai/gemma3 · ai/llama3.2: Des modèles généralistes solides ; choisissez la taille selon votre VRAM (3B, 7B, 14B…).
Tags de quantification: Un tag comme 7B-Q4_K_M précise la taille et la compression. Q4_K_M est le compromis recommandé qualité/mémoire ; Q5_K_M et Q8_0 pèsent plus lourd.

Le format OCI signifie que ces modèles vivent dans n'importe quel registre compatible : Docker Hub, mais aussi un registre privé d'entreprise. Vous pouvez donc pousser un modèle interne comme vous poussez une image, avec la même authentification et les mêmes politiques d'accès.

→

Modèles depuis Hugging Face

Au-delà du namespace ai/, Model Runner sait tirer des GGUF directement depuis Hugging Face en préfixant la référence par hf.co/. Pratique pour un modèle qui n'est pas (encore) publié sur Docker Hub.

#3. Discuter avec docker model run

Comme docker run lance un conteneur, docker model run lance une conversation. Sans argument de message, il ouvre un chat interactif dans le terminal ; avec un prompt, il répond une fois et rend la main — parfait pour scripter.

Terminal

# Chat interactif
docker model run ai/qwen2.5

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

Le premier appel à un modèle le charge en mémoire ; les suivants réutilisent l'instance chargée. Le moteur décharge automatiquement le modèle après une période d'inactivité pour libérer la VRAM, sans que vous ayez à gérer un daemon.

Inspecter et nettoyer

# Détails d'un modèle (taille, quantization, architecture)
docker model inspect ai/qwen2.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

Chargement à la demande

Model Runner ne garde pas tous vos modèles en VRAM. Il charge celui qu'on lui demande, le maintient chaud le temps de l'usage, puis le libère. C'est proche du comportement d'Ollama, sans processus résident à surveiller.

#4. L'API OpenAI-compatible

Le vrai levier de Docker Model Runner, comme d'Ollama, c'est son API OpenAI-compatible. Tout outil conçu pour l'API d'OpenAI fonctionne en changeant simplement l'URL de base. Deux adresses existent selon d'où vous appelez.

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

Un appel chat direct en curl depuis l'hôte, une fois le port TCP activé :

Appel /engines/v1/chat/completions

curl http://localhost:12434/engines/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/qwen2.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 ?"}
    ]
  }'

Le champ model doit correspondre à un modèle tiré localement. Côté SDK Python d'OpenAI, il suffit de rediriger base_url ; la clé API peut être n'importe quelle chaîne, Model Runner ne l'exige pas en local.

Client OpenAI 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/qwen2.5",
    messages=[
        {"role": "user", "content": "Donne trois idées de noms pour un projet open source."}
    ],
)
print(resp.choices[0].message.content)

→

Migrer depuis Ollama

Ollama expose la même famille d'endpoints sur http://localhost:11434/v1. Pour basculer une app d'Ollama vers Model Runner, changez l'URL de base pour http://localhost:12434/engines/v1 et le nom du modèle. Le reste du code OpenAI ne bouge pas.

#5. Brancher un conteneur sur le modèle

L'atout de l'intégration Docker se voit ici : un conteneur de votre application peut appeler le modèle via le DNS interne, sans exposer de port sur l'hôte. Depuis le code qui tourne dans un conteneur, l'URL de base devient model-runner.docker.internal.

Depuis un conteneur

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

En pratique, on passe l'URL par variable d'environnement pour que le même code marche en local (port 12434) et en conteneur (DNS interne). Un extrait de docker-compose.yml qui injecte l'endpoint dans le service applicatif :

docker-compose.yml

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

Un modèle partagé entre services

Plusieurs conteneurs peuvent viser le même endpoint model-runner.docker.internal : le modèle est chargé une fois côté hôte et servi à tous. Idéal pour une stack RAG ou un back-end multi-services qui partagent le même LLM local.

#Docker Model Runner ou Ollama, selon votre workflow

Les deux font tourner llama.cpp et exposent une API OpenAI-compatible. Le choix se joue sur l'écosystème dans lequel vous travaillez, pas sur la performance brute.

Choisissez Model Runner: Quand Docker est déjà votre socle : vous voulez que vos conteneurs parlent au LLM via le réseau Docker, distribuer des modèles via un registre OCI privé, et éviter un outil de plus à installer et maintenir.
Choisissez Model Runner: Pour une stack Compose où le modèle est un service parmi d'autres, versionné et déployé avec les mêmes réflexes que vos images.
Restez sur Ollama: Quand vous voulez le catalogue de modèles le plus large et le plus à jour, une communauté et une documentation abondantes, et un outil qui marche identiquement sur Windows, macOS et Linux sans Docker Desktop.
Restez sur Ollama: Pour un usage bureautique simple, en dehors de tout contexte conteneurisé : Ollama sur son port 11434 reste le plus direct, avec un écosystème d'interfaces (Open WebUI, LM Studio) déjà câblé dessus.

Model Runner est jeune

Docker Model Runner est bien plus récent qu'Ollama et évolue vite : la disponibilité par plateforme, les commandes et le catalogue changent au fil des versions de Docker. Ollama reste, à ce jour, l'écosystème le plus mûr. Vérifiez la doc officielle Docker pour l'état exact des fonctionnalités.

#Dépannage

« docker: 'model' is not a docker command »: Le plugin n'est pas installé ou Model Runner n'est pas activé. Mettez Docker Desktop à jour, activez la fonctionnalité, ou installez docker-model-plugin sur Docker Engine.
L'API ne répond pas sur localhost:12434: Le support TCP côté hôte n'est pas activé. Relancez docker desktop enable model-runner --tcp 12434, ou cochez l'option dans Settings → AI.
Un conteneur ne joint pas le modèle: Depuis un conteneur, utilisez model-runner.docker.internal, pas localhost : localhost pointe le conteneur lui-même, pas l'hôte.
Chargement lent ou « out of memory »: Le modèle dépasse votre VRAM. Tirez une variante plus légère (tag Q4_K_M au lieu de Q5/Q8) ou une taille inférieure, et vérifiez que le GPU est bien détecté.
Le GPU n'est pas utilisé (Windows): Le support GPU NVIDIA sous Windows est arrivé après la sortie initiale. Assurez-vous d'être sur une version de Docker Desktop qui le prend en charge et que vos pilotes sont à jour.

#Pour aller plus loin

Docker Model Runner s'apprécie mieux en le reliant aux autres briques de l'IA locale déjà couvertes sur le site :

Installer Ollama : Windows, macOS et Linux: Pour comparer sur pièce avec l'alternative de référence et son port 11434, et décider laquelle correspond à votre workflow.
Q4, Q5, Q8 : quelle quantification choisir: Pour lire correctement les tags des modèles OCI (7B-Q4_K_M, etc.) et arbitrer qualité, vitesse et mémoire avant de tirer.
llama-server : une API OpenAI locale avec llama.cpp: Pour voir le même moteur exposé autrement, avec un contrôle plus fin de l'offloading GPU.

Ce guide vous a aidé ?

Un retour, une erreur, une précision ? Faites-nous signe, ça améliore le guide pour tout le monde.

Suite logique

Installation · 6 min

Docker Model Runner : lancer des LLM avec Docker, sans Ollama