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 localement des modèles d’IA, 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 → AI (onglet)
  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êtres 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

Commandes principales

Téléchargement de modèles

Téléchargez des modèles préemballés depuis Docker Hub :

# Téléchargement basique
docker model pull ai/llama2

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

# Téléchargement 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écution de modèles

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

# Démarrage basique (interactif)
docker model run ai/llama2 "Qu'est-ce que Docker ?"

# Démarrer en tant que service (en arrière-plan)
docker model run -d --name my-llm ai/llama2

# Démarrer avec un port personnalisé
docker model run -p 8080:8080 ai/llama2

# Démarrer avec une spécification GPU
docker model run --gpus 0,1 ai/llama2

# Démarrer avec une limite de mémoire
docker model run --memory 8g ai/llama2

# Démarrer avec des variables d'environnement
docker model run -e MODEL_CONTEXT=4096 ai/llama2

# Démarrer avec un montage de volume pour des données persistantes
docker model run -v model-data:/data ai/llama2

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 --all --format json

# Filtre par nom
docker model ls --filter "name=llama"

Arrêt des modèles

Arrêter les instances de modèles en cours d’exécution :

# Arrêter un modèle spécifique
docker model stop my-llm

# Arrêter tous les modèles en cours d'exécution
docker model stop $(docker model ps -q)

# Arrêter avec un délai
docker model stop --time 30 my-llm

Suppression des modèles

Supprimer des modèles de l’espace de 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 non utilisés
docker model prune

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

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 /path/to/model.gguf myorg/mymodel:latest

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

# Empaquetage et déploiement en une seule commande
docker model package --gguf /path/to/model.gguf --push myorg/mymodel:latest

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

Publication de modèles

Déployer des modèles sur des registres :

# Connexion à Docker Hub
docker login

# Déploiement sur Docker Hub
docker model push myorg/mymodel:latest

# Déploiement sur un registre privé
docker login myregistry.com
docker model push myregistry.com/models/mymodel:latest

# Étiquetage et déploiement
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_CONTEXT=4096
      - MODEL_TEMPERATURE=0.7
    volumes:
      - model-data:/root/.cache
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  model-data:

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 plus de configurations avancées de Docker Compose et de commandes, consultez notre Fiche de référence Docker Compose couvrant les réseaux, les volumes et les modèles d’orchestration.

Variables d’environnement

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

# Taille de la fenêtre de contexte
MODEL_CONTEXT=4096

# 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_CONTEXT=8192 \
  -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 CPU uniquement

Forcer l’inférence en 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 et les métadonnées du modèle
docker model inspect --format='{{.Size}}' ai/llama2

Journalisation 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 connecter à 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 de registre

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

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

# Utiliser un assistant de gestion des identifiants
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é

# Démarrer 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 standard Kubernetes. 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

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

# Vérifier la disponibilité des 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 du 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

# Vérifier 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 non utilisé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 "Attente du démarrage du modèle..."
    sleep 10
fi

# Effectuer une 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 associées

Articles de comparaison