Docker Model Runner: Gids voor het configureren van contextgrootte

Stel contextgrootte in in Docker Model Runner met omzeilingen

Inhoud

Het configureren van contextgrootte in Docker Model Runner is complexer dan het zou moeten zijn.

Hoewel het context_size-parameter bestaat in de docker-compose configuratie, wordt deze vaak genegeerd door de docker/model-runner:latest-cuda-afbeelding, die een contextgrootte van 4096 tokens hardcode. Deze gids verkent de beperkingen en biedt praktische omzeerweges.

configureren car Deze afbeelding is gegenereerd door Flux 1 dev.

Het Probleem Begrijpen

Wanneer je Docker Model Runner gebruikt met docker-compose, kun je de contextgrootte zo configureren:

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

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

Echter, door de logboeken te controleren, blijkt de daadwerkelijke contextgrootte die wordt gebruikt:

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

Je zult een uitvoer zien zoals:

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

De docker/model-runner:latest-cuda-afbeelding codeert --ctx-size 4096 hard, wanneer het llama.cpp aanroept, en negeert volledig je context_size: 10240-configuratie.

Waarom Dit Gebeurt

De contextgrootte (n_ctx) wordt ingesteld tijdens de initialisatie van het model in llama.cpp, het onderliggende inferentie-engine dat Docker Model Runner gebruikt. Dit gebeurt tijdens de contextconstructiefase van het model, voor het verwerken van enige API-aanvragen. De docker-compose integratie van Docker Model Runner lijkt een bug te hebben waarbij het niet correct de context_size-parameter doorgeeft van de modellensectie naar het onderliggende llama.cpp-proces. In plaats daarvan wordt er standaard 4096 tokens gebruikt, ongeacht je configuratie.

Deze beperking betekent dat, hoewel Docker Compose de context_size-parameter herkent in je YAML-configuratie, de docker/model-runner:latest-cuda-afbeelding deze niet respecteert wanneer het de command-line-argumenten van llama.cpp genereert. De hardcoded --ctx-size 4096-vlag heeft voorrang op elke configuratie die je opgeeft.

Omzeerweges en Oplossingen

Wat te doen? Methoden 1-2-3 werken, maar hebben beperkingen.

Methode 1. ad-hoc, werkt. Methode 2. hardcoded in model. Methode 3. vereist containerisatie en het plaatsen van je eigen app in de samenstelling. Dat is dichter bij productie.

Methode 1: Gebruik docker model configure (Beperkt)

Je kunt de contextgrootte configureren met de Docker Model CLI, die de configuratie opslaat in de modelmetadata van Docker:

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

Deze opdracht werkt de modelconfiguratie bij, maar de implementatie heeft aanzienlijke beperkingen. De configuratie wordt opgeslagen, maar wordt niet altijd correct toegepast.

Beperkingen:

  • Dit werkt niet wanneer je docker model run direct gebruikt, alleen via curl naar het API-eindpunt
  • Je kunt docker model run niet gebruiken na het configureren - het zal de configuratie negeren
  • De configuratie wordt genegeerd wanneer je docker-compose gebruikt met de docker/model-runner:latest-cuda-afbeelding
  • De configuratie kan verloren gaan wanneer het model wordt bijgewerkt of opnieuw wordt opgehaald

Deze methode werkt het beste voor testen met directe API-aanroepen, maar is niet geschikt voor productieimplementaties met docker-compose.

Methode 2: Pak je eigen model

De meest betrouwbare manier om een aangepaste contextgrootte in te stellen is om je eigen model te pakken met de gewenste contextgrootte met behulp van docker model package. Dit bakkeert de contextgrootte in de modelmetadata tijdens het pakken:

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

Dit maakt een nieuw OCI-artefact (gelijk aan een Docker-afbeelding) met de contextgrootte permanent ingesteld. Het gepakte model kan vervolgens worden geüpload naar Docker Hub of een andere OCI-compatibele register en op dezelfde manier worden opgehaald als een ander Docker Model Runner-model.

Echter, deze aanpak vereist:

  • Toegang tot het originele GGUF-modelbestand (de gequantiseerde vorm die wordt gebruikt door llama.cpp)
  • Herpakken elke keer dat je de contextgrootte wilt wijzigen, wat tijdsverbruikend kan zijn
  • Beheer van je eigen modelregister of Docker Hub-account
  • Kennis van de Docker Model Runner pakketworkflow

Deze methode is het beste geschikt voor productieomgevingen waar je consistente, herhaalbare contextgroottes nodig hebt over meerdere implementaties.

Methode 3: Docker Compose

Dit is momenteel gebroken voor docker/model-runner:latest-cuda

Maar voor je eigen app in de afbeelding kan het werken :)

Hoewel de syntaxis bestaat in 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

Dit werkt niet - de context_size-parameter wordt herkend door docker-compose, maar niet toegepast. Het model gebruikt nog steeds 4096 tokens.

Methode 4: Omgevingsvariabelen (Ook Gebroken)

Proberen om de MODEL_CONTEXT-omgevingsvariabele te gebruiken:

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

Dit werkt ook niet - de omgevingsvariabele wordt niet gerespecteerd wanneer je docker-compose gebruikt.

Contextgrootte Verifiëren

Om te controleren welke contextgrootte daadwerkelijk wordt gebruikt, inspecteer de logboeken:

# Controleer llama.cpp argumenten
docker compose logs 2>&1 | grep "llamaCppArgs"

# Controleer de daadwerkelijke contextgrootte
docker compose logs 2>&1 | grep -i "n_ctx" | tail -10

Je zult een uitvoer zien zoals:

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

Als je n_ctx = 4096 ziet ondanks het configureren van een ander waarde, wordt je configuratie genegeerd.

Contextgrootte Testen

Om te controleren of je configuratie van contextgrootte daadwerkelijk wordt toegepast, moet je testen met prompts die de standaardlimiet van 4096 tokens overschrijden. Hieronder volgt een praktische script met behulp van Python om te testen of je contextgrootteconfiguratie werkt:

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

# Test met grote 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

# Controleer tokengebruik
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("✅ Contextvenster is groter dan 4096!")
        else:
            print("⚠️ Contextvenster lijkt beperkt te zijn tot 4096")
PYTHON

Alternatieve Oplossingen

Als je meer flexibiliteit in het configureren van contextgrootte nodig hebt, overweeg dan deze alternatieven:

  • Ollama - Een alternatieve oplossing voor het hosten van LLM’s die betere controle biedt over contextgrootte en eenvoudigere configuratie. Ollama stelt je in staat om contextgrootte per model op te geven en heeft geen dezelfde docker-compose beperkingen.

  • Docker Model Runner vs Ollama vergelijking - Een gedetailleerde vergelijking van beide oplossingen, inclusief contextgrootteconfiguratiecapaciteiten, prestaties en wanneer je elk platform moet kiezen.

Gerelateerde Resources

Docker Model Runner

Docker en Infrastructuur

Alternatieve LLM-oplossingen

Officiële Documentatie

Conclusie

Het configureren van contextgrootte in Docker Model Runner is momenteel problematisch wanneer je docker-compose gebruikt. Hoewel de configuratiesyntaxis bestaat in de Docker Compose-specificatie, wordt deze niet correct geïmplementeerd in de docker/model-runner:latest-cuda-afbeelding, die een contextgrootte van 4096 tokens hardcode, ongeacht je configuratie.

De meest betrouwbare omzeerweg is om je eigen modellen te pakken met de gewenste contextgrootte met behulp van docker model package, hoewel dit complexiteit toevoegt aan je werkstroom en toegang vereist tot de originele GGUF-modelbestanden. Alternatief kun je docker model configure gebruiken voor directe API-toegang, maar dit werkt niet met docker-compose-implementaties.

Voor de meeste toepassingen is de standaard contextgrootte van 4096 tokens voldoende voor typische conversatie-AI-toepassingen. Als je grotere contextvensters of meer flexibiliteit in configuratie nodig hebt, overweeg dan Ollama als alternatief, wat betere controle over contextgrootte biedt zonder de docker-compose-beperkingen.

Je kunt VRAM-gebruik nog steeds optimaliseren via andere middelen zoals modelquantisatie (Q4, Q6, Q8) en GPU-laagconfiguratie (MODEL_GPU_LAYERS), die effectiever zijn voor het verminderen van geheugenverbruik dan aanpassingen van contextgrootte.

Voor meer informatie over GPU-optimalisatie en VRAM-beheer, zie onze gids over het configureren van NVIDIA GPU-ondersteuning.