Шпаргалка Docker Model Runner: команды и примеры

Справочник команд Docker Model Runner

Docker Model Runner (DMR) — это официальное решение Docker для запуска моделей ИИ локально, представленное в апреле 2025 года. Этот справочник предоставляет быстрый доступ ко всем основным командам, настройкам и лучшим практикам.

список моделей gemma, доступных в docker model runner

Установка

Docker Desktop

Включите Docker Model Runner через графический интерфейс:

  1. Откройте Docker Desktop
  2. Перейдите в Настройки → вкладка AI
  3. Нажмите Включить Docker Model Runner
  4. Перезапустите 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)

Установите пакет плагина:

# 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

Проверьте установку:

docker model --help

Поддержка NVIDIA RTX для Docker

Чтобы запускать LLMs на GPU вместо CPU, установите 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

затем вы можете запускать контейнеры с --gpus all

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

проверьте, что контейнер видит GPU:

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

Добавление поддержки NVidia для Docker Model Runner

Docker Model Runner требует явной конфигурации GPU. В отличие от стандартных команд docker run, docker model run не поддерживает флаги --gpus или -e. Вместо этого вам нужно:

  1. Настройте демон Docker для использования NVIDIA runtime по умолчанию

Сначала проверьте, где установлен nvidia-container-runtime:

which nvidia-container-runtime

Обычно это выведет /usr/bin/nvidia-container-runtime. Используйте этот путь в конфигурации ниже.

Создайте или обновите /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

Примечание: Если which nvidia-container-runtime возвращает другой путь, обновите значение "path" в JSON-конфигурации соответственно.

Перезапустите Docker:

sudo systemctl restart docker

Проверьте конфигурацию:

docker info | grep -i runtime

Вы должны увидеть Default Runtime: nvidia в выводе.

  1. Переустановите Docker Model Runner с поддержкой GPU

Docker Model Runner должен быть установлен/переустановлен с явной поддержкой GPU:

# Остановите текущий запускаемый процесс
docker model stop-runner

# Переустановите с поддержкой CUDA GPU
docker model reinstall-runner --gpu cuda

Это загрузит версию с поддержкой CUDA (docker/model-runner:latest-cuda) вместо версии только для CPU.

  1. Проверьте доступ к GPU

Убедитесь, что контейнер Docker Model Runner может получить доступ к GPU:

docker exec docker-model-runner nvidia-smi
  1. Тестирование модели с GPU

Запустите модель и проверьте логи, чтобы подтвердить использование GPU:

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

Проверьте логи для подтверждения GPU:

docker model logs | grep -i cuda

Вы должны увидеть сообщения вроде:

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

Примечание: Если вы уже установили Docker Model Runner без поддержки GPU, вам необходимо переустановить его с флагом --gpu cuda. Просто настройка демона Docker недостаточна — сам контейнер запускаемого процесса должен быть версией с поддержкой CUDA.

Доступные бэкенды GPU:

  • cuda - NVIDIA CUDA (наиболее распространенный)
  • rocm - AMD ROCm
  • musa - Moore Threads MUSA
  • cann - Huawei CANN
  • auto - Автоматическое обнаружение (по умолчанию)
  • none - Только CPU

Основные команды

Загрузка моделей

Загрузите предварительно упакованные модели из Docker Hub:

# Базовая загрузка
docker model pull ai/llama2

# Загрузка конкретной версии
docker model pull ai/llama2:7b-q4

# Загрузка из пользовательского реестра
docker model pull myregistry.com/models/mistral:latest

# Список доступных моделей в пространстве имен
docker search ai/

Запуск моделей

Запустите модель с автоматическим предоставлением API:

# Базовый запуск (интерактивный)
docker model run ai/llama2 "Что такое Docker?"

# Запуск как сервиса (в фоне)
docker model run -d

в целом у нас мало опций для запуска моделей через CLI:

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

Запуск модели и взаимодействие с ней с использованием отправленного запроса или режима чата

Опции:
      --color string                  Использовать цветной вывод (auto|yes|no) (по умолчанию "auto")
      --debug                         Включить отладочную запись логов
  -d, --detach                        Загрузить модель в фоновом режиме без взаимодействия
      --ignore-runtime-memory-check   Не блокировать загрузку, если оцененная память для модели превышает ресурсы системы.

Список моделей

Просмотр загруженных и работающих моделей:

# Список всех загруженных моделей
docker model ls

# Список работающих моделей
docker model ps

# Список с подробной информацией
docker model ls --json

# Список с подробной информацией
docker model ls --openai

# Вернет хеш-коды
docker model ls -q

Удаление моделей

Удалите модели из локального хранилища:

# Удалить конкретную модель
docker model rm ai/llama2

# Удалить с принуждением (даже если работает)
docker model rm -f ai/llama2

# Удалить неиспользуемые модели
docker model prune

# Удалить все модели
docker model rm $(docker model ls -q)

Настройка размеров контекста моделей

Мы не можем использовать CLI для указания размера контекста для конкретного запроса.

В основном можно контролировать размер контекста модели только тремя способами:

  1. Упакуйте модель самостоятельно, указав желаемый зафиксированный размер контекста (Подробнее об этом в следующем разделе.)

  2. При использовании команды docker model runner configure с параметром –context-size, например:

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

Затем вы можете вызывать curl, но не можете использовать docker moder run... — это игнорирует настройку.

  1. В файле docker-compose.yaml, но мы не можем использовать образ docker-model-runner таким образом, потому что он передает модели зафиксированный размер контекста 4096
...
models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240
...

Для получения дополнительной информации, пожалуйста, ознакомьтесь с отдельной статьей об этом: Указание размера контекста в DMR

Упаковка пользовательских моделей

Создание OCI Artifact из GGUF

Упакуйте свои собственные модели GGUF:

# Базовая упаковка
docker model package --gguf /path/to/model.gguf myorg/mymodel:latest

# Упаковка с метаданными
docker model package \
  --gguf /path/to/model.gguf \
  --label "description=Custom Llama model" \
  --label "version=1.0" \
  myorg/mymodel:v1.0

# Упаковка и отправка в один шаг
docker model package --gguf /path/to/model.gguf --push myorg/mymodel:latest

# Упаковка с пользовательским размером контекста
docker model package \
  --gguf /path/to/model.gguf \
  --context 8192 \
  myorg/mymodel:latest

Публикация моделей

Отправьте модели в реестры:

# Вход в Docker Hub
docker login

# Отправка в Docker Hub
docker model push myorg/mymodel:latest

# Отправка в приватный реестр
docker login myregistry.com
docker model push myregistry.com/models/mymodel:latest

# Метка и отправка
docker model tag mymodel:latest myorg/mymodel:v1.0
docker model push myorg/mymodel:v1.0

Использование API

Совместимые с OpenAI конечные точки

Docker Model Runner автоматически предоставляет совместимые с OpenAI API:

# Запуск модели с API
docker model run -d -p 8080:8080 --name llm ai/llama2

# Завершение чата
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Привет!"}]
  }'

# Генерация текста
curl http://localhost:8080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "prompt": "Однажды",
    "max_tokens": 100
  }'

# Потоковый ответ
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama2",
    "messages": [{"role": "user", "content": "Расскажи мне историю"}],
    "stream": true
  }'

# Список доступных моделей через API
curl http://localhost:8080/v1/models

# Информация о модели
curl http://localhost:8080/v1/models/llama2

Конфигурация Docker Compose

Базовый файл 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

Настройка нескольких моделей

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"

Для более сложных конфигураций и команд Docker Compose, см. наш Справочник Docker Compose, в котором рассматриваются сетевые настройки, тома и шаблоны оркестрации.

Переменные окружения

Настройте поведение модели с помощью переменных окружения:

# Температура (0.0-1.0)
MODEL_TEMPERATURE=0.7

# Выборка top-p
MODEL_TOP_P=0.9

# Выборка top-k
MODEL_TOP_K=40

# Максимальное количество токенов
MODEL_MAX_TOKENS=2048

# Количество слоев GPU
MODEL_GPU_LAYERS=35

# Размер пакета
MODEL_BATCH_SIZE=512

# Количество потоков (CPU)
MODEL_THREADS=8

# Включить подробное логирование
MODEL_VERBOSE=true

# Ключ API для аутентификации
MODEL_API_KEY=your-secret-key

Запуск с переменными окружения:

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

Настройка GPU

Автоматическое обнаружение GPU

DMR автоматически обнаруживает и использует доступные GPU:

# Использовать все GPU
docker model run --gpus all ai/llama2

# Использовать конкретное GPU
docker model run --gpus 0 ai/llama2

# Использовать несколько конкретных GPU
docker model run --gpus 0,1,2 ai/llama2

# GPU с ограничением памяти
docker model run --gpus all --memory 16g ai/llama2

Режим только CPU

Принудительное выполнение инференса на CPU, когда доступно GPU:

docker model run --no-gpu ai/llama2

Многопоточная тензорная параллельность

Распределение больших моделей по GPU:

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

Инспекция и отладка

Просмотр информации о модели

# Просмотр конфигурации модели
docker model inspect ai/llama2

# Просмотр слоев модели
docker model history ai/llama2

# Проверка размера и метаданных модели
docker model inspect --format='{{.Size}}' ai/llama2

Логи и мониторинг

# Просмотр логов модели
docker model logs llm

# Следить за логами в реальном времени
docker model logs -f llm

# Просмотр последних 100 строк
docker model logs --tail 100 llm

# Просмотр логов с временными метками
docker model logs -t llm

Статистика производительности

# Использование ресурсов
docker model stats

# Статистика конкретной модели
docker model stats llm

# Статистика в формате JSON
docker model stats --format json

Сетевые настройки

Открытие API

# Стандартный порт (8080)
docker model run -p 8080:8080 ai/llama2

# Пользовательский порт
docker model run -p 3000:8080 ai/llama2

# Привязка к конкретному интерфейсу
docker model run -p 127.0.0.1:8080:8080 ai/llama2

# Несколько портов
docker model run -p 8080:8080 -p 9090:9090 ai/llama2

Сетевая конфигурация

# Создание пользовательской сети
docker network create llm-network

# Запуск модели в пользовательской сети
docker model run --network llm-network --name llm ai/llama2

# Подключение к существующей сети
docker model run --network host ai/llama2

Безопасность

Контроль доступа

# Запуск с аутентификацией по ключу API
docker model run \
  -e MODEL_API_KEY=my-secret-key \
  ai/llama2

# Использование с аутентификацией
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer my-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "llama2", "messages": [...]}'

Аутентификация в реестре

# Вход в приватный реестр
docker login myregistry.com -u username -p password

# Загрузка из приватного реестра
docker model pull myregistry.com/private/model:latest

# Использование помощника для ввода пароля
docker login --password-stdin < token.txt

Лучшие практики

Выбор модели

# Использование квантованных моделей для более быстрого инференса
docker model pull ai/llama2:7b-q4     # Квантование 4 бита
docker model pull ai/llama2:7b-q5     # Квантование 5 бит
docker model pull ai/llama2:7b-q8     # Квантование 8 бит

# Проверка вариантов моделей
docker search ai/llama2

Управление ресурсами

# Установка ограничений памяти
docker model run --memory 8g --memory-swap 16g ai/llama2

# Установка ограничений CPU
docker model run --cpus 4 ai/llama2

# Ограничение памяти GPU
docker model run --gpus all --gpu-memory 8g ai/llama2

Проверки работоспособности

# Запуск с проверкой работоспособности
docker model run \
  --health-cmd "curl -f http://localhost:8080/health || exit 1" \
  --health-interval 30s \
  --health-timeout 10s \
  --health-retries 3 \
  ai/llama2

Оркестрация в производственной среде

Для развертывания в производственной среде с Kubernetes контейнеры Docker Model Runner могут быть оркестрированы с использованием стандартных манифестов Kubernetes. Определите развертывания с ограничениями ресурсов, автоскейлингом и балансировкой нагрузки. Для полного списка команд Kubernetes и шаблонов развертывания ознакомьтесь с нашей Шпаргалкой по Kubernetes.

# Пример: Развертывание в кластере Kubernetes
kubectl apply -f llm-deployment.yaml

# Масштабирование развертывания
kubectl scale deployment llm --replicas=3

# Открытие как сервиса
kubectl expose deployment llm --type=LoadBalancer --port=8080

Устранение неполадок

Распространенные проблемы

Модель не запускается:

# Проверка доступного места на диске
df -h

# Просмотр подробных логов ошибок
docker model logs --tail 50 llm

# Проверка доступности GPU
nvidia-smi  # Для GPU NVIDIA

Ошибки нехватки памяти:

# Использование меньшей квантованной модели
docker model pull ai/llama2:7b-q4

# Уменьшение размера контекста
docker model run -e MODEL_CONTEXT=2048 ai/llama2

# Ограничение размера пакета
docker model run -e MODEL_BATCH_SIZE=256 ai/llama2

Медленный инференс:

# Проверка использования GPU
docker model stats llm

# Убедитесь, что GPU используется
docker model logs llm | grep -i gpu

# Увеличение количества слоев GPU
docker model run -e MODEL_GPU_LAYERS=40 ai/llama2

Диагностические команды

# Информация о системе
docker model system info

# Использование диска
docker model system df

# Очистка неиспользуемых ресурсов
docker model system prune

# Полная очистка (удаление всех моделей)
docker model system prune -a

Примеры интеграции

Интеграция с Python

import openai

# Настройка клиента для Docker Model Runner
client = openai.OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # DMR не требует ключа по умолчанию
)

# Завершение чата
response = client.chat.completions.create(
    model="llama2",
    messages=[
        {"role": "user", "content": "Привет!"}
    ]
)

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

# Потоковая передача
stream = client.chat.completions.create(
    model="llama2",
    messages=[{"role": "user", "content": "Расскажи мне историю"}],
    stream=True
)

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

Bash скрипт

#!/bin/bash

# Запуск модели, если она не работает
if ! docker model ps | grep -q "llm"; then
    docker model run -d --name llm -p 8080:8080 ai/llama2
    echo "Ожидание запуска модели..."
    sleep 10
fi

# Вызов 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'

Интеграция с 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;
}

// Использование
const response = await chat('Что такое Docker Model Runner?');
console.log(response);

Полезные ссылки

Официальная документация

Связанные шпаргалки

Статьи сравнения