Docker Model Runner: Leitfaden zur Konfiguration der Kontextgröße

Konfigurieren Sie Kontextgrößen in Docker Model Runner mit Workarounds

Inhaltsverzeichnis

Konfigurieren von Kontextgrößen im Docker Model Runner ist komplexer, als es sein sollte.

Während der Parameter context_size in der docker-compose-Konfiguration existiert, wird er oft vom Bild docker/model-runner:latest-cuda ignoriert, das eine Kontextgröße von 4096 Tokens fest codiert. Dieser Leitfaden untersucht die Einschränkungen und bietet praktische Workarounds.

configuring car Dieses Bild wurde von Flux 1 dev generiert.

Verständnis des Problems

Bei der Verwendung von Docker Model Runner mit docker-compose könnten Sie die Kontextgröße wie folgt konfigurieren:

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

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

Allerdings zeigen die Protokolle die tatsächlich verwendete Kontextgröße an:

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

Sie werden eine Ausgabe wie diese sehen:

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

Das Bild docker/model-runner:latest-cuda kodiert --ctx-size 4096 fest, wenn llama.cpp aufgerufen wird, und ignoriert Ihre Konfiguration context_size: 10240 vollständig.

Warum dies geschieht

Die Kontextgröße (n_ctx) wird zur Initialisierungszeit des Modells in llama.cpp festgelegt, dem zugrunde liegenden Inferenz-Engine, das Docker Model Runner verwendet. Dies geschieht während der Kontextkonstruktionsphase des Modells, bevor API-Anfragen verarbeitet werden. Die Docker Compose-Integration von Docker Model Runner scheint einen Fehler zu haben, bei dem der context_size-Parameter aus dem Modulbereich nicht korrekt an den zugrunde liegenden llama.cpp-Prozess weitergegeben wird. Stattdessen wird standardmäßig 4096 Tokens verwendet, unabhängig von Ihrer Konfiguration.

Diese Einschränkung bedeutet, dass selbst wenn Docker Compose den context_size-Parameter in Ihrer YAML-Konfiguration erkennt, das Bild docker/model-runner:latest-cuda ihn nicht berücksichtigt, wenn die Befehlszeilenargumente von llama.cpp konstruiert werden. Die fest codierte Flagge --ctx-size 4096 hat Vorrang gegenüber jeder von Ihnen angegebenen Konfiguration.

Workarounds und Lösungen

Was tun? Methoden 1-2-3 funktionieren, haben aber Einschränkungen.

Methode 1. Ad-hoc, wird funktionieren. Methode 2. Im Modell fest codiert. Methode 3. Erfordert Containerisierung und Integration Ihrer eigenen Anwendung in die Komposition. Das ist näher an der Produktion.

Methode 1: Verwendung von docker model configure (Eingeschränkt)

Sie können die Kontextgröße mit der Docker Model CLI konfigurieren, die die Konfiguration in den Docker-Modellmetadaten speichert:

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

Dieser Befehl aktualisiert die Modellkonfiguration, hat aber erhebliche Einschränkungen. Die Konfiguration wird gespeichert, aber nicht immer korrekt angewendet.

Einschränkungen:

  • Dies funktioniert nicht bei direkter Verwendung von docker model run, nur über curl an die API-Endpunkt
  • Sie können docker model run nach der Konfiguration nicht verwenden - es wird die Konfiguration ignorieren
  • Die Konfiguration wird ignoriert, wenn docker-compose mit dem Bild docker/model-runner:latest-cuda verwendet wird
  • Die Konfiguration kann verloren gehen, wenn das Modell aktualisiert oder erneut gezogen wird

Diese Methode eignet sich am besten für Tests mit direkten API-Aufrufen, ist aber nicht für Produktionsbereitstellungen mit docker-compose geeignet.

Methode 2: Eigenes Modell paketieren

Die zuverlässigste Methode zur Festlegung einer benutzerdefinierten Kontextgröße besteht darin, Ihr eigenes Modell mit der gewünschten Kontextgröße mit docker model package zu paketieren. Dies “backt” die Kontextgröße in die Metadaten des Modells zum Paketierungszeitpunkt ein:

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

Dies erstellt ein neues OCI-Artifact (ähnlich einem Docker-Image) mit der dauerhaft konfigurierten Kontextgröße. Das paketierte Modell kann dann an Docker Hub oder jedes OCI-konforme Repository gepusht und wie jedes andere Docker Model Runner-Modell gezogen werden.

Allerdings erfordert dieser Ansatz:

  • Zugriff auf die ursprüngliche GGUF-Modelldatei (das quantisierte Format, das von llama.cpp verwendet wird)
  • Neues Paketieren jedes Mal, wenn Sie die Kontextgröße ändern möchten, was zeitaufwendig sein kann
  • Verwaltung Ihres eigenen Modellregistrys oder eines Docker Hub-Kontos
  • Verständnis des Docker Model Runner-Paketierungs-Workflows

Diese Methode eignet sich am besten für Produktionsumgebungen, in denen Sie konsistente, reproduzierbare Kontextgrößen über Bereitstellungen hinweg benötigen.

Methode 3: Docker Compose

Dies ist derzeit für docker/model-runner:latest-cuda defekt

Aber für Ihre eigene App im Bild könnte es funktionieren :)

Obwohl die Syntax in docker-compose.yml existiert:

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

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

Dies funktioniert nicht - der Parameter context_size wird von docker-compose erkannt, aber nicht angewendet. Das Modell verwendet weiterhin 4096 Tokens.

Methode 4: Umgebungsvariablen (Auch defekt)

Versuch, die Umgebungsvariable MODEL_CONTEXT zu verwenden:

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

Dies funktioniert ebenfalls nicht - die Umgebungsvariable wird bei Verwendung von docker-compose nicht berücksichtigt.

Überprüfung der Kontextgröße

Um zu überprüfen, welche Kontextgröße tatsächlich verwendet wird, untersuchen Sie die Protokolle:

# Überprüfen Sie die llama.cpp-Argumente
docker compose logs 2>&1 | grep "llamaCppArgs"

# Überprüfen Sie die tatsächliche Kontextgröße
docker compose logs 2>&1 | grep -i "n_ctx" | tail -10

Sie werden eine Ausgabe wie diese sehen:

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

Wenn Sie n_ctx = 4096 sehen, obwohl Sie einen anderen Wert konfiguriert haben, wird Ihre Konfiguration ignoriert.

Testen der Kontextgröße

Um zu überprüfen, ob Ihre Kontextgrößenkonfiguration tatsächlich angewendet wird, müssen Sie mit Prompts testen, die die Standardgrenze von 4096 Tokens überschreiten. Hier ist ein praktisches Skript unter Verwendung von Python, um zu testen, ob Ihre Kontextgrößenkonfiguration funktioniert:

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

# Test mit großem Prompt
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

# Überprüfen Sie die Token-Nutzung
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("✅ Das Kontextfenster ist größer als 4096!")
        else:
            print("⚠️ Das Kontextfenster scheint auf 4096 begrenzt zu sein")
PYTHON

Alternative Lösungen

Wenn Sie eine flexiblere Kontextgrößenkonfiguration benötigen, sollten Sie diese Alternativen in Betracht ziehen:

  • Ollama - Eine alternative LLM-Hosting-Lösung, die eine bessere Kontrolle über Kontextgrößen und eine einfachere Konfiguration bietet. Ollama ermöglicht es Ihnen, die Kontextgröße pro Modell festzulegen und hat nicht die gleichen docker-compose-Einschränkungen.

  • Vergleich von Docker Model Runner vs Ollama - Ein detaillierter Vergleich beider Lösungen, einschließlich der Fähigkeiten zur Kontextgrößenkonfiguration, Leistung und wann Sie jede Plattform wählen sollten.

Verwandte Ressourcen

Docker Model Runner

Docker und Infrastruktur

Alternative LLM-Lösungen

Offizielle Dokumentation

Fazit

Die Konfiguration von Kontextgrößen in Docker Model Runner ist derzeit problematisch bei der Verwendung von docker-compose. Obwohl die Konfigurationssyntax in der Docker Compose-Spezifikation existiert, ist sie nicht ordnungsgemäß in dem Bild docker/model-runner:latest-cuda implementiert, das eine Kontextgröße von 4096 Tokens unabhängig von Ihrer Konfiguration fest einstellt.

Die zuverlässigste Workaround-Lösung besteht darin, Ihre eigenen Modelle mit der gewünschten Kontextgröße zu paketieren, indem Sie docker model package verwenden, obwohl dies Komplexität zu Ihrem Workflow hinzufügt und den Zugriff auf die ursprünglichen GGUF-Modelldateien erfordert. Alternativ können Sie docker model configure für den direkten API-Zugriff verwenden, aber dies funktioniert nicht mit docker-compose-Einsätzen.

Für die meisten Anwendungsfälle ist die Standard-Kontextgröße von 4096 Tokens ausreichend für typische Anwendungen der konversationellen KI. Wenn Sie größere Kontextfenster oder eine flexiblere Konfiguration benötigen, sollten Sie Ollama als Alternative in Betracht ziehen, das eine bessere Kontrolle über die Kontextgrößen ohne die docker-compose-Beschränkungen bietet.

Sie können die VRAM-Nutzung weiterhin durch andere Mittel wie Modellquantisierung (Q4, Q6, Q8) und GPU-Schichtkonfiguration (MODEL_GPU_LAYERS) optimieren, die effektiver für die Reduzierung des Speicherverbrauchs sind als Anpassungen der Kontextgröße.

Für weitere Details zur GPU-Optimierung und VRAM-Verwaltung siehe unsere Anleitung zur Konfiguration der NVIDIA-GPU-Unterstützung.