Docker Model Runner Cheatsheet: Befehle & Beispiele

Schnelle Referenz für Docker Model Runner-Befehle

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

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 → KI-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

Installation überprüfen:

docker model --help

NVIDIA RTX-Unterstützung für Docker

Um sicherzustellen, dass LLMs auf der GPU statt auf der CPU laufen, 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

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

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

Überprüfen Sie, ob der Container die GPU erkennen kann:

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

Hinzufügen der NVidia-Unterstützung für Docker Model Runner

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. Konfigurieren Sie den Docker-Daemon für die Verwendung des NVIDIA-Runtime-Standards

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

which nvidia-container-runtime

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

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 Wert "path" 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 Default Runtime: nvidia in der Ausgabe sehen.

  1. Installieren Sie Docker Model Runner mit GPU-Unterstützung neu

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

# Stoppen Sie den aktuellen Runner
docker model stop-runner

# Neu 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. Überprüfen Sie den GPU-Zugriff

Stellen Sie sicher, dass der Docker Model Runner-Container auf die GPU zugreifen kann:

docker exec docker-model-runner nvidia-smi
  1. Testen Sie das Modell mit GPU

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

docker model run ai/qwen3:14B-Q6_K "Wer bist du?"

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

docker model logs | grep -i cuda

Sie sollten Nachrichten wie diese sehen:

  • 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 mit dem --gpu cuda-Flag neu 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 (am häufigsten verwendet)
  • rocm - AMD ROCm
  • musa - Moore Threads MUSA
  • cann - Huawei CANN
  • auto - Automatische Erkennung (Standard)
  • none - CPU-Only

Kernbefehle

Modelle herunterladen

Laden Sie vorkonfigurierte Modelle von Docker Hub herunter:

# Grundlegendes Herunterladen
docker model pull ai/llama2

# Spezifische Version herunterladen
docker model pull ai/llama2:7b-q4

# Von einem benutzerdefinierten Registry herunterladen
docker model pull myregistry.com/models/mistral:latest

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

Modelle ausführen

Starten Sie ein Modell mit automatischer API-Bereitstellung:

# Grundlegendes Ausführen (interaktiv)
docker model run ai/llama2 "Was ist Docker?"

# Als Dienst ausführen (Hintergrund)
docker model run -d

Insgesamt haben wir nicht viele Optionen beim Ausführen von Modellen über die CLI:

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

Führen Sie ein Modell aus und interagieren Sie damit unter Verwendung eines übermittelten Prompts oder Chat-Modus

Optionen:
      --color string                  Verwenden Sie farbige Ausgabe (auto|yes|no) (Standardwert "auto")
      --debug                         Aktivieren Sie Debug-Protokollierung
  -d, --detach                        Laden Sie das Modell im Hintergrund ohne Interaktion
      --ignore-runtime-memory-check   Blockieren Sie nicht das Herunterladen, wenn der geschätzte Speicherbedarf des Modells für die Laufzeit die Systemressourcen überschreitet.

Modelle auflisten

Angezeigte heruntergeladene und ausgeführte Modelle:

# Alle heruntergeladenen Modelle auflisten
docker model ls

# Ausgeführte 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 dem lokalen Speicher:

# Spezifisches Modell entfernen
docker model rm ai/llama2

# Mit Zwang entfernen (auch wenn ausgeführt)
docker model rm -f ai/llama2

# Nicht verwendete Modelle entfernen
docker model prune

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

Konfigurieren von Modellkontextgrößen

Wir können die CLI nicht verwenden, um die Kontextgröße für eine bestimmte Anfrage zu spezifizieren.

Grundsätzlich können wir die Modellkontextgröße nur auf drei Arten steuern:

  1. Packen Sie das Modell selbst, indem Sie die gewünschte festgelegte Kontextgröße angeben (Weitere Informationen dazu finden Sie im nächsten Abschnitt).

  2. Verwenden Sie den docker model runner configure-Befehl mit dem Parameter --context-size wie folgt:

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

Dann können Sie curl darauf aufrufen, aber Sie können nicht docker moder run... ausführen - dieser wird die Konfiguration ignorieren.

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

Für weitere Details siehe den dedizierten Beitrag dazu: Angeben der Kontextgröße in DMR

Packen von benutzerdefinierten Modellen

Erstellen eines OCI-Artifacts aus GGUF

Packen Sie Ihre eigenen GGUF-Modelle:

# Grundlegendes Packen
docker model package --gguf /path/to/model.gguf myorg/mymodel:latest

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

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

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

Veröffentlichen von Modellen

Laden Sie Modelle in Registries hoch:

# Anmelden bei Docker Hub
docker login

# Hochladen auf Docker Hub
docker model push myorg/mymodel:latest

# Hochladen auf privates Registry
docker login myregistry.com
docker model push myregistry.com/models/mymodel:latest

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

API-Nutzung

OpenAI-kompatible Endpunkte

Docker Model Runner stellt automatisch OpenAI-kompatible APIs bereit:

# Starten Sie das Modell mit API
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": "Es war einmal",
    "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ähl mir eine Geschichte"}],
    "stream": true
  }'

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

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

Docker Compose-Konfiguration

Grundlegende Compose-Datei

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

Multi-Modell-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 erweiterte Docker Compose-Konfigurationen und -Befehle siehe unser Docker Compose Cheatsheet, das Netzwerk, Volumes und Orchestrierungsmuster abdeckt.

Umgebungsvariablen

Konfigurieren Sie das Modellverhalten mit Umgebungsvariablen:

# Temperatur (0.0-1.0)
MODEL_TEMPERATURE=0.7

# Top-p Sampling
MODEL_TOP_P=0.9

# Top-k Sampling
MODEL_TOP_K=40

# Maximale Tokens
MODEL_MAX_TOKENS=2048

# Anzahl der GPU-Layers
MODEL_GPU_LAYERS=35

# Batch-Größe
MODEL_BATCH_SIZE=512

# Thread-Zahl (CPU)
MODEL_THREADS=8

# Aktivieren Sie detaillierte Protokollierung
MODEL_VERBOSE=true

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

Ausführen mit Umgebungsvariablen:

docker model run \
  -e MODEL_TEMPERATURE=0.8 \
  -e MODEL_API_KEY=secret123 \
  ai/llama2

GPU-Konfiguration

Automatische GPU-Erkennung

DMR erkennt automatisch verfügbare GPUs und nutzt diese:

# Verwenden Sie alle GPUs
docker model run --gpus all ai/llama2

# Verwenden Sie eine bestimmte GPU
docker model run --gpus 0 ai/llama2

# Verwenden Sie mehrere bestimmte GPUs
docker model run --gpus 0,1,2 ai/llama2

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

CPU-Only-Modus

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

docker model run --no-gpu ai/llama2

Multi-GPU-Tensor-Parallelität

Verteilen Sie große Modelle über GPUs:

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

Inspektion und Fehlerbehebung

Anzeigen von Modelldetails

# Modellkonfiguration prüfen
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

# Spezifische Modellstatistiken
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

# Binden an eine bestimmte Schnittstelle
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

# Erstellen Sie ein benutzerdefiniertes Netzwerk
docker network create llm-network

# Führen Sie das Modell in einem benutzerdefinierten Netzwerk aus
docker model run --network llm-network --name llm ai/llama2

# Verbinden Sie sich mit einem bestehenden Netzwerk
docker model run --network host ai/llama2

Sicherheit

Zugriffskontrolle

# Ausführen mit API-Schlüssel-Authentifizierung
docker model run \
  -e MODEL_API_KEY=my-secret-key \
  ai/llama2

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

Registrierungsauthentifizierung

# Anmelden beim privaten Registrierungsdienst
docker login myregistry.com -u username -p password

# Herunterladen aus privatem Registrierungsdienst
docker model pull myregistry.com/private/model:latest

# Verwenden Sie den Anmeldeinformations-Helfer
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

# Modellvarianten prüfen
docker search ai/llama2

Ressourcenmanagement

# Speichergrenzen festlegen
docker model run --memory 8g --memory-swap 16g ai/llama2

# CPU-Grenzen festlegen
docker model run --cpus 4 ai/llama2

# GPU-Speicher begrenzen
docker model run --gpus all --gpu-memory 8g ai/llama2

Gesundheitsprüfungen

# Ausführen mit Gesundheitsprüfung
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 Standard-Kubernetes-Manifesten orchestriert werden. Definieren Sie Bereitstellungen mit Ressourcengrenzen, automatischer Skalierung und Lastverteilung. Für eine umfassende Kubernetes-Befehlsreferenz und Bereitstellungsmuster überprüfen Sie unseren Kubernetes Cheatsheet.

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

# Bereitstellung skalieren
kubectl scale deployment llm --replicas=3

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

Fehlerbehebung

Häufige Probleme

Modell startet nicht:

# Verfügbaren Festplattenspeicher prüfen
df -h

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

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

Speicherfehler:

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

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

# Batch-Größe begrenzen
docker model run -e MODEL_BATCH_SIZE=256 ai/llama2

Langsame Inferenz:

# GPU-Nutzung prüfen
docker model stats llm

# Stellen Sie sicher, dass die GPU verwendet wird
docker model logs llm | grep -i gpu

# Erhöhen Sie die GPU-Layers
docker model run -e MODEL_GPU_LAYERS=40 ai/llama2

Diagnosebefehle

# Systeminformationen
docker model system info

# Festplattennutzung
docker model system df

# Unbenutzte Ressourcen bereinigen
docker model system prune

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

Integrationsbeispiele

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ählen Sie mir eine Geschichte"}],
    stream=True
)

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

Bash-Skript

#!/bin/bash

# Starten Sie das Modell, 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 "Warten auf den Start des Modells..."
    sleep 10
fi

# API-Aufruf machen
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);

Offizielle Dokumentation

Verwandte Cheatsheets

Vergleichsartikel