Docker Model Runner: Gids voor het configureren van contextgrootte

Stel contextgroottes in in Docker Model Runner met omzeilingen

Inhoud

Het instellen 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 omzeerstrategieën. Voor een breder overzicht van Docker Model Runner in vergelijking met Ollama, vLLM, LocalAI en cloudproviders—met inbegrip van configuratie- en infrastructuurcompromissen—zie LLM Hosting: Lokale, zelfgehoste en cloudinfrastructuur vergeleken.

configureren auto Deze afbeelding is gegenereerd door Flux 1 dev.

Het probleem begrijpen

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

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 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 het initialiseren van het model in llama.cpp, het onderliggende inferentie-engine dat Docker Model Runner gebruikt. Dit gebeurt tijdens de fase van contextconstructie van het model, voor het verwerken van enige API-aanvragen. De compose-integratie van Docker Model Runner lijkt een bug te hebben waarbij het de context_size-parameter niet correct doorgeeft vanuit de modellensectie naar het onderliggende llama.cpp-proces. In plaats daarvan wordt 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 de command-line-argumenten van llama.cpp worden opgebouwd. De hardcoded --ctx-size 4096-vlag heeft voorrang boven elke configuratie die je opgeeft.

Omzeerstrategieën en oplossingen

Wat moet je dan doen? Methoden 1-2-3 werken, maar hebben beperkingen.

Methode 1. ad-hoc, werkt. Methode 2. hardcoded in het 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 instellen 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 significante 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 bij testen met directe API-aanroepen, maar is niet geschikt voor productiedeployments met docker-compose.

Methode 2: Verpak je eigen model

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

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

Dit creëert een nieuw OCI-artefact (gelijk aan een Docker-afbeelding) met de contextgrootte permanent ingesteld. Het verpakte model kan vervolgens worden gepusht naar Docker Hub of een andere OCI-compatibele registratie en wordt opgehaald zoals elk ander Docker Model Runner-model.

Echter, deze aanpak vereist:

  • Toegang tot de originele GGUF-modelbestand (de gequantiseerde indeling die wordt gebruikt door llama.cpp)
  • Herverpakken elke keer dat je de contextgrootte wilt wijzigen, wat tijdrovend kan zijn
  • Beheer van je eigen modelregistratie of Docker Hub-account
  • Kennis van de verpakkingswerkstroom van Docker Model Runner

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

Methode 3: Docker Compose

Dit is momenteel beschadigd 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 beschadigd)

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 docker-compose wordt gebruikt.

Contextgrootte controleren

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 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 instellen van een andere waarde, wordt je configuratie genegeerd.

Contextgrootte testen

Om te controleren of je configuratie voor contextgrootte daadwerkelijk wordt toegepast, moet je testen met prompts die de standaardlimiet van 4096 tokens overschrijden. Hieronder volgt een praktisch script dat gebruikmaakt van Python om te testen of je configuratie 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 instellen 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 in te stellen en heeft geen dezelfde docker-compose beperkingen.

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

Om te zien hoe Docker Model Runner past bij andere lokale en cloudopties, zie onze gids LLM Hosting: Lokale, zelfgehoste en cloudinfrastructuur vergeleken.

Gerelateerde bronnen

Docker Model Runner

Docker en infrastructuur

Alternatieve LLM-oplossingen

Officiële documentatie

Conclusie

Het instellen van contextgrootte in Docker Model Runner is momenteel problematisch wanneer docker-compose wordt 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 hardcoded, ongeacht je configuratie.

De meest betrouwbare omzeerstrategie is om je eigen modellen te verpakken met de gewenste contextgrootte via 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 flexibele configuratie nodig hebt, overweeg dan Ollama als alternatief, wat betere controle over contextgrootte biedt zonder de docker-compose-beperkingen.

Je kunt nog steeds VRAM-gebruik 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 instellen van NVIDIA GPU-ondersteuning.