Docker Model Runner Cheatsheet: Opdrachten & Voorbeelden

Snelle verwijzing naar Docker Model Runner-commands

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 beste praktijken.

Voor een breder vergelijk van Docker Model Runner met Ollama, vLLM, LocalAI en cloudproviders — inclusief kosten- en infrastructuurafwegingen — zie LLM Hosting: Lokale, Self-Hosted & Cloud Infrastructuur Vergelijk.

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 zien in de uitvoer.

  1. Herinstallatie van Docker Model Runner met GPU-ondersteuning

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

# Stop de huidige runner
docker model stop-runner

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

Dit haalt de CUDA-geëmde versie (docker/model-runner:latest-cuda) op 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 logbestanden om GPU-gebruik te bevestigen:

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

Controleer de logbestanden voor bevestiging van GPU:

docker model logs | grep -i cuda

Je moet berichten zien zoals:

  • gebruik apparaat CUDA0 (NVIDIA GeForce RTX 4080)
  • offgeladen 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-geëmde 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

Haal vooraf verpakte modellen op van Docker Hub:

# Basis ophalen
docker model pull ai/llama2

# Specifieke versie ophalen
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-ervaring:

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

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

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

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

Run a model and interact with it using a submitted prompt or chat mode

Options:
      --color string                  Use colored output (auto|yes|no) (default "auto")
      --debug                         Enable debug logging
  -d, --detach                        Load the model in the background without interaction
      --ignore-runtime-memory-check   Do not block pull if estimated runtime memory for model exceeds system resources.

Modellen lijsten

Bekijk gedownloade en actieve modellen:

# Lijst alle gedownloade modellen
docker model ls

# Lijst actieve 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 actief)
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 Contextgroottes

We kunnen niet via CLI een specifieke contextgrootte opgeven voor een bepaalde aanvraag.

In principe kan men de contextgrootte van het model alleen op drie manieren bepalen:

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

  2. Bij het gebruiken van docker model runner configureer opdracht met –context-size parameter zoals:

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

Dan kan je curl gebruiken om erop te roepen, maar je kunt niet docker model run... doen — diegene zal de configure negeren.

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

Voor meer details zie de specifieke post hierover: Specifieren van contextgrootte in DMR

Aanpassen van Aangepaste Modellen

Maak een OCI Artifact van GGUF

Pak je eigen GGUF-modellen:

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

# Verpak met metadata
docker model package \
  --gguf /path/to/model.gguf \
  --label "description=Aangepaste Llama model" \
  --label "version=1.0" \
  myorg/mymodel:v1.0

# Verpak en push in één opdracht
docker model package --gguf /path/to/model.gguf --push myorg/mymodel:latest

# Verpak met aangepaste contextgrootte
docker model package \
  --gguf /path/to/model.gguf \
  --context 8192 \
  myorg/mymodel:latest

Publiceren van modellen

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

# Chatcompletion
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
  }'

# Streamresponse
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
  }'

# Lijst beschikbare modellen via API
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 opstelling

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 orkestratiepatronen 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

# Activeren van gedetailleerde logboekregistratie
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 en gebruikt automatisch beschikbare GPUs:

# 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 Tensor Parallelisme

Verdeel grote modellen over meerdere GPUs:

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

Inspectie en Debuggen

Bekijk modeldetails

# Bekijk modelconfiguratie
docker model inspect ai/llama2

# Bekijk modellagen
docker model history ai/llama2

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

Logboeken en monitoring

# Bekijk modellogboeken
docker model logs llm

# Volg logboeken in real-time
docker model logs -f llm

# Bekijk laatste 100 regels
docker model logs --tail 100 llm

# Bekijk logboeken met tijdstempels
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

Exposeren van API’s

# 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

# Maak aangepast netwerk
docker network create llm-network

# Voer model uit op aangepast netwerk
docker model run --network llm-network --name llm ai/llama2

# Verbind met bestaand netwerk
docker model run --network host ai/llama2

Beveiliging

Toegangscontrole

# Voer uit met API-sleutelauthenticatie
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": [...]}'

Registry-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

Beste praktijken

Modelkeuze

# Gebruik gequantiseerde modellen voor snellere inferentie
docker model pull ai/llama2:7b-q4     # 4-bits quantisatie
docker model pull ai/llama2:7b-q5     # 5-bits quantisatie
docker model pull ai/llama2:7b-q8     # 8-bits quantisatie

# 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

# Voer uit 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

Productie-orkestratie

Voor productiedeployments met Kubernetes, kunnen Docker Model Runner-containers worden georkestratiseerd met standaard Kubernetes-manifesten. Definieer implementaties met resourcebeperkingen, automatisch schalen 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 kleinere gequantiseerde 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 dat GPU wordt gebruikt
docker model logs llm | grep -i gpu

# Verhoog aantal 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
)

# Chatcompletion
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 actief is
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);

Om te zien hoe Docker Model Runner past bij Ollama, vLLM, LocalAI en cloudproviders, zie onze LLM Hosting: Lokale, Self-Hosted & Cloud Infrastructuur Vergelijk gids.

Officiële documentatie

Gerelateerde artikelen