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 beschikbare gemma modellen in docker model runner

Installatie

Docker Desktop

Schakel Docker Model Runner in via het GUI:

  1. Open Docker Desktop
  2. Ga naar InstellingenAI 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 venster

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

Kernopdrachten

Modellen ophalen

Haal vooraf ingepakte modellen op van Docker Hub:

# Basis ophalen
docker model pull ai/llama2

# Specifieke versie ophalen
docker model pull ai/llama2:7b-q4

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

# Lijst beschikbare modellen in een naamruimte
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 --name my-llm ai/llama2

# Uitvoeren met aangepaste poort
docker model run -p 8080:8080 ai/llama2

# Uitvoeren met GPU-specificatie
docker model run --gpus 0,1 ai/llama2

# Uitvoeren met geheugenslimming
docker model run --memory 8g ai/llama2

# Uitvoeren met omgevingsvariabelen
docker model run -e MODEL_CONTEXT=4096 ai/llama2

# Uitvoeren met volume-aanhang voor blijvende gegevens
docker model run -v model-data:/data ai/llama2

Modellen tonen

Bekijk gedownloade en actieve modellen:

# Lijst met alle gedownloade modellen
docker model ls

# Lijst met actieve modellen
docker model ps

# Lijst met gedetailleerde informatie
docker model ls --all --format json

# Filter op naam
docker model ls --filter "name=llama"

Modellen stoppen

Stop actieve modelinstanties:

# Stop specifiek model
docker model stop my-llm

# Stop alle actieve modellen
docker model stop $(docker model ps -q)

# Stop met timeout
docker model stop --time 30 my-llm

Modellen verwijderen

Verwijder modellen van lokale opslag:

# Verwijder specifiek model
docker model rm ai/llama2

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

# Verwijder ongebruikte modellen
docker model prune

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

Aanpassen van aangepaste modellen

Maak een OCI-artefact aan van GGUF

Pak je eigen GGUF-modellen in:

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

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

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

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

Publiceren van modellen

Push modellen naar registraties:

# Aanmelden bij Docker Hub
docker login

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

# Push naar privéregistratie
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 APIs 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 respons
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_CONTEXT=4096
      - MODEL_TEMPERATURE=0.7
    volumes:
      - model-data:/root/.cache
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  model-data:

Multi-model instelling

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:

# Contextvenster grootte
MODEL_CONTEXT=4096

# 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 logboeken
MODEL_VERBOSE=true

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

Voer uit met omgevingsvariabelen:

docker model run \
  -e MODEL_CONTEXT=8192 \
  -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 geheugenslimming
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

# Inspecteer 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 APIs

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

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

# Bind aan specifiek 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 aan
docker network create llm-netwerk

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

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

Beveiliging

Toegangscontrole

# Start 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": [...]}'

Registratie authenticatie

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

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

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

Best practices

Modelselectie

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

# Controleer modelvarianten
docker search ai/llama2

Resourcebeheer

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

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

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

Gezondheidstests

# Start 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 georkestratieerd met standaard Kubernetes-manifesten. Definieer implementaties met resourcebeperkingen, autoscaling 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 kleiner gequantiseerd 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 inferentieprestaties:

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

# 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 actief is
if ! docker model ps | grep -q "llm"; then
    docker model run -d --name llm -p 8080:8080 ai/llama2
    echo "Wachten op modelstart..."
    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