Docker Model Runner: Guide för inställning av kontextstorlek

Konfigurera kontextstorlek i Docker Model Runner är mer komplex än det borde vara.

Även om parametern context_size finns i docker-compose-konfigurationen, ignoreras den ofta av bilden docker/model-runner:latest-cuda, som har en hårdkodad kontextstorlek på 4096 token. Den här guiden undersöker begränsningarna och ger praktiska lösningar. För en bredare jämförelse mellan Docker Model Runner och Ollama, vLLM, LocalAI samt molntjänstleverantörer – inklusive konfigurations- och infrastrukturtrade-offar – se LLM Hosting: Lokal, självvärd och molninfrastruktur jämförd.

Detta bild genererades av Flux 1 dev.

Förstå problemet

När du använder Docker Model Runner med docker-compose kan du konfigurera kontextstorlek så här:

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

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

Men genom att kontrollera loggarna ser du den faktiska kontextstorlek som används:

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

Du kommer att se utdata som:

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

Bilden docker/model-runner:latest-cuda hårdkoder --ctx-size 4096 när den anropar llama.cpp, och ignorerar helt ditt context_size: 10240-konfigurationsalternativ.

Varför Det Händer

Kontextstorleken (n_ctx) anges vid modellens initieringstid i llama.cpp, det underliggande inferensmotorn som Docker Model Runner använder. Detta sker under modellens kontextbyggfase, innan några API-begäran hanteras. Docker Model Runner:s kompositionssammanhang verkar ha ett fel där den inte korrekt skickar vidare context_size-parametern från modellavsnittet till den underliggande llama.cpp-processen. Istället används alltid 4096 token oavsett konfiguration.

Denna begränsning innebär att även om Docker Compose identifierar context_size-parametern i din YAML-konfiguration, så ignorerar bilden docker/model-runner:latest-cuda den när den bygger llama.cpp-kommandoradargumenten. Den hårdkodade --ctx-size 4096-flaggan tar över för någon konfiguration du anger.

Arbetssätt och lösningar

Vad ska du göra? Metoderna 1-2-3 kommer att fungera, men de har begränsningar.

Metod 1. ad-hoc, kommer att fungera. Metod 2. hårdkodad i modellen. Metod 3. kräver containerisering och att du lägger till din egen app i kompositionen. Det är närmare produktion.

Metod 1: Använd docker model configure (Begränsad)

Du kan konfigurera kontextstorlek med Docker Model CLI, vilket lagrar konfigurationen i Dockers modellmetadata:

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

Detta kommando uppdaterar modellens konfiguration, men implementeringen har betydande begränsningar. Konfigurationen lagras men tillämpas inte alltid korrekt.

Begränsningar:

• Detta fungerar inte när du använder docker model run direkt, endast via curl till API-slutpunkten
• Du kan inte använda docker model run efter konfiguration – den kommer att ignorera konfigurationen
• Konfigurationen ignoreras när du använder docker-compose med bilden docker/model-runner:latest-cuda
• Konfigurationen kan gå förlorad när modellen uppdateras eller laddas ner igen

Detta sätt fungerar bäst för testning med direkt API-anrop, men är inte lämpligt för produktionssystem som använder docker-compose.

Metod 2: Packa din egen modell

Den mest pålitliga metoden att ställa in en anpassad kontextstorlek är att packa din egen modell med önskad kontextstorlek med hjälp av docker model package. Detta bakar in kontextstorleken i modellens metadata vid förpackningstid:

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

Detta skapar ett nytt OCI-objekt (likt en Docker-bild) med kontextstorleken permanent konfigurerad. Den förpackade modellen kan sedan pushas till Docker Hub eller någon OCI-kompatibel register och laddas ner som någon annan Docker Model Runner-modell.

Men detta sätt kräver:

• Åtkomst till den ursprungliga GGUF-modelfilen (den kvantiseringsspecifika formatet som används av llama.cpp)
• Förpackning varje gång du vill ändra kontextstorlek, vilket kan vara tidskrävande
• Hantering av din egen modellregister eller Docker Hub-konto
• Förståelse av Docker Model Runner förpackningsflöde

Detta sätt är bäst lämpat för produktionsmiljöer där du behöver konsekventa, återproducerbara kontextstorlekar över distributioner.

Metod 3: Docker Compose

Detta är för närvarande trasigt för docker/model-runner:latest-cuda

Men för din egen app i bilden kan det fungera :)

Även om syntaxen finns i 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

Detta fungerar inte – context_size-parametern identifieras av docker-compose men tillämpas inte. Modellen använder fortfarande 4096 token.

Metod 4: Miljövariabler (Också trasiga)

Försök att använda miljövariabeln MODEL_CONTEXT:

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

Detta fungerar inte heller – miljövariabeln ignoreras när du använder docker-compose.

Verifiera kontextstorlek

För att kontrollera vilken kontextstorlek som faktiskt används, undersök loggarna:

# Kontrollera llama.cpp argument
docker compose logs 2>&1 | grep "llamaCppArgs"

# Kontrollera faktisk kontextstorlek
docker compose logs 2>&1 | grep -i "n_ctx" | tail -10

Du kommer att se utdata som:

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

Om du ser n_ctx = 4096 trots att du konfigurerat en annan värde, ignoreras din konfiguration.

Testa kontextstorlek

För att bekräfta om din kontextstorlek konfiguration faktiskt tillämpas, måste du testa med frågor som överskrider standarden 4096-tokengräns. Här är ett praktiskt skript som använder Python för att testa om din kontextstorlek konfiguration fungerar:

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

# Testa med stor 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

# Kontrollera tokenanvändning
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("✅ Kontextfönstret är större än 4096!")
        else:
            print("⚠️ Kontextfönstret verkar begränsas till 4096")
PYTHON

Alternativa lösningar

Om du behöver mer flexibel kontextstorlek konfiguration, överväg dessa alternativ:

• Ollama – Ett alternativ LLM-hostningssystem som ger bättre kontroll över kontextstorlekar och enklare konfiguration. Ollama låter dig ange kontextstorlek per modell och har inte samma docker-compose-begränsningar.

• Jämförelse mellan Docker Model Runner och Ollama – En detaljerad jämförelse av båda lösningarna, inklusive kontextstorlek konfigurationsförmåga, prestanda och när du ska välja varje plattform.

För att se hur Docker Model Runner passar in med andra lokala och molnalternativ, se vår LLM Hosting: Lokal, självvärd och molninfrastruktur jämförd-guide.

Relaterade resurser

Docker Model Runner

• Docker Model Runner Cheatsheet – Komplett kommandoreferens med exempel för alla Docker Model Runner-åtgärder
• Lägg till NVIDIA GPU-stöd i Docker Model Runner – Steg-för-steg-guide för att aktivera GPU-accellerering
• Docker Model Runner vs Ollama: Vilket ska du välja?

Docker och infrastruktur

• Docker Cheatsheet – Essentiella docker-kommandon för behållarhantering
• Docker Compose Cheatsheet – Komplett guide till Docker Compose-konfiguration och kommandon

Alternativa LLM-lösningar

• Ollama Cheatsheet – Alternativ LLM-hostningssystem med inbyggt GPU-stöd och enklare kontextstorlek konfiguration
• Integrera Ollama med Python

Officiell dokumentation

• Docker Model Runner Dokumentation – Officiell Docker-dokumentation för Model Runner
• llama.cpp Kontextkonfiguration – Dokumentation för den underliggande inferensmotorn

Slutsats

Konfigurera kontextstorlekar i Docker Model Runner är för närvarande problematiskt när du använder docker-compose. Även om konfigurationsyntaxen finns i Docker Compose-specifikationen, är den inte korrekt implementerad i bilden docker/model-runner:latest-cuda, som har en hårdkodad kontextstorlek på 4096 token oavsett din konfiguration.

Den mest pålitliga lösningen är att förpacka dina egna modeller med önskad kontextstorlek med hjälp av docker model package, även om detta lägger till komplexitet i din arbetsflöde och kräver åtkomst till de ursprungliga GGUF-modelfilerna. Alternativt kan du använda docker model configure för direkt API-åtkomst, men detta fungerar inte med docker-compose-distributioner.

För de flesta användningssyften är standardkontextstorleken på 4096 token tillräcklig för typiska konversationella AI-program. Om du behöver större kontextfönster eller mer flexibel konfiguration, överväg att använda Ollama som alternativ, vilket ger bättre kontroll över kontextstorlekar utan docker-compose-begränsningar.

Du kan fortfarande optimera VRAM-användning genom andra sätt som modellkvantisering (Q4, Q6, Q8) och GPU-lagerkonfiguration (MODEL_GPU_LAYERS), vilka är mer effektiva för att minska minnesanvändning än kontextstorleksjusteringar.

För mer information om GPU-optimering och VRAM-hantering, se vår guide om konfigurera NVIDIA GPU-stöd.