Docker Model Runner: Przewodnik konfiguracji rozmiaru kontekstu

Konfigurowanie rozmiarów kontekstu w Docker Model Runner jest bardziej skomplikowane, niż powinno być.

Choć parametr context_size istnieje w konfiguracji docker-compose, często jest ignorowany przez obraz docker/model-runner:latest-cuda, który ustala domyślnie rozmiar kontekstu na 4096 tokenów. Niniejszy przewodnik omawia ograniczenia i przedstawia praktyczne sposoby obejścia.

To zdjęcie zostało wygenerowane przez Flux 1 dev.

Zrozumienie problemu

Podczas korzystania z Docker Model Runner wraz z docker-compose możesz skonfigurować rozmiar kontekstu w ten sposób:

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

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

Jednak sprawdzając logi, można zobaczyć rzeczywisty rozmiar kontekstu, który jest używany:

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

Zobaczysz wynik podobny do:

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

Obraz docker/model-runner:latest-cuda ustawia domyślnie --ctx-size 4096, ignorując Twoją konfigurację context_size: 10240.

Dlaczego to się dzieje

Rozmiar kontekstu (n_ctx) jest ustawiany w momencie inicjalizacji modelu w llama.cpp, który jest silnikiem wnioskowania używanym przez Docker Model Runner. To następuje podczas konstrukcji kontekstu modelu, zanim zostaną przetworzone żadne żądania API. Integracja Docker Model Runner z docker-compose wydaje się mieć błąd, w którym nieprawidłowo przekazuje parametr context_size z sekcji modeli do procesu llama.cpp. Zamiast tego, domyślnie ustawia rozmiar kontekstu na 4096 tokenów, niezależnie od Twojej konfiguracji.

To ograniczenie oznacza, że mimo iż Docker Compose rozpoznaje parametr context_size w Twojej konfiguracji YAML, obraz docker/model-runner:latest-cuda go nie uwzględnia podczas tworzenia argumentów wiersza poleceń dla llama.cpp. Ustalone --ctx-size 4096 mają pierwszeństwo nad każdą konfiguracją, którą określisz.

Sposoby obejścia i rozwiązania

Co zrobić? Metody 1-2-3 będą działać, ale mają ograniczenia.

Metoda 1. ad-hoc, będzie działać. Metoda 2. ustalona w modelu. Metoda 3. wymaga konteneryzacji i wstawienia własnej aplikacji do kompozycji. To jest bliższe produkcji.

Metoda 1: Użycie docker model configure (ograniczenia)

Możesz skonfigurować rozmiar kontekstu za pomocą CLI Docker Model, który przechowuje konfigurację w metadanych modelu Docker:

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

To polecenie aktualizuje konfigurację modelu, ale implementacja ma istotne ograniczenia. Konfiguracja jest przechowywana, ale nie zawsze jest poprawnie stosowana.

Ograniczenia:

• Nie działa, gdy używasz docker model run bezpośrednio, tylko przez wywołanie API za pomocą curl
• Nie możesz używać docker model run po skonfigurowaniu – zignoruje konfigurację
• Konfiguracja jest ignorowana, gdy używasz docker-compose z obrazem docker/model-runner:latest-cuda
• Konfiguracja może zostać utracona po aktualizacji lub ponownym pobraniu modelu

Ta metoda najlepiej nadaje się do testowania z bezpośrednimi wywołaniami API, ale nie jest odpowiednia do wdrożeń produkcyjnych z użyciem docker-compose.

Metoda 2: Umieszczenie własnego modelu

Najbardziej niezawodny sposób na ustawienie niestandardowego rozmiaru kontekstu to umieszczenie własnego modelu z pożądanym rozmiarem kontekstu za pomocą docker model package. To zapieka rozmiar kontekstu w metadanych modelu w momencie pakowania:

docker model package \
  --gguf /ścieżka/do/model.gguf \
  --context-size 10240 \
  --name my-model:custom-context

To tworzy nowy artefakt OCI (podobny do obrazu Docker) z trwale skonfigurowanym rozmiarem kontekstu. Pakowany model może być następnie wypchnięty do Docker Hub lub dowolnego kompatybilnego z OCI rejestru i pobrany jak każdy inny model Docker Model Runner.

Jednak ten sposób wymaga:

• Dostępu do oryginalnego pliku modelu GGUF (formatu używanego przez llama.cpp)
• Ponownego pakowania za każdym razem, gdy chcesz zmienić rozmiar kontekstu, co może być czasochłonne
• Zarządzania własnym rejestrem modeli lub kontem Docker Hub
• Zrozumienia przepływu pracy pakowania Docker Model Runner

Ta metoda jest najlepsza do środowisk produkcyjnych, gdzie potrzebujesz spójnych, powtarzalnych rozmiarów kontekstu w różnych wdrożeniach.

Metoda 3: Docker Compose

To obecnie nie działa dla docker/model-runner:latest-cuda

Ale może działać dla własnej aplikacji w obrazie :)

Choć składnia istnieje w 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

To nie działa – parametr context_size jest rozpoznawany przez docker-compose, ale nie jest stosowany. Model nadal używa 4096 tokenów.

Metoda 4: Zmienne środowiskowe (również nie działają)

Próba użycia zmiennej środowiskowej MODEL_CONTEXT:

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

To również nie działa – zmienna środowiskowa nie jest stosowana podczas użycia docker-compose.

Sprawdzanie rozmiaru kontekstu

Aby sprawdzić, jaki rozmiar kontekstu faktycznie jest używany, sprawdź logi:

# Sprawdź argumenty llama.cpp
docker compose logs 2>&1 | grep "llamaCppArgs"

# Sprawdź rzeczywisty rozmiar kontekstu
docker compose logs 2>&1 | grep -i "n_ctx" | tail -10

Zobaczysz wynik podobny do:

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

Jeśli zobaczysz n_ctx = 4096, mimo że skonfigurowałeś inny rozmiar, Twoja konfiguracja jest ignorowana.

Testowanie rozmiaru kontekstu

Aby sprawdzić, czy konfiguracja rozmiaru kontekstu faktycznie jest stosowana, musisz przetestować z wywołaniami, które przekraczają domyślny limit 4096 tokenów. Oto praktyczny skrypt korzystający z Pythona do testowania, czy konfiguracja rozmiaru kontekstu działa:

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

# Test z dużym promptem
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

# Sprawdź użycie tokenów
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("✅ Rozmiar okna kontekstu jest większy niż 4096!")
        else:
            print("⚠️ Rozmiar okna kontekstu wydaje się ograniczony do 4096")
PYTHON

Alternatywne rozwiązania

Jeśli potrzebujesz bardziej elastycznego konfigurowania rozmiarów kontekstu, rozważ następujące alternatywy:

• Ollama – alternatywna metoda hostowania LLM, która oferuje lepszy kontrolę nad rozmiarami kontekstu i prostsze konfiguracje. Ollama pozwala określić rozmiar kontekstu dla każdego modelu i nie ma tych samych ograniczeń związanych z docker-compose.

• Porównanie Docker Model Runner z Ollama – szczegółowe porównanie obu rozwiązań, w tym możliwości konfiguracji rozmiarów kontekstu, wydajność i kiedy wybrać każdy z platform.

Powiązane zasoby

Docker Model Runner

• Docker Model Runner Cheatsheet – kompletny przewodnik z przykładami dla wszystkich operacji związanych z Docker Model Runner
• Dodanie wsparcia dla GPU NVIDIA do Docker Model Runner – krok po kroku przewodnik po włączaniu przyspieszenia GPU
• Docker Model Runner vs Ollama: Który wybrać?

Docker i infrastruktura

• Docker Cheatsheet – istotne polecenia Docker do zarządzania kontenerami
• Docker Compose Cheatsheet – kompletny przewodnik po konfiguracji i poleceniach Docker Compose

Alternatywne rozwiązania LLM

• Ollama Cheatsheet – alternatywna metoda hostowania LLM z wbudowanym wsparciem dla GPU i prostszym konfigurowaniem rozmiarów kontekstu
• Integracja Ollama z Pythonem

Dokumentacja oficjalna

• Dokumentacja Docker Model Runner – oficjalna dokumentacja Docker dla Model Runner
• Konfiguracja kontekstu w llama.cpp – dokumentacja silnika wnioskowania

Podsumowanie

Konfigurowanie rozmiarów kontekstu w Docker Model Runner jest obecnie problematyczne przy użyciu docker-compose. Choć składnia konfiguracji istnieje w specyfikacji Docker Compose, nie jest poprawnie zaimplementowana w obrazie docker/model-runner:latest-cuda, który ustala domyślnie rozmiar kontekstu na 4096 tokenów, niezależnie od Twojej konfiguracji.

Najbardziej niezawodny sposób obejścia to pakowanie własnych modeli z pożądanym rozmiarem kontekstu za pomocą docker model package, choć to dodaje złożoność do Twojego przepływu pracy i wymaga dostępu do oryginalnych plików modelu GGUF. Alternatywnie możesz użyć docker model configure do bezpośredniego dostępu do API, ale to nie działa w wdrożeniach docker-compose.

Dla większości przypadków użycia domyślny rozmiar kontekstu 4096 tokenów jest wystarczający dla typowych aplikacji AI. Jeśli potrzebujesz większych okien kontekstu lub bardziej elastycznej konfiguracji, rozważ użycie Ollama jako alternatywy, która oferuje lepszą kontrolę nad rozmiarami kontekstu bez ograniczeń związanych z docker-compose.

Możesz nadal optymalizować użycie VRAM poprzez inne metody, takie jak kwantyzacja modelu (Q4, Q6, Q8) i konfiguracja warstw GPU (MODEL_GPU_LAYERS), które są bardziej skuteczne w redukowaniu zużycia pamięci niż dostosowania rozmiaru kontekstu.

Aby uzyskać więcej informacji na temat optymalizacji GPU i zarządzania VRAM, zobacz nasz przewodnik dotyczący konfiguracji wsparcia dla GPU NVIDIA.