Docker Model Runner: LLMs mit Docker starten, ohne Ollama

#Warum Docker Model Runner?

Docker Model Runner ist Dockers Antwort auf Ollama: eine Möglichkeit, LLMs lokal auszuführen, ohne das Docker-Ökosystem zu verlassen. Sie verwalten keinen separaten Daemon und kein gesondertes Modellverzeichnis mehr – die Modelle werden als OCI-Artefakte verteilt, genau wie Container-Images aus einer Registry abgerufen und über eine neue Familie von docker model-Befehlen gesteuert.

Technisch gesehen ist die Inferenz-Engine hinter Model Runner dieselbe wie bei Ollama, LM Studio oder Jan: llama.cpp. Der Unterschied liegt also nicht in der reinen Geschwindigkeit, sondern in der Integration. Wenn Sie auf Ihrem Rechner oder Server bereits Docker einsetzen, erspart Ihnen Model Runner ein zusätzliches Tool und ermöglicht Ihren Containern die unkomplizierte Kommunikation mit einem lokalen Modell.

Modelle im OCI-Format

Ein LLM lässt sich wie ein Docker-Image herunterladen, versionieren und hochladen. Dieselbe Registry, dieselbe Authentifizierung, dieselben gewohnten Abläufe.

OpenAI-kompatible API

Endpunkte /engines/v1/chat/completions, /completions, /models. Jeder OpenAI-kompatible Client lässt sich durch Ändern der Basis-URL daran anbinden.

Kein zusätzliches Werkzeug

Ollama muss nicht zusätzlich installiert werden. Die Docker-CLI genügt, und die Inferenz lässt sich in Compose integrieren.

GPU direkt genutzt

Die Inferenz-Engine läuft auf dem Host (Apple Silicon über Metal, NVIDIA über CUDA) und nicht in einem Container, damit die Beschleunigung erhalten bleibt.

#Voraussetzungen

Aktuelle Version von Docker Desktop

Model Runner wurde mit Docker Desktop 4.40 (macOS auf Apple Silicon) eingeführt und anschließend auf Windows mit NVIDIA-GPU ausgeweitet. Aktualisieren Sie auf die neueste verfügbare Version.

Oder Docker Engine unter Linux

Auf einem Linux-Server ohne Docker Desktop wird Model Runner über das Paket docker-model-plugin installiert (siehe unten).

VRAM oder Unified Memory

Bei Q4_K_M rechnen Sie mit etwa 2 GB für ein 3B-Modell, etwa 5 GB für ein 7B-Modell, etwa 9 GB für ein 14B-Modell und etwa 19 GB für ein 32B-Modell. Auf dem Mac dient der vereinheitlichte Speicher als VRAM.

Eine GPU wird empfohlen

RTX 3060 mit 12 GB für den Einstieg, RTX 4070/4080 in der Mittelklasse, RTX 4090 mit 24 GB oder ein Mac M4 Pro (24–48 GB gemeinsamer Speicher) für große Modelle. Der Betrieb allein auf der CPU funktioniert, ist aber langsam.

#1. Docker Model Runner aktivieren

Die Funktion ist nicht immer standardmäßig aktiv. In Docker Desktop finden Sie sie in den Einstellungen; über die Kommandozeile reicht ein einziger Befehl aus.

1. 01
   Per Docker Desktop

   Öffnen Sie Settings → AI (oder je nach Version „Beta features“) und aktivieren Sie das Kontrollkästchen „Enable Docker Model Runner“. Um die API vom Host aus aufzurufen, aktivieren Sie auch „Enable host-side TCP support“ und notieren Sie den vorgeschlagenen Port (standardmäßig 12434).
2. 02
   Über die CLI

   Ein Startbefehl aktiviert den Dienst und öffnet optional den TCP-Port auf der Hostseite, um die API von Ihrer Maschine aus direkt zu erreichen, ohne über einen Container zu gehen.
3. 03
   Prüfen

   docker model status confirme que le runner tourne. docker model version affiche la version du plugin installé.

# 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

Auf einem Linux-Server mit Docker Engine (ohne Docker Desktop) wird Model Runner als Plugin hinzugefügt. Auf einer Debian/Ubuntu-Distribution:

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

# Confirmer
docker model version

#2. Ein Modell im OCI-Format laden

Docker hostet auf Docker Hub unter dem Namespace ai/ eine Bibliothek von Modellen, die im OCI-Format verpackt sind. Sie werden mit docker model pull genauso heruntergeladen wie Images. Die Tags kodieren die Größe und die Quantisierung des Modells.

# 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

Sehr kleines Modell, ideal, um die Installation selbst ohne GPU in wenigen Sekunden zu überprüfen.

ai/qwen3.5 · ai/gemma4 · ai/granite4.2

Die soliden Allzweckmodelle von 2026; wählen Sie die Größe entsprechend Ihrem VRAM (2B, 4B, 9B, 12B…). Qwen 3.5 9B (≈6,6 GB in Q4) ist bei 8 GB eine gute Standardwahl; alle stehen unter der Apache-2.0-Lizenz.

Quantisierungstags

Ein Tag wie 9B-Q4_K_M gibt die Größe und die Kompression an. Q4_K_M ist der empfohlene Kompromiss zwischen Qualität und Speicherbedarf; Q5_K_M und Q8_0 benötigen mehr Speicher.

Das OCI-Format bedeutet, dass diese Modelle in jeder kompatiblen Registry gespeichert werden können: auf Docker Hub, aber auch in einer privaten Unternehmens-Registry. Sie können daher ein internes Modell genauso wie ein Container-Image pushen, mit derselben Authentifizierung und denselben Zugriffsrichtlinien.

#3. Mit docker model run chatten

So wie docker run einen Container startet, startet docker model run ein Gespräch. Ohne Nachrichtenargument öffnet der Befehl einen interaktiven Chat im Terminal; mit einem Prompt antwortet er einmal und gibt die Kontrolle zurück – ideal für die Verwendung in Skripten.

# 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."

Beim ersten Aufruf eines Modells wird es in den Speicher geladen; spätere Aufrufe verwenden die bereits geladene Instanz erneut. Die Engine entlädt das Modell nach einer Zeit der Inaktivität automatisch, um VRAM freizugeben, ohne dass Sie einen Daemon verwalten müssen.

# 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

#4. OpenAI-kompatible API

Die entscheidende Stärke von Docker Model Runner ist, wie bei Ollama, seine OpenAI-kompatible API. Jedes für die OpenAI-API entwickelte Tool funktioniert, wenn Sie lediglich die Basis-URL ändern. Je nachdem, von wo aus Sie die API aufrufen, gibt es zwei Adressen.

Vom Host aus (TCP)

http://localhost:12434/engines/v1/… si vous avez activé le support TCP côté hôte (port 12434 par défaut).

Aus einem Container

http://model-runner.docker.internal/engines/v1/… — un nom DNS interne résolu automatiquement dans le réseau Docker.

Ein direkter Chataufruf über curl vom Host, nachdem der TCP-Port aktiviert wurde:

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 ?"}
    ]
  }'

Das Feld model muss einem lokal heruntergeladenen Modell entsprechen. Im Python-SDK von OpenAI genügt es, base_url umzuleiten; der API-Schlüssel kann eine beliebige Zeichenfolge sein, da Model Runner ihn im lokalen Betrieb nicht verlangt.

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)

#5. Einen Container mit dem Modell verbinden

Hier zeigt sich der Vorteil der Docker-Integration: Ein Container Ihrer Anwendung kann das Modell über das interne DNS aufrufen, ohne einen Port auf dem Host freizugeben. Für Code, der in einem Container läuft, lautet die Basis-URL dann model-runner.docker.internal.

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"}]
  }'

In der Praxis wird die URL über eine Umgebungsvariable übergeben, damit derselbe Code sowohl lokal (Port 12434) als auch im Container (interne DNS-Auflösung) funktioniert. Ein Ausschnitt aus docker-compose.yml, der den Endpoint an den Anwendungsdienst übergibt:

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

#Docker Model Runner oder Ollama, je nach Ihrem Workflow

Beide führen llama.cpp aus und stellen eine OpenAI-kompatible API bereit. Entscheidend für die Wahl ist das Ökosystem, in dem Sie arbeiten, nicht die reine Leistung.

Wählen Sie Model Runner

Wenn Docker bereits Ihre Grundlage ist: Sie möchten, dass Ihre Container über das Docker-Netzwerk mit dem LLM kommunizieren, Modelle über eine private OCI-Registry verteilen und vermeiden, ein weiteres Tool installieren und warten zu müssen.

Wählen Sie Model Runner

Für einen Compose-Stack, in dem das Modell ein Dienst unter mehreren ist und genauso wie Ihre Container-Images versioniert und bereitgestellt wird.

Bleiben Sie bei Ollama

Wenn Sie den größten und aktuellsten Modellkatalog, eine große Community und umfangreiche Dokumentation sowie ein Tool möchten, das unter Windows, macOS und Linux gleichermaßen ohne Docker Desktop funktioniert.

Bleiben Sie bei Ollama

Für einfache Büroanwendungen außerhalb einer containerisierten Umgebung bleibt Ollama auf Port 11434 die direkteste Lösung, mit einem Ökosystem von Benutzeroberflächen (Open WebUI, LM Studio), die bereits daran angebunden sind.

#Fehlerbehebung

« docker: 'model' is not a docker command »

Das Plugin ist nicht installiert oder Model Runner ist nicht aktiviert. Aktualisieren Sie Docker Desktop, aktivieren Sie die Funktion oder installieren Sie docker-model-plugin für Docker Engine.

Die API antwortet nicht auf localhost:12434

Die TCP-Unterstützung auf dem Host ist nicht aktiviert. Führen Sie docker desktop enable model-runner --tcp 12434 erneut aus, oder aktivieren Sie die Option unter Settings → AI.

Ein Container erreicht das Modell nicht

Verwenden Sie aus einem Container heraus model-runner.docker.internal, nicht localhost: localhost verweist auf den Container selbst, nicht auf den Host.

Langsames Laden oder „out of memory“

Das Modell benötigt mehr VRAM, als Ihnen zur Verfügung steht. Laden Sie eine leichtere Variante herunter (Tag Q4_K_M statt Q5/Q8) oder wählen Sie eine kleinere Modellgröße, und prüfen Sie, ob die GPU korrekt erkannt wird.

Die GPU wird nicht verwendet (Windows)

Die Unterstützung für NVIDIA-GPUs unter Windows kam erst nach der ursprünglichen Veröffentlichung hinzu. Stellen Sie sicher, dass Sie eine Docker-Desktop-Version verwenden, die diese GPUs unterstützt, und dass Ihre Treiber aktuell sind.

#Weiterführende Informationen

Docker Model Runner lässt sich besser beurteilen, wenn man ihn mit den anderen Bausteinen der lokalen KI verbindet, die bereits auf dieser Website behandelt werden:

Ollama installieren: Windows, macOS und Linux

Um einen direkten Vergleich mit der Referenzalternative und ihrem Port 11434 vorzunehmen und zu entscheiden, welche Lösung zu Ihrem Workflow passt.

Q4, Q5, Q8: Welche Quantisierung wählen?

Um die Tags der OCI-Modelle (7B-Q4_K_M usw.) richtig zu lesen und vor dem Herunterladen Qualität, Geschwindigkeit und Speicherbedarf gegeneinander abzuwägen.

llama-server: eine lokale OpenAI-API mit llama.cpp

Um dieselbe Engine auf andere Weise bereitgestellt zu sehen, mit einer feineren Steuerung des GPU-Offloadings.