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

Configurez les tailles de contexte dans Docker Model Runner avec des contournements

Sommaire

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.

configuring car 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 pourriez 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 ainsi votre configuration context_size: 10240.

Pourquoi cela arrive

La taille du 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 docker-compose de Docker Model Runner 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. Au lieu de cela, elle utilise par défaut 4096 tokens, indépendamment de votre configuration.

Cette limitation signifie que, même 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 fixée --ctx-size 4096 prend le dessus sur toute configuration que vous spécifiez.

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’intégration de votre propre application dans la composition. Cela est plus proche de la production.

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

Vous pouvez configurer la taille du contexte à l’aide de l’interface CLI Docker Model, qui stocke la configuration dans les métadonnées 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 limites importantes. La configuration est stockée mais n’est pas toujours appliquée correctement.

Limites :

  • 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 - cela l’ignorera
  • 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 : Empaqueter votre propre modèle

La manière la plus fiable de définir une taille de contexte personnalisée est d’empaqueter votre propre modèle avec la taille de contexte souhaitée à l’aide de docker model package. Cela intègre la taille du contexte dans les métadonnées du modèle lors de l’empaquetage :

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 empaqueté peut ensuite être poussé vers Docker Hub ou tout registre compatible OCI et 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)
  • Un réempaquetage à chaque fois que vous souhaitez modifier la taille du 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’empaquetage 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érifier la taille du 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.

Tester la taille du contexte

Pour vérifier si votre configuration de la taille du 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 du contexte fonctionne :

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

# Tester avec un prompt volumineux
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 du contexte, envisagez ces alternatives :

  • Ollama - Une solution alternative d’hébergement de modèles 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 de docker-compose.

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

Ressources liées

Docker Model Runner

Docker et infrastructure

Solutions alternatives LLM

Documentation officielle

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 est d’empaqueter 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 workflow 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 du contexte.

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