Fiche de raccourcis Docker Model Runner : commandes et exemples

Référence rapide des commandes de Docker Model Runner

Docker Model Runner (DMR) est la solution officielle de Docker pour exécuter des modèles d’IA localement, introduite en avril 2025. Cette fiche de référence fournit un aperçu rapide de toutes les commandes essentielles, configurations et bonnes pratiques.

liste des modèles gemma disponibles dans docker model runner

Installation

Docker Desktop

Activez Docker Model Runner via l’interface graphique :

  1. Ouvrez Docker Desktop
  2. Allez dans Paramètres → Onglet AI
  3. Cliquez sur Activer Docker Model Runner
  4. Redémarrez Docker Desktop

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

Docker Engine (Linux)

Installez le package du plugin :

# 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

Vérifiez l’installation :

docker model --help

Support NVIDIA RTX pour Docker

Pour activer l’exécution des LLM sur GPU au lieu du CPU, installez 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

ensuite, vous pouvez exécuter des conteneurs avec --gpus all

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

vérifiez que le conteneur peut voir le GPU :

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

Ajout du support NVidia pour Docker Model Runner

Docker Model Runner nécessite une configuration explicite du GPU. Contrairement aux commandes standard docker run, docker model run ne prend pas en charge les drapeaux --gpus ou -e. Au lieu de cela, vous devez :

  1. Configurer le démon Docker pour utiliser le runtime NVIDIA par défaut

Tout d’abord, vérifiez où se trouve nvidia-container-runtime installé :

which nvidia-container-runtime

Cela affichera généralement /usr/bin/nvidia-container-runtime. Utilisez ce chemin dans la configuration suivante.

Créez ou mettez à jour /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

Note : Si which nvidia-container-runtime retourne un autre chemin, mettez à jour la valeur "path" dans la configuration JSON en conséquence.

Redémarrez Docker :

sudo systemctl restart docker

Vérifiez la configuration :

docker info | grep -i runtime

Vous devriez voir Default Runtime: nvidia dans la sortie.

  1. Réinstallez Docker Model Runner avec le support GPU

Docker Model Runner doit être installé/réinstallé avec un support GPU explicite :

# Arrêtez le runner actuel
docker model stop-runner

# Réinstallez avec le support CUDA
docker model reinstall-runner --gpu cuda

Cela tirera la version activée par CUDA (docker/model-runner:latest-cuda) au lieu de la version uniquement CPU.

  1. Vérifiez l’accès au GPU

Vérifiez que le conteneur Docker Model Runner peut accéder au GPU :

docker exec docker-model-runner nvidia-smi
  1. Testez un modèle avec le GPU

Exécutez un modèle et vérifiez les journaux pour confirmer l’utilisation du GPU :

docker model run ai/qwen3:14B-Q6_K "qui êtes-vous ?"

Vérifiez les journaux pour la confirmation du GPU :

docker model logs | grep -i cuda

Vous devriez voir des messages comme :

  • utilisation du dispositif CUDA0 (NVIDIA GeForce RTX 4080)
  • déchargé 41/41 couches sur le GPU
  • taille du tampon du modèle CUDA0 = 10946,13 MiB

Note : Si vous avez déjà installé Docker Model Runner sans support GPU, vous devez le réinstaller avec le drapeau --gpu cuda. Simplement configurer le démon Docker n’est pas suffisant - le conteneur runner lui-même doit être la version activée par CUDA.

Backends GPU disponibles :

  • cuda - NVIDIA CUDA (le plus courant)
  • rocm - AMD ROCm
  • musa - Moore Threads MUSA
  • cann - Huawei CANN
  • auto - Détection automatique (par défaut)
  • none - Uniquement CPU

Commandes principales

Tirer des modèles

Tirez des modèles préemballés depuis Docker Hub :

# Tirage basique
docker model pull ai/llama2

# Tirage d'une version spécifique
docker model pull ai/llama2:7b-q4

# Tirage depuis un registre personnalisé
docker model pull myregistry.com/models/mistral:latest

# Liste des modèles disponibles dans un espace de noms
docker search ai/

Exécuter des modèles

Démarrer un modèle avec un service API automatique :

# Exécution basique (interactive)
docker model run ai/llama2 "Qu'est-ce que Docker ?"

# Exécution en service (en arrière-plan)
docker model run -d

globalement, nous n’avons pas beaucoup d’options pour exécuter des modèles via CLI :

docker model run --help
Utilisation :  docker model run MODÈLE [PROMPT]

Exécuter un modèle et interagir avec lui à l'aide d'un prompt soumis ou en mode chat

Options :
      --color string                  Utiliser la sortie colorée (auto|yes|no) (par défaut "auto")
      --debug                         Activer le journalisation débogage
  -d, --detach                        Charger le modèle en arrière-plan sans interaction
      --ignore-runtime-memory-check   Ne pas bloquer le tirage si la mémoire estimée du modèle dépasse les ressources du système.

Liste des modèles

Afficher les modèles téléchargés et en cours d’exécution :

# Liste de tous les modèles téléchargés
docker model ls

# Liste des modèles en cours d'exécution
docker model ps

# Liste avec des informations détaillées
docker model ls --json

# Liste avec des informations détaillées
docker model ls --openai

# Retournera des hachages
docker model ls -q

Supprimer des modèles

Supprimer des modèles du stockage local :

# Supprimer un modèle spécifique
docker model rm ai/llama2

# Supprimer avec force (même s'il est en cours d'exécution)
docker model rm -f ai/llama2

# Supprimer les modèles inutilisés
docker model prune

# Supprimer tous les modèles
docker model rm $(docker model ls -q)

Configuration des tailles de contexte des modèles

Nous ne pouvons pas utiliser le CLI pour spécifier la taille de contexte pour une demande particulière.

En général, nous pouvons contrôler la taille de contexte du modèle que de trois manières :

  1. Empaqueter nous-mêmes le modèle, en spécifiant la taille de contexte souhaitée (Voir plus sur cela dans la section suivante.)

  2. Lors de l’utilisation du docker model runner, configurez la commande avec le paramètre –context-size comme suit :

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

Ensuite, vous pouvez appeler curl vers lui, mais vous ne pouvez pas faire docker model run... - celui-ci ignorera la configuration.

  1. Dans le fichier docker-compose.yaml, mais nous ne pouvons pas utiliser l’image docker-model-runner de cette manière, car elle transmet à la taille de contexte codée en dur du modèle de 4096
...
models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240
...

Pour plus de détails, veuillez consulter le post dédié à ce sujet : Spécifier la taille de contexte dans DMR

Empaquetage de modèles personnalisés

Créer un artefact OCI à partir de GGUF

Empaqueter vos propres modèles GGUF :

# Empaquetage basique
docker model package --gguf /chemin/vers/model.gguf myorg/mymodel:latest

# Empaquetage avec métadonnées
docker model package \
  --gguf /chemin/vers/model.gguf \
  --label "description=Modèle personnalisé Llama" \
  --label "version=1.0" \
  myorg/mymodel:v1.0

# Empaquetage et pousser en une seule commande
docker model package --gguf /chemin/vers/model.gguf --push myorg/mymodel:latest

# Empaquetage avec une taille de contexte personnalisée
docker model package \
  --gguf /chemin/vers/model.gguf \
  --context 8192 \
  myorg/mymodel:latest

Publication de modèles

Pousser des modèles vers des registres :

# Connexion à Docker Hub
docker login

# Pousser vers Docker Hub
docker model push myorg/mymodel:latest

# Pousser vers un registre privé
docker login myregistry.com
docker model push myregistry.com/models/mymodel:latest

# Étiqueter et pousser
docker model tag mymodel:latest myorg/mymodel:v1.0
docker model push myorg/mymodel:v1.0

Utilisation de l’API

Points de terminaison compatibles OpenAI

Docker Model Runner expose automatiquement des API compatibles OpenAI :

# Démarrer le modèle avec l'API
docker model run -d -p 8080:8080 --name llm ai/llama2

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

# Génération de texte
curl http://localhost:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "prompt": "Il était une fois",
    "max_tokens": 100
  }'

# Réponse en flux
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Raconte-moi une histoire"}],
    "stream": true
  }'

# Liste des modèles disponibles via l'API
curl http://localhost:8080/v1/models

# Informations sur le modèle
curl http://localhost:8080/v1/models/llama2

Configuration Docker Compose

Fichier Compose basique

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

Configuration multi-modèles

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"

Pour des configurations Docker Compose plus avancées et des commandes, consultez notre Fiche de référence Docker Compose couvrant le réseau, les volumes et les modèles d’orchestration.

Variables d’environnement

Configurez le comportement du modèle avec des variables d’environnement :

# Température (0,0-1,0)
MODEL_TEMPERATURE=0,7

# Échantillonnage top-p
MODEL_TOP_P=0,9

# Échantillonnage top-k
MODEL_TOP_K=40

# Nombre maximum de tokens
MODEL_MAX_TOKENS=2048

# Nombre de couches GPU
MODEL_GPU_LAYERS=35

# Taille de lot
MODEL_BATCH_SIZE=512

# Nombre de threads (CPU)
MODEL_THREADS=8

# Activer le journalisation détaillée
MODEL_VERBOSE=true

# Clé API pour l'authentification
MODEL_API_KEY=your-secret-key

Exécutez avec des variables d’environnement :

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

Configuration GPU

Détection automatique des GPU

DMR détecte automatiquement et utilise les GPU disponibles :

# Utiliser tous les GPU
docker model run --gpus all ai/llama2

# Utiliser un GPU spécifique
docker model run --gpus 0 ai/llama2

# Utiliser plusieurs GPU spécifiques
docker model run --gpus 0,1,2 ai/llama2

# GPU avec limite de mémoire
docker model run --gpus all --memory 16g ai/llama2

Mode uniquement CPU

Forcer l’inférence sur CPU même si le GPU est disponible :

docker model run --no-gpu ai/llama2

Parallélisme tensoriel multi-GPU

Répartir de grands modèles sur plusieurs GPU :

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

Inspection et débogage

Afficher les détails du modèle

# Inspecter la configuration du modèle
docker model inspect ai/llama2

# Afficher les couches du modèle
docker model history ai/llama2

# Vérifier la taille du modèle et les métadonnées
docker model inspect --format='{{.Size}}' ai/llama2

Journaux et surveillance

# Afficher les journaux du modèle
docker model logs llm

# Suivre les journaux en temps réel
docker model logs -f llm

# Afficher les 100 dernières lignes
docker model logs --tail 100 llm

# Afficher les journaux avec des horodatages
docker model logs -t llm

Statistiques de performance

# Utilisation des ressources
docker model stats

# Statistiques d'un modèle spécifique
docker model stats llm

# Statistiques au format JSON
docker model stats --format json

Réseau

Exposition des API

# Port par défaut (8080)
docker model run -p 8080:8080 ai/llama2

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

# Se lier à une interface spécifique
docker model run -p 127.0.0.1:8080:8080 ai/llama2

# Plusieurs ports
docker model run -p 8080:8080 -p 9090:9090 ai/llama2

Configuration du réseau

# Créer un réseau personnalisé
docker network create llm-network

# Exécuter un modèle sur un réseau personnalisé
docker model run --network llm-network --name llm ai/llama2

# Se connecter à un réseau existant
docker model run --network host ai/llama2

Sécurité

Contrôle d’accès

# Exécuter avec l'authentification par clé API
docker model run \
  -e MODEL_API_KEY=my-secret-key \
  ai/llama2

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

Authentification du registre

# Se connecter à un registre privé
docker login myregistry.com -u username -p password

# Tirer depuis un registre privé
docker model pull myregistry.com/private/model:latest

# Utiliser un helper de credentials
docker login --password-stdin < token.txt

Bonnes pratiques

Sélection de modèles

# Utiliser des modèles quantifiés pour une inférence plus rapide
docker model pull ai/llama2:7b-q4     # quantification 4-bit
docker model pull ai/llama2:7b-q5     # quantification 5-bit
docker model pull ai/llama2:7b-q8     # quantification 8-bit

# Vérifier les variantes de modèles
docker search ai/llama2

Gestion des ressources

# Définir des limites de mémoire
docker model run --memory 8g --memory-swap 16g ai/llama2

# Définir des limites de CPU
docker model run --cpus 4 ai/llama2

# Limiter la mémoire GPU
docker model run --gpus all --gpu-memory 8g ai/llama2

Vérifications de santé

# Exécuter avec vérification de santé
docker model run \
  --health-cmd "curl -f http://localhost:8080/health || exit 1" \
  --health-interval 30s \
  --health-timeout 10s \
  --health-retries 3 \
  ai/llama2

Orchestration en production

Pour les déploiements en production avec Kubernetes, les conteneurs Docker Model Runner peuvent être orchestrés à l’aide des manifestes Kubernetes standards. Définissez les déploiements avec des limites de ressources, un autoscaling et un équilibrage de charge. Pour une référence complète des commandes Kubernetes et des modèles de déploiement, consultez notre Fiche de référence Kubernetes.

# Exemple : Déployer sur un cluster Kubernetes
kubectl apply -f llm-deployment.yaml

# Échelle du déploiement
kubectl scale deployment llm --replicas=3

# Exposer en tant que service
kubectl expose deployment llm --type=LoadBalancer --port=8080

Dépannage

Problèmes courants

Le modèle ne démarre pas :

# Vérifier l'espace disque disponible
df -h

# Voir les journaux d'erreur détaillés
docker model logs --tail 50 llm

# Vérifier la disponibilité du GPU
nvidia-smi  # Pour les GPU NVIDIA

Erreurs de mémoire insuffisante :

# Utiliser un modèle quantifié plus petit
docker model pull ai/llama2:7b-q4

# Réduire la taille de contexte
docker model run -e MODEL_CONTEXT=2048 ai/llama2

# Limiter la taille du lot
docker model run -e MODEL_BATCH_SIZE=256 ai/llama2

Inférence lente :

# Vérifier l'utilisation du GPU
docker model stats llm

# Assurer que le GPU est utilisé
docker model logs llm | grep -i gpu

# Augmenter le nombre de couches GPU
docker model run -e MODEL_GPU_LAYERS=40 ai/llama2

Commandes de diagnostic

# Informations système
docker model system info

# Utilisation du disque
docker model system df

# Nettoyer les ressources inutilisées
docker model system prune

# Nettoyage complet (supprimer tous les modèles)
docker model system prune -a

Exemples d’intégration

Intégration Python

import openai

# Configurer le client pour Docker Model Runner
client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # DMR n'exige pas de clé par défaut
)

# Complétion de chat
response = client.chat.completions.create(
    model="llama2",
    messages=[
        {"role": "user", "content": "Bonjour !"}
    ]
)

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

# Flux
stream = client.chat.completions.create(
    model="llama2",
    messages=[{"role": "user", "content": "Raconte-moi une histoire"}],
    stream=True
)

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

Script Bash

#!/bin/bash

# Démarrer le modèle si non en cours d'exécution
if ! docker model ps | grep -q "llm"; then
    docker model run -d --name llm -p 8080:8080 ai/llama2
    echo "En attente du démarrage du modèle..."
    sleep 10
fi

# Faire un appel API
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'

Intégration Node.js

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

// Utilisation
const response = await chat('Qu'est-ce que Docker Model Runner ?');
console.log(response);

Liens utiles

Documentation officielle

Fiches de référence

Articles de comparaison