Docker Model Runner Cheatsheet: Opdrachten & Voorbeelden

Snelle verwijzing naar Docker Model Runner-opdrachten

Docker Model Runner (DMR) is de officiële oplossing van Docker voor het lokaal uitvoeren van AI-modellen, geïntroduceerd in april 2025. Deze cheatsheet biedt een snelle verwijzing naar alle essentiële opdrachten, configuraties en best practices.

lijst van gemma modellen beschikbaar in docker model runner

Installatie

Docker Desktop

Schakel Docker Model Runner in via het GUI:

  1. Open Docker Desktop
  2. Ga naar Instellingen → AI tab
  3. Klik op Docker Model Runner inschakelen
  4. Herstart Docker Desktop

/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)

Installeer het pluginpakket:

# 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

Controleer de installatie:

docker model --help

NVIDIA RTX-ondersteuning voor Docker

Om te laten werken met GPU in plaats van CPU, installeer 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

Daarna kun je containers uitvoeren met --gpus all

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

Controleer of de container de GPU kan zien:

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

Toevoegen van NVidia-ondersteuning voor Docker Model Runner

Docker Model Runner vereist expliciete GPU-configuratie. In tegenstelling tot standaard docker run-opdrachten, ondersteunt docker model run geen --gpus of -e-vlaggen. In plaats daarvan moet je:

  1. Configureren van Docker-daemon om standaard NVIDIA-runtime te gebruiken

Controleer eerst waar nvidia-container-runtime is geïnstalleerd:

which nvidia-container-runtime

Dit geeft meestal /usr/bin/nvidia-container-runtime als uitvoer. Gebruik deze pad in de configuratie hieronder.

Maak of update /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

Opmerking: Als which nvidia-container-runtime een ander pad retourneert, pas dan de "path"-waarde in de JSON-configuratie daarop aan.

Herstart Docker:

sudo systemctl restart docker

Controleer de configuratie:

docker info | grep -i runtime

Je moet Default Runtime: nvidia in de uitvoer zien.

  1. Herinstalleer Docker Model Runner met GPU-ondersteuning

Docker Model Runner moet worden geïnstalleerd/hergeïnstalleerd met expliciete GPU-ondersteuning:

# Huidige runner stoppen
docker model stop-runner

# Herinstalleer met CUDA GPU-ondersteuning
docker model reinstall-runner --gpu cuda

Dit zal de CUDA-geenablede versie (docker/model-runner:latest-cuda) ophalen in plaats van de CPU-only-versie.

  1. Controleer GPU-toegang

Controleer of de Docker Model Runner-container toegang heeft tot de GPU:

docker exec docker-model-runner nvidia-smi
  1. Test model met GPU

Voer een model uit en controleer de logboeken om GPU-gebruik te bevestigen:

docker model run ai/qwen3:14B-Q6_K "wie ben jij?"

Controleer de logboeken voor GPU-bevestiging:

docker model logs | grep -i cuda

Je moet berichten zoals:

  • gebruik apparaat CUDA0 (NVIDIA GeForce RTX 4080)
  • uitgelost 41/41 lagen naar GPU
  • CUDA0 model buffer grootte = 10946,13 MiB

Opmerking: Als je Docker Model Runner al hebt geïnstalleerd zonder GPU-ondersteuning, moet je het opnieuw installeren met de --gpu cuda-vlag. Alleen het configureren van de Docker-daemon is niet voldoende - de runner-container zelf moet de CUDA-geenablede versie zijn.

Beschikbare GPU-backends:

  • cuda - NVIDIA CUDA (meest voorkomend)
  • rocm - AMD ROCm
  • musa - Moore Threads MUSA
  • cann - Huawei CANN
  • auto - Automatische detectie (standaard)
  • none - Alleen CPU

Kernopdrachten

Modellen ophalen

Ophalen van voorverpakte modellen van Docker Hub:

# Basis ophalen
docker model pull ai/llama2

# Ophalen van specifieke versie
docker model pull ai/llama2:7b-q4

# Ophalen van aangepaste register
docker model pull myregistry.com/models/mistral:latest

# Lijst beschikbare modellen in een namespace
docker search ai/

Modellen uitvoeren

Start een model met automatische API-serveerfunctie:

# Basis uitvoeren (interactief)
docker model run ai/llama2 "Wat is Docker?"

# Uitvoeren als service (achtergrond)
docker model run -d

over het algemeen hebben we niet veel opties met het uitvoeren van modellen via CLI:

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

Een model uitvoeren en ermee interacteren met een ingediende prompt of chatmodus

Opties:
      --color string                  Gebruik gekleurde uitvoer (auto|yes|no) (standaard "auto")
      --debug                         Debuglogboekregistratie inschakelen
  -d, --detach                        Model laden in de achtergrond zonder interactie
      --ignore-runtime-memory-check   Blokkeer ophalen niet als geschatte runtime-geheugen voor model overschrijdt systeemresources.

Modellen tonen

Bekijk gedownloade en lopende modellen:

# Lijst met alle gedownloade modellen
docker model ls

# Lijst met lopende modellen
docker model ps

# Lijst met gedetailleerde informatie
docker model ls --json

# Lijst met gedetailleerde informatie
docker model ls --openai

# Geeft hashcodes terug
docker model ls -q

Modellen verwijderen

Verwijder modellen van lokale opslag:

# Verwijder specifiek model
docker model rm ai/llama2

# Verwijder met kracht (zelfs als het loopt)
docker model rm -f ai/llama2

# Verwijder ongebruikte modellen
docker model prune

# Verwijder alle modellen
docker model rm $(docker model ls -q)

Configureren van Model Contextgrootte

We kunnen de CLI niet gebruiken om de contextgrootte voor een specifieke aanvraag op te geven.

Bijna altijd kunnen we de contextgrootte van het model alleen op drie manieren beïnvloeden:

  1. Pak het model zelf, en specificeer de gewenste hardcoded contextgrootte (Zie hieronder voor meer informatie over dit onderwerp.)

  2. Wanneer u docker model runner configureeropdracht gebruikt met –context-size parameter zoals

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

Dan kunt u curl gebruiken om erop te roepen, maar u kunt niet doen docker moder run... - die zal de configure negeren.

  1. In docker-compose.yaml bestand, maar we kunnen niet op deze manier docker-model-runner afbeelding gebruiken, omdat het een hardcoded contextgrootte van 4096 doorgeeft aan het model
...
models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240
...

Voor meer details zie het gerelateerde artikel hierover: Specifieren van contextgrootte in DMR

Aangepaste modellen verpakken

Maak een OCI-artefact van GGUF

Pak uw eigen GGUF-modellen:

# Basisverpakking
docker model package --gguf /pad/naar/model.gguf myorg/mymodel:latest

# Verpakken met metadata
docker model package \
  --gguf /pad/naar/model.gguf \
  --label "beschrijving=Aangepast Llama model" \
  --label "versie=1.0" \
  myorg/mymodel:v1.0

# Verpakken en pushen in één opdracht
docker model package --gguf /pad/naar/model.gguf --push myorg/mymodel:latest

# Verpakken met aangepaste contextgrootte
docker model package \
  --gguf /pad/naar/model.gguf \
  --context 8192 \
  myorg/mymodel:latest

Modellen publiceren

Push modellen naar registers:

# Aanmelden bij Docker Hub
docker login

# Push naar Docker Hub
docker model push myorg/mymodel:latest

# Push naar privé register
docker login myregistry.com
docker model push myregistry.com/models/mymodel:latest

# Tag en push
docker model tag mymodel:latest myorg/mymodel:v1.0
docker model push myorg/mymodel:v1.0

API-gebruik

OpenAI-compatibele eindpunten

Docker Model Runner maakt automatisch OpenAI-compatibele API’s beschikbaar:

# Start model met API
docker model run -d -p 8080:8080 --name llm ai/llama2

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

# Tekstgeneratie
curl http://localhost:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "prompt": "Er was eens",
    "max_tokens": 100
  }'

# Streaming reactie
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Vertel me een verhaal"}],
    "stream": true
  }'

# Beschikbare modellen via API lijsten
curl http://localhost:8080/v1/models

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

Docker Compose configuratie

Basis Compose-bestand

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-model 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"

Voor geavanceerde Docker Compose configuraties en opdrachten, zie onze Docker Compose Cheatsheet die netwerken, volumes en orchestratiepatronen behandelt.

Omgevingsvariabelen

Stel modelgedrag in met omgevingsvariabelen:

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

# Top-p sampling
MODEL_TOP_P=0,9

# Top-k sampling
MODEL_TOP_K=40

# Maximaal aantal tokens
MODEL_MAX_TOKENS=2048

# Aantal GPU-lagen
MODEL_GPU_LAYERS=35

# Batchgrootte
MODEL_BATCH_SIZE=512

# Threadtelling (CPU)
MODEL_THREADS=8

# Actieve logboekregistratie inschakelen
MODEL_VERBOSE=true

# API-sleutel voor authenticatie
MODEL_API_KEY=your-secret-key

Voer uit met omgevingsvariabelen:

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

GPU-configuratie

Automatische GPU-detectie

DMR detecteert automatisch beschikbare GPUs en gebruikt ze:

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

# Gebruik specifieke GPU
docker model run --gpus 0 ai/llama2

# Gebruik meerdere specifieke GPUs
docker model run --gpus 0,1,2 ai/llama2

# GPU met geheugenlimiet
docker model run --gpus all --memory 16g ai/llama2

Alleen CPU-modus

Forceer CPU-inferentie wanneer GPU beschikbaar is:

docker model run --no-gpu ai/llama2

Multi-GPU Tensorparallelisme

Verdeel grote modellen over meerdere GPUs:

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

Inspectie en foutopsporing

Modeldetails bekijken

# Modelconfiguratie inspecteren
docker model inspect ai/llama2

# Modellagen bekijken
docker model history ai/llama2

# Modelgrootte en metadata controleren
docker model inspect --format='{{.Size}}' ai/llama2

Logboeken en monitoring

# Modellogboeken bekijken
docker model logs llm

# Logboeken in real-time volgen
docker model logs -f llm

# Laatste 100 regels bekijken
docker model logs --tail 100 llm

# Logboeken met tijdstempels bekijken
docker model logs -t llm

Prestatie statistieken

# Resourcegebruik
docker model stats

# Specifieke modelstatistieken
docker model stats llm

# Statistieken in JSON-formaat
docker model stats --format json

Netwerken

APIs blootstellen

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

# Aangepaste poort
docker model run -p 3000:8080 ai/llama2

# Bind aan specifieke interface
docker model run -p 127.0.0.1:8080:8080 ai/llama2

# Meerdere poorten
docker model run -p 8080:8080 -p 9090:9090 ai/llama2

Netwerkconfiguratie

# Aangepast netwerk aanmaken
docker network create llm-netwerk

# Model op aangepast netwerk uitvoeren
docker model run --network llm-netwerk --name llm ai/llama2

# Aan bestaand netwerk verbinden
docker model run --network host ai/llama2

Beveiliging

Toegangscontrole

# Uitvoeren met API-sleutel authenticatie
docker model run \
  -e MODEL_API_KEY=my-secret-key \
  ai/llama2

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

Register authenticatie

# Aanmelden bij privé register
docker login myregistry.com -u username -p password

# Ophalen van privé register
docker model pull myregistry.com/private/model:latest

# Gebruik credentials helper
docker login --password-stdin < token.txt

Best practices

Modelselectie

# Gebruik gecomprimeerde modellen voor snellere inferentie
docker model pull ai/llama2:7b-q4     # 4-bit compressie
docker model pull ai/llama2:7b-q5     # 5-bit compressie
docker model pull ai/llama2:7b-q8     # 8-bit compressie

# Controleer modelvarianten
docker search ai/llama2

Resourcebeheer

# Stel geheugenlimieten in
docker model run --memory 8g --memory-swap 16g ai/llama2

# Stel CPU-limieten in
docker model run --cpus 4 ai/llama2

# Beperk GPU-geheugen
docker model run --gpus all --gpu-memory 8g ai/llama2

Gezondheidstests

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

Productieorchestratie

Voor productiedeployments met Kubernetes, kunnen Docker Model Runner-containers worden georchestratiseerd met standaard Kubernetes-manifesten. Definieer implementaties met resourcebeperkingen, automatische schaling en loadbalancing. Voor een uitgebreide Kubernetes-opdrachtreferentie en implementatiepatronen, zie onze Kubernetes Cheatsheet.

# Voorbeeld: Implementeer in Kubernetes cluster
kubectl apply -f llm-deployment.yaml

# Schaal implementatie
kubectl scale deployment llm --replicas=3

# Expose als service
kubectl expose deployment llm --type=LoadBalancer --port=8080

Probleemoplossing

Algemene problemen

Model start niet:

# Controleer beschikbare schijfruimte
df -h

# Bekijk gedetailleerde foutlogboeken
docker model logs --tail 50 llm

# Controleer GPU-beschikbaarheid
nvidia-smi  # Voor NVIDIA GPUs

Geheugenfouten:

# Gebruik een kleinere gecomprimeerde model
docker model pull ai/llama2:7b-q4

# Verminder contextgrootte
docker model run -e MODEL_CONTEXT=2048 ai/llama2

# Beperk batchgrootte
docker model run -e MODEL_BATCH_SIZE=256 ai/llama2

Slechte inferentie:

# Controleer GPU-gebruik
docker model stats llm

# Zorg ervoor dat GPU wordt gebruikt
docker model logs llm | grep -i gpu

# Verhoog GPU-lagen
docker model run -e MODEL_GPU_LAYERS=40 ai/llama2

Diagnostische opdrachten

# Systeeminformatie
docker model system info

# Schijfgebruik
docker model system df

# Reinig ongebruikte resources
docker model system prune

# Volledige reiniging (verwijder alle modellen)
docker model system prune -a

Integratievoorbeelden

Python-integratie

import openai

# Configureer client voor Docker Model Runner
client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # DMR vereist geen sleutel standaard
)

# Chatvoltooiing
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": "Vertel me een verhaal"}],
    stream=True
)

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

Bash-script

#!/bin/bash

# Start model als het niet loopt
if ! docker model ps | grep -q "llm"; then
    docker model run -d --name llm -p 8080:8080 ai/llama2
    echo "Wachten tot model is gestart..."
    sleep 10
fi

# Maak API-aanroep
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-integratie

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;
}

// Gebruik
const response = await chat('Wat is Docker Model Runner?');
console.log(response);

Officiële documentatie

Gerelateerde cheatsheets

Vergelijkende artikelen