Docker Model Runner : Guide de configuration de la taille du contexte

Configuration des tailles de contexte dans Docker Model Runner est plus complexe qu’elle ne devrait l’être.

Bien que le paramètre context_size existe dans la configuration docker-compose, il est souvent ignoré par l’image docker/model-runner:latest-cuda, qui fixe une taille de contexte de 4096 tokens. Ce guide explore les limites et propose des solutions pratiques. Pour une comparaison plus large entre Docker Model Runner et Ollama, vLLM, LocalAI et les fournisseurs de cloud — y compris les compromis en matière de configuration et d’infrastructure — consultez LLM Hosting : Comparaison des infrastructures locales, auto-hébergées et en cloud.

Cette image a été générée par Flux 1 dev.

Comprendre le problème

Lors de l’utilisation de Docker Model Runner avec docker-compose, vous pouvez configurer la taille du contexte comme suit :

services:
  llm:
    image: docker/model-runner:latest-cuda
    models:
      - llm_model

models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240

Cependant, en examinant les journaux, on constate la taille de contexte réellement utilisée :

docker compose logs 2>&1 | grep -i "n_ctx"

Vous verrez une sortie comme :

llamaCppArgs: [... --ctx-size 4096 ...]
llama_context: n_ctx = 4096

L’image docker/model-runner:latest-cuda fixe manuellement --ctx-size 4096 lors de l’appel à llama.cpp, ignorant totalement votre configuration context_size: 10240.

Pourquoi cela se produit

La taille de contexte (n_ctx) est définie lors de l’initialisation du modèle dans llama.cpp, le moteur d’inférence sous-jacent utilisé par Docker Model Runner. Cela se produit pendant la phase de construction du contexte du modèle, avant tout traitement des requêtes API. L’intégration de Docker Model Runner avec docker-compose semble avoir un bug où elle ne transmet pas correctement le paramètre context_size depuis la section des modèles vers le processus llama.cpp sous-jacent. Elle utilise par défaut 4096 tokens, indépendamment de votre configuration.

Cette limitation signifie qu’even si Docker Compose reconnaît le paramètre context_size dans votre configuration YAML, l’image docker/model-runner:latest-cuda ne le respecte pas lors de la construction des arguments de ligne de commande de llama.cpp. L’option fixe --ctx-size 4096 a la priorité sur toute configuration spécifiée.

Contournements et solutions

Que faire ? Les méthodes 1 à 3 fonctionneront, mais elles ont des limites.

Méthode 1. ad-hoc, fonctionne. Méthode 2. fixée dans le modèle. Méthode 3. nécessite une conteneurisation et l’inclusion de votre propre application dans la composition. Cela est plus proche d’une solution de production.

Méthode 1 : Utiliser docker model configure (limitée)

Vous pouvez configurer la taille du contexte à l’aide de l’interface CLI de Docker Model, qui stocke la configuration dans les métadonnées du modèle de Docker :

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

Cette commande met à jour la configuration du modèle, mais l’implémentation a des limitations importantes. La configuration est stockée mais n’est pas toujours appliquée correctement.

Limitations :

• Cela ne fonctionne pas lors de l’utilisation directe de docker model run, uniquement via une requête curl vers le point de terminaison API
• Vous ne pouvez pas utiliser docker model run après la configuration — elle sera ignorée
• La configuration est ignorée lors de l’utilisation de docker-compose avec l’image docker/model-runner:latest-cuda
• La configuration peut être perdue lors de la mise à jour ou du retrait du modèle

Cette méthode fonctionne le mieux pour les tests avec des appels API directs, mais n’est pas adaptée aux déploiements en production utilisant docker-compose.

Méthode 2 : Emballer votre propre modèle

La façon la plus fiable de définir une taille de contexte personnalisée est d’emballer votre propre modèle avec la taille de contexte souhaitée à l’aide de docker model package. Cela inscrit la taille du contexte dans les métadonnées du modèle lors de l’emballage :

docker model package \
  --gguf /path/to/model.gguf \
  --context-size 10240 \
  --name my-model:custom-context

Cela crée un nouvel artefact OCI (similaire à une image Docker) avec une taille de contexte configurée de manière permanente. Le modèle emballé peut ensuite être poussé vers Docker Hub ou tout registre compatible OCI et être tiré comme tout autre modèle Docker Model Runner.

Cependant, cette approche nécessite :

• L’accès au fichier GGUF original (le format quantifié utilisé par llama.cpp)
• Le réemballage à chaque fois que vous souhaitez modifier la taille de contexte, ce qui peut être chronophage
• La gestion de votre propre registre de modèles ou d’un compte Docker Hub
• Une compréhension de la workflow d’emballage de Docker Model Runner

Cette méthode est adaptée aux environnements de production où vous avez besoin de tailles de contexte cohérentes et reproductibles à travers les déploiements.

Méthode 3 : Docker Compose

Cela est actuellement cassé pour docker/model-runner:latest-cuda

Mais pour votre propre application dans l’image, cela pourrait fonctionner :)

Bien que la syntaxe existe dans docker-compose.yml :

services:
  llm:
    image: docker/model-runner:latest-cuda
    models:
      - llm_model

models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240

Cela ne fonctionne pas — le paramètre context_size est reconnu par docker-compose mais n’est pas appliqué. Le modèle utilise toujours 4096 tokens.

Méthode 4 : Variables d’environnement (Également cassée)

En tentant d’utiliser la variable d’environnement MODEL_CONTEXT :

services:
  llm:
    image: docker/model-runner:latest-cuda
    environment:
      - MODEL_CONTEXT=10240

Cela ne fonctionne pas non plus — la variable d’environnement n’est pas respectée lors de l’utilisation de docker-compose.

Vérification de la taille de contexte

Pour vérifier quelle taille de contexte est réellement utilisée, examinez les journaux :

# Vérifier les arguments de llama.cpp
docker compose logs 2>&1 | grep "llamaCppArgs"

# Vérifier la taille de contexte réelle
docker compose logs 2>&1 | grep -i "n_ctx" | tail -10

Vous verrez une sortie comme :

llamaCppArgs: [-ngl 999 --metrics --model /models/... --ctx-size 4096 ...]
llama_context: n_ctx = 4096
llama_context: n_ctx_per_seq = 4096

Si vous voyez n_ctx = 4096 malgré la configuration d’une valeur différente, votre configuration est ignorée.

Test de la taille de contexte

Pour vérifier si votre configuration de la taille de contexte est effectivement appliquée, vous devez tester avec des prompts dépassant la limite par défaut de 4096 tokens. Voici un script pratique utilisant Python pour tester si votre configuration de la taille de contexte fonctionne :

#!/bin/bash
MODEL="ai/gemma3-qat:4B"
PORT=8085

# Test avec un prompt long
python3 -c "print('test ' * 5000)" > large_prompt.txt

python3 << 'PYTHON' > request.json
import json
import os

with open('large_prompt.txt', 'r') as f:
    large_prompt = f.read().strip()

request = {
    "model": os.environ.get("MODEL", "ai/gemma3-qat:4B"),
    "messages": [{
        "role": "user",
        "content": large_prompt
    }]
}
print(json.dumps(request))
PYTHON

curl -s http://localhost:${PORT}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d @request.json > response.json

# Vérifier l'utilisation des tokens
python3 << 'PYTHON'
import json
with open('response.json') as f:
    r = json.load(f)
    if 'usage' in r:
        print(f"Prompt tokens: {r['usage']['prompt_tokens']}")
        if r['usage']['prompt_tokens'] > 4096:
            print("✅ La fenêtre de contexte est plus grande que 4096 !")
        else:
            print("⚠️ La fenêtre de contexte semble limitée à 4096")
PYTHON

Solutions alternatives

Si vous avez besoin d’une configuration plus flexible de la taille de contexte, envisagez ces alternatives :

• Ollama — Une solution alternative d’hébergement de LLM qui offre un meilleur contrôle sur les tailles de contexte et une configuration plus simple. Ollama vous permet de spécifier la taille du contexte par modèle et n’a pas les mêmes limites avec docker-compose.

• Comparaison Docker Model Runner vs Ollama — Une comparaison détaillée des deux solutions, y compris les capacités de configuration des tailles de contexte, les performances et quand choisir chaque plateforme.

Pour voir comment Docker Model Runner s’intègre avec d’autres options locales et en cloud, consultez notre guide LLM Hosting : Comparaison des infrastructures locales, auto-hébergées et en cloud.

Ressources liées

Docker Model Runner

• Cheatsheet de Docker Model Runner — Référence complète des commandes avec exemples pour toutes les opérations Docker Model Runner
• Ajouter le support GPU NVIDIA à Docker Model Runner — Guide étape par étape pour activer l’accélération GPU
• Docker Model Runner vs Ollama : Quelle solution choisir ?

Docker et infrastructure

• Cheatsheet Docker — Commandes essentielles pour la gestion des conteneurs
• Cheatsheet Docker Compose — Guide complet sur la configuration et les commandes Docker Compose

Solutions alternatives LLM

• Cheatsheet Ollama — Solution alternative d’hébergement LLM avec un support GPU intégré et une configuration plus simple de la taille de contexte
• Intégrer Ollama avec Python

Documentation officielle

• Documentation Docker Model Runner — Documentation officielle de Docker Model Runner
• Configuration du contexte de llama.cpp — Documentation du moteur d’inférence sous-jacent

Conclusion

La configuration des tailles de contexte dans Docker Model Runner est actuellement problématique lors de l’utilisation de docker-compose. Bien que la syntaxe de configuration existe dans la spécification Docker Compose, elle n’est pas correctement implémentée dans l’image docker/model-runner:latest-cuda, qui fixe une taille de contexte de 4096 tokens indépendamment de votre configuration.

Le contournement le plus fiable consiste à emballer vos propres modèles avec la taille de contexte souhaitée à l’aide de docker model package, bien que cela ajoute de la complexité à votre flux de travail et nécessite l’accès aux fichiers GGUF originaux. En alternative, vous pouvez utiliser docker model configure pour l’accès direct à l’API, mais cela ne fonctionne pas avec les déploiements docker-compose.

Pour la plupart des cas d’utilisation, la taille de contexte par défaut de 4096 tokens est suffisante pour les applications typiques d’IA conversationnelle. Si vous avez besoin de fenêtres de contexte plus grandes ou d’une configuration plus flexible, envisagez d’utiliser Ollama comme alternative, qui offre un meilleur contrôle sur les tailles de contexte sans les limites de docker-compose.

Vous pouvez toujours optimiser l’utilisation de la VRAM par d’autres moyens, comme la quantisation du modèle (Q4, Q6, Q8) et la configuration des couches GPU (MODEL_GPU_LAYERS), qui sont plus efficaces pour réduire la consommation de mémoire que les ajustements de la taille de contexte.

Pour plus de détails sur l’optimisation GPU et la gestion de la VRAM, consultez notre guide sur la configuration du support GPU NVIDIA.