Docker Model Runner Cheatsheet: Befehle & Beispiele

Schnellreferenz für Docker Model Runner-Befehle

Docker Model Runner (DMR) ist Docks offizielle Lösung zur lokalen Ausführung von KI-Modellen, eingeführt im April 2025. Dieses Cheat Sheet bietet eine schnelle Referenz für alle wesentlichen Befehle, Konfigurationen und Best Practices.

Für einen umfassenderen Vergleich zwischen Docker Model Runner und Ollama, vLLM, LocalAI und Cloud-Anbietern – einschließlich Kosten- und Infrastrukturkompromisse – siehe LLM Hosting: Lokal, Selbstgehostet & Cloud-Infrastruktur Verglichen.

liste der gemma modelle, die in docker model runner verfügbar sind

Installation

Docker Desktop

Aktivieren Sie Docker Model Runner über die GUI:

  1. Öffnen Sie Docker Desktop
  2. Gehen Sie zu Einstellungen → AI-Registerkarte
  3. Klicken Sie auf Docker Model Runner aktivieren
  4. Starten Sie Docker Desktop neu

/home/rg/prj/hugo-pers/content/post/2025/10/docker-model-runner-cheatsheet/docker-model-runner_w678.jpg docker model runner windows

Docker Engine (Linux)

Installieren Sie das Plugin-Paket:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker-model-plugin

# Fedora/RHEL
sudo dnf install docker-model-plugin

# Arch Linux
sudo pacman -S docker-model-plugin

Überprüfen Sie die Installation:

docker model --help

NVIDIA RTX-Unterstützung für Docker

Um LLMs auf der GPU anstelle der CPU laufen zu lassen, installieren Sie nvidia-container-toolkit:

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

danach können Sie Container mit --gpus all ausführen

docker run --rm --gpus all <image> <command>

überprüfen Sie, ob der Container die GPU sieht:

docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubi8 nvidia-smi

NVIDIA-Unterstützung für Docker Model Runner hinzufügen

Docker Model Runner erfordert eine explizite GPU-Konfiguration. Im Gegensatz zu Standard-docker run-Befehlen unterstützt docker model run keine --gpus- oder -e-Flags. Stattdessen müssen Sie:

  1. Docker-Daemon so konfigurieren, dass er standardmäßig den NVIDIA-Runzeitraum verwendet

Zuerst prüfen Sie, wo nvidia-container-runtime installiert ist:

which nvidia-container-runtime

Dies gibt in der Regel /usr/bin/nvidia-container-runtime aus. Verwenden Sie diesen Pfad in der untenstehenden Konfiguration.

Erstellen oder aktualisieren Sie /etc/docker/daemon.json:

sudo tee /etc/docker/daemon.json > /dev/null << 'EOF'
{
  "default-runtime": "nvidia",
  "runtimes": {
    "nvidia": {
      "path": "/usr/bin/nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}
EOF

Hinweis: Wenn which nvidia-container-runtime einen anderen Pfad zurückgibt, aktualisieren Sie den "path"-Wert in der JSON-Konfiguration entsprechend.

Starten Sie Docker neu:

sudo systemctl restart docker

Überprüfen Sie die Konfiguration:

docker info | grep -i runtime

Sie sollten in der Ausgabe Default Runtime: nvidia sehen.

  1. Docker Model Runner mit GPU-Unterstützung erneut installieren

Docker Model Runner muss mit expliziter GPU-Unterstützung installiert/erneut installiert werden:

# Aktuellen Runner stoppen
docker model stop-runner

# Erneut installieren mit CUDA-GPU-Unterstützung
docker model reinstall-runner --gpu cuda

Dies wird die CUDA-fähige Version (docker/model-runner:latest-cuda) anstelle der CPU-only-Version herunterladen.

  1. GPU-Zugriff überprüfen

Überprüfen Sie, ob der Docker Model Runner-Container die GPU nutzen kann:

docker exec docker-model-runner nvidia-smi
  1. Modell mit GPU testen

Führen Sie ein Modell aus und prüfen Sie die Protokolle, um die GPU-Nutzung zu bestätigen:

docker model run ai/qwen3:14B-Q6_K "who are you?"

Überprüfen Sie die Protokolle auf GPU-Bestätigung:

docker model logs | grep -i cuda

Sie sollten Nachrichten wie:

  • using device CUDA0 (NVIDIA GeForce RTX 4080)
  • offloaded 41/41 layers to GPU
  • CUDA0 model buffer size = 10946.13 MiB

Hinweis: Wenn Sie Docker Model Runner bereits ohne GPU-Unterstützung installiert haben, müssen Sie es erneut mit dem --gpu cuda-Flag installieren. Die Konfiguration des Docker-Daemons allein reicht nicht aus – der Runner-Container selbst muss die CUDA-fähige Version sein.

Verfügbare GPU-Backends:

  • cuda - NVIDIA CUDA (häufigste)
  • rocm - AMD ROCm
  • musa - Moore Threads MUSA
  • cann - Huawei CANN
  • auto - Automatische Erkennung (Standard)
  • none - Nur CPU

Kernkommandos

Modelle herunterladen

Von Docker Hub vorgefertigte Modelle herunterladen:

# Grundlegender Pull
docker model pull ai/llama2

# Bestimmte Version pullen
docker model pull ai/llama2:7b-q4

# Aus einem benutzerdefinierten Registry pullen
docker model pull myregistry.com/models/mistral:latest

# Verfügbare Modelle in einem Namespace auflisten
docker search ai/

Modelle ausführen

Starten Sie ein Modell mit automatischer API-Bereitstellung:

# Grundlegender Start (interaktiv)
docker model run ai/llama2 "Was ist Docker?"

# Als Dienst starten (Hintergrund)
docker model run -d

overall haben wir nicht viele Optionen, um Modelle über die CLI zu starten:

docker model run --help
Usage:  docker model run MODEL [PROMPT]

Ein Modell ausführen und mit einem eingegebenen Prompt oder Chat-Modus interagieren

Optionen:
      --color string                  Farbige Ausgabe verwenden (auto|yes|no) (Standard: "auto")
      --debug                         Debug-Protokollierung aktivieren
  -d, --detach                        Modell im Hintergrund laden, ohne Interaktion
      --ignore-runtime-memory-check   Nicht blockieren, wenn geschätzter Laufzeit-Speicher für das Modell die Systemressourcen überschreitet.

Modelle auflisten

Zeigen Sie heruntergeladene und laufende Modelle an:

# Alle heruntergeladenen Modelle auflisten
docker model ls

# Laufende Modelle auflisten
docker model ps

# Mit detaillierten Informationen auflisten
docker model ls --json

# Mit detaillierten Informationen auflisten
docker model ls --openai

# Gibt nur Hashcodes zurück
docker model ls -q

Modelle entfernen

Löschen Sie Modelle aus der lokalen Speicherung:

# Bestimmtes Modell entfernen
docker model rm ai/llama2

# Mit Gewalt entfernen (auch wenn es läuft)
docker model rm -f ai/llama2

# Nicht verwendete Modelle entfernen
docker model prune

# Alle Modelle entfernen
docker model rm $(docker model ls -q)

Konfigurieren der Modellkontextgrößen

Wir können die CLI nicht verwenden, um die Kontextgröße für einen bestimmten Antrag zu spezifizieren.

Grundlegend können wir die Modellkontextgröße nur auf drei Arten steuern:

  1. Verpacken Sie das Modell selbst, indem Sie die gewünschte hartcodierte Kontextgröße angeben (siehe den nächsten Abschnitt für weitere Informationen.)

  2. Wenn Sie den docker model runner konfigurieren, verwenden Sie den –context-size-Parameter wie folgt:

docker model configure --context-size=10000 ai/gemma3-qat:4B

Dann können Sie curl verwenden, aber nicht docker moder run... - dieser ignoriert die Konfiguration.

  1. In der docker-compose.yaml-Datei, aber wir können die docker-model-runner-Image nicht auf diese Weise verwenden, weil es eine hartcodierte Kontextgröße von 4096 an das Modell übergibt
...
models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240
...

Weitere Details finden Sie in einem separaten Beitrag zu diesem Thema: Spezifizieren der Kontextgröße in DMR

Verpacken benutzerdefinierter Modelle

Aus GGUF ein OCI-Artifact erstellen

Verpacken Sie Ihre eigenen GGUF-Modelle:

# Grundlegende Verpackung
docker model package --gguf /path/to/model.gguf myorg/mymodel:latest

# Verpacken mit Metadaten
docker model package \
  --gguf /path/to/model.gguf \
  --label "description=Benutzerdefiniertes Llama-Modell" \
  --label "version=1.0" \
  myorg/mymodel:v1.0

# Verpacken und pushen in einem Befehl
docker model package --gguf /path/to/model.gguf --push myorg/mymodel:latest

# Verpacken mit benutzerdefinierter Kontextgröße
docker model package \
  --gguf /path/to/model.gguf \
  --context 8192 \
  myorg/mymodel:latest

Modelle veröffentlichen

Modelle an Registries pushen:

# Anmeldung bei Docker Hub
docker login

# An Docker Hub pushen
docker model push myorg/mymodel:latest

# An privates Registry pushen
docker login myregistry.com
docker model push myregistry.com/models/mymodel:latest

# Taggen und pushen
docker model tag mymodel:latest myorg/mymodel:v1.0
docker model push myorg/mymodel:v1.0

API-Nutzung

OpenAI-kompatible Endpunkte

Docker Model Runner macht automatisch OpenAI-kompatible APIs verfügbar:

# Modell mit API starten
docker model run -d -p 8080:8080 --name llm ai/llama2

# Chat-Vervollständigung
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Hallo!"}]
  }'

# Textgenerierung
curl http://localhost:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "prompt": "Einmal war es",
    "max_tokens": 100
  }'

# Streaming-Antwort
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Erzähle eine Geschichte"}],
    "stream": true
  }'

# Verfügbare Modelle über API auflisten
curl http://localhost:8080/v1/models

# Modellinformationen
curl http://localhost:8080/v1/models/llama2

Docker Compose-Konfiguration

Grundlegendes Compose-File

version: '3.8'

services:
  llm:
    image: docker-model-runner
    model: ai/llama2:7b-q4
    ports:
      - "8080:8080"
    environment:
      - MODEL_TEMPERATURE=0.7
    volumes:
      - docker-model-runner-models:/models
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  docker-model-runner-models:
    external: true

Mehrmodell-Setup

version: '3.8'

services:
  llama:
    image: docker-model-runner
    model: ai/llama2
    ports:
      - "8080:8080"
    
  mistral:
    image: docker-model-runner
    model: ai/mistral
    ports:
      - "8081:8080"
    
  embedding:
    image: docker-model-runner
    model: ai/nomic-embed-text
    ports:
      - "8082:8080"

Für fortgeschrittene Docker Compose-Konfigurationen und Befehle siehe unsere Docker Compose Cheatsheet zu Netzwerken, Volumes und Orchestrierungsmustern.

Umgebungsvariablen

Konfigurieren Sie das Verhalten des Modells mit Umgebungsvariablen:

# Temperatur (0,0-1,0)
MODEL_TEMPERATURE=0,7

# Top-p-Abtastung
MODEL_TOP_P=0,9

# Top-k-Abtastung
MODEL_TOP_K=40

# Maximale Tokenanzahl
MODEL_MAX_TOKENS=2048

# Anzahl der GPU-Schichten
MODEL_GPU_LAYERS=35

# Batchgröße
MODEL_BATCH_SIZE=512

# Threadanzahl (CPU)
MODEL_THREADS=8

# Ausführliche Protokollierung aktivieren
MODEL_VERBOSE=true

# API-Schlüssel für Authentifizierung
MODEL_API_KEY=your-secret-key

Starten Sie mit Umgebungsvariablen:

docker model run \
  -e MODEL_TEMPERATURE=0,8 \
  -e MODEL_API_KEY=secret123 \
  ai/llama2

GPU-Konfiguration

Automatische GPU-Erkennung

DMR erkennt und nutzt automatisch verfügbare GPUs:

# Alle GPUs verwenden
docker model run --gpus all ai/llama2

# Bestimmte GPU verwenden
docker model run --gpus 0 ai/llama2

# Mehrere spezifische GPUs verwenden
docker model run --gpus 0,1,2 ai/llama2

# GPU mit Speicherlimit
docker model run --gpus all --memory 16g ai/llama2

Nur CPU-Modus

Erzwingen Sie CPU-Verarbeitung, wenn eine GPU verfügbar ist:

docker model run --no-gpu ai/llama2

Multi-GPU-Tensorparallellität

Verteilen Sie große Modelle auf mehrere GPUs:

docker model run \
  --gpus all \
  --tensor-parallel 2 \
  ai/llama2-70b

Inspektion und Debuggen

Modellinformationen anzeigen

# Modellkonfiguration inspizieren
docker model inspect ai/llama2

# Modellschichten anzeigen
docker model history ai/llama2

# Modellgröße und Metadaten prüfen
docker model inspect --format='{{.Size}}' ai/llama2

Protokolle und Überwachung

# Modellprotokolle anzeigen
docker model logs llm

# Protokolle in Echtzeit verfolgen
docker model logs -f llm

# Letzte 100 Zeilen anzeigen
docker model logs --tail 100 llm

# Protokolle mit Zeitstempeln anzeigen
docker model logs -t llm

Leistungsstatistiken

# Ressourcennutzung
docker model stats

# Statistiken für ein bestimmtes Modell
docker model stats llm

# Statistiken im JSON-Format
docker model stats --format json

Netzwerk

APIs freigeben

# Standardport (8080)
docker model run -p 8080:8080 ai/llama2

# Benutzerdefinierter Port
docker model run -p 3000:8080 ai/llama2

# An bestimmtes Interface binden
docker model run -p 127.0.0.1:8080:8080 ai/llama2

# Mehrere Ports
docker model run -p 8080:8080 -p 9090:9090 ai/llama2

Netzwerkkonfiguration

# Benutzerdefiniertes Netzwerk erstellen
docker network create llm-network

# Modell auf benutzerdefiniertem Netzwerk ausführen
docker model run --network llm-network --name llm ai/llama2

# Zu bestehendem Netzwerk verbinden
docker model run --network host ai/llama2

Sicherheit

Zugriffssteuerung

# Mit API-Schlüsselauthentifizierung starten
docker model run \
  -e MODEL_API_KEY=my-secret-key \
  ai/llama2

# Mit Authentifizierung verwenden
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama2", "messages": [...]}'

Registry-Authentifizierung

# An privates Registry anmelden
docker login myregistry.com -u username -p password

# Aus privater Registry pullen
docker model pull myregistry.com/private/model:latest

# Mit Credentials Helper verwenden
docker login --password-stdin < token.txt

Best Practices

Modellauswahl

# Verwenden Sie quantisierte Modelle für schnellere Inferenz
docker model pull ai/llama2:7b-q4     # 4-Bit Quantisierung
docker model pull ai/llama2:7b-q5     # 5-Bit Quantisierung
docker model pull ai/llama2:7b-q8     # 8-Bit Quantisierung

# Prüfen Sie Modellvarianten
docker search ai/llama2

Ressourcenverwaltung

# Speicherlimits setzen
docker model run --memory 8g --memory-swap 16g ai/llama2

# CPU-Limits setzen
docker model run --cpus 4 ai/llama2

# GPU-Speicherlimit setzen
docker model run --gpus all --gpu-memory 8g ai/llama2

Gesundheitschecks

# Mit Gesundheitscheck starten
docker model run \
  --health-cmd "curl -f http://localhost:8080/health || exit 1" \
  --health-interval 30s \
  --health-timeout 10s \
  --health-retries 3 \
  ai/llama2

Produktionsorchestrierung

Für Produktionsbereitstellungen mit Kubernetes können Docker Model Runner-Container mit standardmäßigen Kubernetes-Manifesten orchestriert werden. Definieren Sie Bereitstellungen mit Ressourcenlimits, Automatisierung und Lastverteilung. Für umfassende Kubernetes-Befehlsreferenzen und Bereitstellungsmuster prüfen Sie unsere Kubernetes Cheatsheet.

# Beispiel: Bereitstellung in Kubernetes-Cluster
kubectl apply -f llm-deployment.yaml

# Skalierung der Bereitstellung
kubectl scale deployment llm --replicas=3

# Als Dienst exponieren
kubectl expose deployment llm --type=LoadBalancer --port=8080

Problembehandlung

Häufige Probleme

Modell startet nicht:

# Verfügbaren Speicherplatz prüfen
df -h

# Detaillierte Fehlerprotokolle anzeigen
docker model logs --tail 50 llm

# GPU-Verfügbarkeit prüfen
nvidia-smi  # Für NVIDIA-GPUs

Ausnahmen aufgrund von Speicherproblemen:

# Verwenden Sie ein kleineres quantisiertes Modell
docker model pull ai/llama2:7b-q4

# Kontextgröße verringern
docker model run -e MODEL_CONTEXT=2048 ai/llama2

# Batchgröße verringern
docker model run -e MODEL_BATCH_SIZE=256 ai/llama2

Langsame Inferenz:

# GPU-Nutzung prüfen
docker model stats llm

# Sicherstellen, dass die GPU genutzt wird
docker model logs llm | grep -i gpu

# Anzahl der GPU-Schichten erhöhen
docker model run -e MODEL_GPU_LAYERS=40 ai/llama2

Diagnosebefehle

# Systeminformationen
docker model system info

# Speicherverwendung
docker model system df

# Unbenutzte Ressourcen bereinigen
docker model system prune

# Vollständige Bereinigung (alle Modelle entfernen)
docker model system prune -a

Integrationssbeispiele

Python-Integration

import openai

# Client für Docker Model Runner konfigurieren
client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # DMR erfordert standardmäßig keinen Schlüssel
)

# Chat-Vervollständigung
response = client.chat.completions.create(
    model="llama2",
    messages=[
        {"role": "user", "content": "Hallo!"}
    ]
)

print(response.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="llama2",
    messages=[{"role": "user", "content": "Erzähle eine Geschichte"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Bash-Script

#!/bin/bash

# Modell starten, wenn es nicht läuft
if ! docker model ps | grep -q "llm"; then
    docker model run -d --name llm -p 8080:8080 ai/llama2
    echo "Warte, bis das Modell gestartet ist..."
    sleep 10
fi

# API-Aufruf
curl -s http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "'"$1"'"}]
  }' | jq -r '.choices[0].message.content'

Node.js-Integration

import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'http://localhost:8080/v1',
    apiKey: 'not-needed'
});

async function chat(message) {
    const completion = await client.chat.completions.create({
        model: 'llama2',
        messages: [{ role: 'user', content: message }]
    });
    
    return completion.choices[0].message.content;
}

// Verwendung
const response = await chat('Was ist Docker Model Runner?');
console.log(response);

Um zu sehen, wie Docker Model Runner mit Ollama, vLLM, LocalAI und Cloud-Anbietern zusammenpasst, prüfen Sie unsere LLM Hosting: Lokal, Selbstgehostet & Cloud-Infrastruktur Verglichen-Anleitung.

Offizielle Dokumentation

Verwandte Artikel