Docker Model Runner Cheatsheet: Polecenia i Przykłady

Szybki przewodnik po poleceniach Docker Model Runner

Docker Model Runner (DMR) to oficjalne rozwiązanie firmy Docker do uruchamiania modeli AI lokalnie, wprowadzone w kwietniu 2025 roku. Ten cheatsheet zawiera szybki przewodnik po wszystkich istotnych komendach, konfiguracjach i najlepszych praktykach.

lista dostępnych modeli gemma w docker model runner

Instalacja

Docker Desktop

Włącz Docker Model Runner przez interfejs graficzny:

  1. Otwórz Docker Desktop
  2. Przejdź do Ustawienia → Karta AI
  3. Kliknij Włącz Docker Model Runner
  4. Uruchom ponownie Docker Desktop

/home/rg/prj/hugo-pers/content/post/2025/10/docker-model-runner-cheatsheet/docker-model-runner_w678.jpg docker model runner windows

Docker Engine (Linux)

Zainstaluj pakiet wtyczki:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker-model-plugin

# Fedora/RHEL
sudo dnf install docker-model-plugin

# Arch Linux
sudo pacman -S docker-model-plugin

Sprawdź instalację:

docker model --help

Obsługa NVIDIA RTX dla Docker

Aby włączyć uruchamianie LLM na GPU zamiast CPU, zainstaluj nvidia-container-toolkit:

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

następnie możesz uruchomić kontenery z --gpus all

docker run --rm --gpus all <image> <command>

sprawdź, czy kontener może zobaczyć GPU:

docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubi8 nvidia-smi

Dodanie wsparcia NVIDIA dla Docker Model Runner

Docker Model Runner wymaga jawnej konfiguracji GPU. W przeciwieństwie do standardowych komend docker run, docker model run nie obsługuje flag --gpus ani -e. Zamiast tego musisz:

  1. Skonfigurować demon Docker do użycia domyślnie środowiska uruchomieniowego NVIDIA

Najpierw sprawdź, gdzie został zainstalowany nvidia-container-runtime:

which nvidia-container-runtime

Wynik będzie zwykle /usr/bin/nvidia-container-runtime. Użyj tej ścieżki w konfiguracji poniżej.

Utwórz lub zaktualizuj /etc/docker/daemon.json:

sudo tee /etc/docker/daemon.json > /dev/null << 'EOF'
{
  "default-runtime": "nvidia",
  "runtimes": {
    "nvidia": {
      "path": "/usr/bin/nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}
EOF

Uwaga: Jeśli which nvidia-container-runtime zwraca inną ścieżkę, zaktualizuj wartość "path" w konfiguracji JSON odpowiednio.

Uruchom ponownie Docker:

sudo systemctl restart docker

Sprawdź konfigurację:

docker info | grep -i runtime

W wyniku powinien zostać wyświetlony Default Runtime: nvidia.

  1. Ponowna instalacja Docker Model Runner z obsługą GPU

Docker Model Runner musi zostać zainstalowany/ponownie zainstalowany z jawną obsługą GPU:

# Zatrzymaj bieżącego runnera
docker model stop-runner

# Ponownie zainstaluj z obsługą GPU CUDA
docker model reinstall-runner --gpu cuda

To pociągnie wersję z obsługą CUDA (docker/model-runner:latest-cuda) zamiast wersji tylko dla CPU.

  1. Sprawdzenie dostępu do GPU

Sprawdź, czy kontener Docker Model Runner może uzyskać dostęp do GPU:

docker exec docker-model-runner nvidia-smi
  1. Test modelu z użyciem GPU

Uruchom model i sprawdź logi, aby potwierdzić użycie GPU:

docker model run ai/qwen3:14B-Q6_K "who are you?"

Sprawdź logi w celu potwierdzenia użycia GPU:

docker model logs | grep -i cuda

W logach powinny się znaleźć komunikaty takie jak:

  • using device CUDA0 (NVIDIA GeForce RTX 4080)
  • offloaded 41/41 layers to GPU
  • CUDA0 model buffer size = 10946.13 MiB

Uwaga: Jeśli już zainstalowałeś Docker Model Runner bez wsparcia GPU, musisz go ponownie zainstalować z użyciem flagi --gpu cuda. Proste skonfigurowanie demona Docker nie wystarczy – sam kontener runnera musi być wersją z obsługą CUDA.

Dostępne backendy GPU:

  • cuda - NVIDIA CUDA (najczęstszy)
  • rocm - AMD ROCm
  • musa - Moore Threads MUSA
  • cann - Huawei CANN
  • auto - automatyczne wykrywanie (domyślne)
  • none - tylko CPU

Podstawowe polecenia

Pobieranie modeli

Pobierz wstępnie zapakowane modele z Docker Hub:

# Podstawowe pobranie
docker model pull ai/llama2

# Pobierz określoną wersję
docker model pull ai/llama2:7b-q4

# Pobierz z niestandardowego rejestru
docker model pull myregistry.com/models/mistral:latest

# Lista dostępnych modeli w przestrzeni nazw
docker search ai/

Uruchamianie modeli

Uruchom model z automatycznym serwisem API:

# Podstawowe uruchomienie (interaktywne)
docker model run ai/llama2 "What is Docker?"

# Uruchom jako usługę (w tle)
docker model run -d

ogólnie mamy niewiele opcji uruchamiania modeli przez CLI:

docker model run --help
Usage:  docker model run MODEL [PROMPT]

Uruchom model i interakcjonuj z nim za pomocą podanego promptu lub trybu czatu

Opcje:
      --color string                  Użyj kolorowego wyjścia (auto|yes|no) (domyślnie "auto")
      --debug                         Włącz logowanie debugowania
  -d, --detach                        Załaduj model w tle bez interakcji
      --ignore-runtime-memory-check   Nie blokuj pobierania, jeśli szacowana pamięć uruchomieniowa modelu przekracza zasoby systemowe.

Lista modeli

Wyświetl pobrane i uruchomione modele:

# Lista wszystkich pobranych modeli
docker model ls

# Lista uruchomionych modeli
docker model ps

# Lista z szczegółowymi informacjami
docker model ls --json

# Lista z szczegółowymi informacjami
docker model ls --openai

# Zwróci hashe
docker model ls -q

Usuwanie modeli

Usuń modele z lokalnego magazynu:

# Usuń określony model
docker model rm ai/llama2

# Usuń z siłą (nawet jeśli działa)
docker model rm -f ai/llama2

# Usuń nieużywane modele
docker model prune

# Usuń wszystkie modele
docker model rm $(docker model ls -q)

Konfigurowanie rozmiarów kontekstu modeli

Nie możemy używać CLI do określenia rozmiaru kontekstu dla konkretnego żądania.

W zasadzie możemy kontrolować rozmiar kontekstu modelu tylko trzema sposobami:

  1. Pakuj model samodzielnie, określając pożądaną, zapisaną w pamięci rozmiar kontekstu (Zobacz więcej na ten temat w kolejnym sekcji.)

  2. Gdy używasz docker model runner, skonfiguruj polecenie z parametrem –context-size, np.

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

Następnie możesz wywołać curl do niego, ale nie możesz wykonać docker model run... - to zignoruje konfigurację.

  1. W pliku docker-compose.yaml, ale nie możemy używać obrazu docker-model-runner w ten sposób, ponieważ przekazuje do modelu zapisany w pamięci rozmiar kontekstu 4096
...
models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240
...

Aby uzyskać więcej szczegółów, zobacz dedykowany wpis na ten temat: Określanie rozmiaru kontekstu w DMR

Pakowanie niestandardowych modeli

Tworzenie artefaktu OCI z GGUF

Pakuj własne modele GGUF:

# Podstawowe pakowanie
docker model package --gguf /path/to/model.gguf myorg/mymodel:latest

# Pakuj z metadanymi
docker model package \
  --gguf /path/to/model.gguf \
  --label "description=Custom Llama model" \
  --label "version=1.0" \
  myorg/mymodel:v1.0

# Pakuj i przesyłaj w jednym poleceniu
docker model package --gguf /path/to/model.gguf --push myorg/mymodel:latest

# Pakuj z niestandardowym rozmiarem kontekstu
docker model package \
  --gguf /path/to/model.gguf \
  --context 8192 \
  myorg/mymodel:latest

Publikowanie modeli

Przesyłaj modele do rejestrów:

# Zaloguj się do Docker Hub
docker login

# Przesyłaj do Docker Hub
docker model push myorg/mymodel:latest

# Przesyłaj do prywatnego rejestru
docker login myregistry.com
docker model push myregistry.com/models/mymodel:latest

# Oznacz i przesyłaj
docker model tag mymodel:latest myorg/mymodel:v1.0
docker model push myorg/mymodel:v1.0

Użycie API

Kompatybilne z OpenAI punkty końcowe

Docker Model Runner automatycznie udostępnia punkty końcowe kompatybilne z OpenAI:

# Uruchom model z API
docker model run -d -p 8080:8080 --name llm ai/llama2

# Kompletacja rozmowy
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# Generowanie tekstu
curl http://localhost:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "prompt": "Once upon a time",
    "max_tokens": 100
  }'

# Strumieniowa odpowiedź
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Tell me a story"}],
    "stream": true
  }'

# Lista dostępnych modeli przez API
curl http://localhost:8080/v1/models

# Informacje o modelu
curl http://localhost:8080/v1/models/llama2

Konfiguracja Docker Compose

Podstawowy plik Compose

version: '3.8'

services:
  llm:
    image: docker-model-runner
    model: ai/llama2:7b-q4
    ports:
      - "8080:8080"
    environment:
      - MODEL_TEMPERATURE=0.7
    volumes:
      - docker-model-runner-models:/models
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  docker-model-runner-models:
    external: true

Konfiguracja wielu modeli

version: '3.8'

services:
  llama:
    image: docker-model-runner
    model: ai/llama2
    ports:
      - "8080:8080"
    
  mistral:
    image: docker-model-runner
    model: ai/mistral
    ports:
      - "8081:8080"
    
  embedding:
    image: docker-model-runner
    model: ai/nomic-embed-text
    ports:
      - "8082:8080"

Aby uzyskać bardziej zaawansowane konfiguracje Docker Compose i polecenia, zobacz nasz Docker Compose Cheatsheet obejmujący sieci, woluminy i wzorce orkestracji.

Zmienne środowiskowe

Konfiguruj zachowanie modelu za pomocą zmiennych środowiskowych:

# Temperatura (0.0-1.0)
MODEL_TEMPERATURE=0.7

# Top-p sampling
MODEL_TOP_P=0.9

# Top-k sampling
MODEL_TOP_K=40

# Maksymalna liczba tokenów
MODEL_MAX_TOKENS=2048

# Liczba warstw GPU
MODEL_GPU_LAYERS=35

# Wielkość partii
MODEL_BATCH_SIZE=512

# Liczba wątków (CPU)
MODEL_THREADS=8

# Włącz szczegółowe logowanie
MODEL_VERBOSE=true

# Klucz API do uwierzytelnienia
MODEL_API_KEY=your-secret-key

Uruchom z użyciem zmiennych środowiskowych:

docker model run \
  -e MODEL_TEMPERATURE=0.8 \
  -e MODEL_API_KEY=secret123 \
  ai/llama2

Konfiguracja GPU

Automatyczne wykrywanie GPU

DMR automatycznie wykrywa i używa dostępnych GPU:

# Użyj wszystkich GPU
docker model run --gpus all ai/llama2

# Użyj określonego GPU
docker model run --gpus 0 ai/llama2

# Użyj wielu określonych GPU
docker model run --gpus 0,1,2 ai/llama2

# GPU z ograniczeniem pamięci
docker model run --gpus all --memory 16g ai/llama2

Tryb tylko CPU

Wymuś inferencję na CPU, mimo że GPU jest dostępne:

docker model run --no-gpu ai/llama2

Tensorowe równoległość wielu GPU

Rozdziel duże modele na GPU:

docker model run \
  --gpus all \
  --tensor-parallel 2 \
  ai/llama2-70b

Inspekcja i debugowanie

Wyświetlanie szczegółów modelu

# Inspekcja konfiguracji modelu
docker model inspect ai/llama2

# Wyświetlanie warstw modelu
docker model history ai/llama2

# Sprawdzenie rozmiaru modelu i metadanych
docker model inspect --format='{{.Size}}' ai/llama2

Logi i monitorowanie

# Wyświetlanie logów modelu
docker model logs llm

# Monitorowanie logów w czasie rzeczywistym
docker model logs -f llm

# Wyświetlanie ostatnich 100 linii
docker model logs --tail 100 llm

# Wyświetlanie logów z czasem
docker model logs -t llm

Statystyki wydajności

# Użycie zasobów
docker model stats

# Statystyki konkretnego modelu
docker model stats llm

# Statystyki w formacie JSON
docker model stats --format json

Sieci

Wyświetlanie API

# Domyślny port (8080)
docker model run -p 8080:8080 ai/llama2

# Niestandardowy port
docker model run -p 3000:8080 ai/llama2

# Przypnij do określonego interfejsu
docker model run -p 127.0.0.1:8080:8080 ai/llama2

# Wiele portów
docker model run -p 8080:8080 -p 9090:9090 ai/llama2

Konfiguracja sieci

# Utwórz niestandardową sieć
docker network create llm-network

# Uruchom model na niestandardowej sieci
docker model run --network llm-network --name llm ai/llama2

# Połącz z istniejącą siecią
docker model run --network host ai/llama2

Bezpieczeństwo

Kontrola dostępu

# Uruchom z uwierzytelnieniem API
docker model run \
  -e MODEL_API_KEY=my-secret-key \
  ai/llama2

# Użyj z uwierzytelnieniem
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama2", "messages": [...]}'

Uwierzytelnienie w rejestrze

# Zaloguj się do prywatnego rejestru
docker login myregistry.com -u username -p password

# Pobierz z prywatnego rejestru
docker model pull myregistry.com/private/model:latest

# Użyj pomocnika do poświadczeń
docker login --password-stdin < token.txt

Najlepsze praktyki

Wybór modelu

# Użyj modeli z kwantyzacją dla szybszej inferencji
docker model pull ai/llama2:7b-q4     # kwantyzacja 4-bit
docker model pull ai/llama2:7b-q5     # kwantyzacja 5-bit
docker model pull ai/llama2:7b-q8     # kwantyzacja 8-bit

# Sprawdź wersje modelu
docker search ai/llama2

Zarządzanie zasobami

# Ustaw ograniczenia pamięci
docker model run --memory 8g --memory-swap 16g ai/llama2

# Ustaw ograniczenia CPU
docker model run --cpus 4 ai/llama2

# Ogranicz pamięć GPU
docker model run --gpus all --gpu-memory 8g ai/llama2

Sprawdzanie stanu

# Uruchom z sprawdzaniem stanu
docker model run \
  --health-cmd "curl -f http://localhost:8080/health || exit 1" \
  --health-interval 30s \
  --health-timeout 10s \
  --health-retries 3 \
  ai/llama2

Orchestracja w środowisku produkcyjnym

Dla wdrożeń produkcyjnych z Kubernetes, kontenery Docker Model Runner mogą być orkestrowane za pomocą standardowych manifestów Kubernetes. Zdefiniuj wdrożenia z ograniczeniami zasobów, autoskalowaniem i bilansowaniem obciążenia. Aby uzyskać kompleksowy przewodnik po poleceniach Kubernetes i wzorcach wdrożeń, sprawdź nasz Kubernetes Cheatsheet.

# Przykład: Wdrożenie w klastrze Kubernetes
kubectl apply -f llm-deployment.yaml

# Skalowanie wdrożenia
kubectl scale deployment llm --replicas=3

# Wyeksponuj jako usługę
kubectl expose deployment llm --type=LoadBalancer --port=8080

Rozwiązywanie problemów

Typowe problemy

Model nie uruchamia się:

# Sprawdź dostępne miejsce na dysku
df -h

# Wyświetl szczegółowe logi błędów
docker model logs --tail 50 llm

# Sprawdź dostępność GPU
nvidia-smi  # Dla GPU NVIDIA

Błędy braku pamięci:

# Użyj mniejszego modelu z kwantyzacją
docker model pull ai/llama2:7b-q4

# Zmniejsz rozmiar kontekstu
docker model run -e MODEL_CONTEXT=2048 ai/llama2

# Ogranicz wielkość partii
docker model run -e MODEL_BATCH_SIZE=256 ai/llama2

Wolna inferencja:

# Sprawdź użycie GPU
docker model stats llm

# Upewnij się, że GPU jest używane
docker model logs llm | grep -i gpu

# Zwiększ liczbę warstw GPU
docker model run -e MODEL_GPU_LAYERS=40 ai/llama2

Polecenia diagnostyczne

# Informacje systemowe
docker model system info

# Użycie dysku
docker model system df

# Wyczyszczenie nieużywanych zasobów
docker model system prune

# Pełne wyczyszczenie (usunięcie wszystkich modeli)
docker model system prune -a

Przykłady integracji

Integracja w Pythonie

import openai

# Skonfiguruj klienta dla Docker Model Runner
client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # DMR nie wymaga klucza domyślnie
)

# Kompletacja rozmowy
response = client.chat.completions.create(
    model="llama2",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

print(response.choices[0].message.content)

# Strumieniowe przesyłanie
stream = client.chat.completions.create(
    model="llama2",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Skrypt Bash

#!/bin/bash

# Uruchom model, jeśli nie działa
if ! docker model ps | grep -q "llm"; then
    docker model run -d --name llm -p 8080:8080 ai/llama2
    echo "Oczekiwanie na uruchomienie modelu..."
    sleep 10
fi

# Wykonaj wywołanie API
curl -s http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "'"$1"'"}]
  }' | jq -r '.choices[0].message.content'

Integracja w Node.js

import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'http://localhost:8080/v1',
    apiKey: 'not-needed'
});

async function chat(message) {
    const completion = await client.chat.completions.create({
        model: 'llama2',
        messages: [{ role: 'user', content: message }]
    });
    
    return completion.choices[0].message.content;
}

// Użycie
const response = await chat('Co to jest Docker Model Runner?');
console.log(response);

Przydatne linki

Oficjalna dokumentacja

Powiązane cheatsheety

Porównania artykułów