Шпаргалка Docker Model Runner: команды и примеры
Справочник команд Docker Model Runner
Docker Model Runner (DMR) — это официальное решение Docker для запуска моделей ИИ локально, представленное в апреле 2025 года. Этот справочник предоставляет быстрый доступ ко всем основным командам, настройкам и лучшим практикам.
Установка
Docker Desktop
Включите Docker Model Runner через графический интерфейс:
- Откройте Docker Desktop
- Перейдите в Настройки → вкладка ИИ
- Нажмите Включить Docker Model Runner
- Перезапустите Docker Desktop
/home/rg/prj/hugo-pers/content/post/2025/10/docker-model-runner-cheatsheet/docker-model-runner_w678.jpg
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
Основные команды
Загрузка моделей
Загрузите предварительно упакованные модели из 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 --name my-llm ai/llama2
# Запуск с пользовательским портом
docker model run -p 8080:8080 ai/llama2
# Запуск с указанием GPU
docker model run --gpus 0,1 ai/llama2
# Запуск с ограничением памяти
docker model run --memory 8g ai/llama2
# Запуск с переменными окружения
docker model run -e MODEL_CONTEXT=4096 ai/llama2
# Запуск с монтированием тома для постоянных данных
docker model run -v model-data:/data ai/llama2
Список моделей
Просмотрите загруженные и работающие модели:
# Список всех загруженных моделей
docker model ls
# Список работающих моделей
docker model ps
# Список с подробной информацией
docker model ls --all --format json
# Фильтрация по имени
docker model ls --filter "name=llama"
Остановка моделей
Остановите работающие экземпляры моделей:
# Остановка конкретной модели
docker model stop my-llm
# Остановка всех работающих моделей
docker model stop $(docker model ps -q)
# Остановка с таймаутом
docker model stop --time 30 my-llm
Удаление моделей
Удалите модели из локального хранилища:
# Удаление конкретной модели
docker model rm ai/llama2
# Принудительное удаление (даже если работает)
docker model rm -f ai/llama2
# Удаление неиспользуемых моделей
docker model prune
# Удаление всех моделей
docker model rm $(docker model ls -q)
Упаковка пользовательских моделей
Создание OCI-артефакта из 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_CONTEXT=4096
- MODEL_TEMPERATURE=0.7
volumes:
- model-data:/root/.cache
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
volumes:
model-data:
Настройка нескольких моделей
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, который охватывает сетевые настройки, тома и шаблоны оркестрации.
Переменные окружения
Настройте поведение модели с помощью переменных окружения:
# Размер окна контекста
MODEL_CONTEXT=4096
# Температура (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_CONTEXT=8192 \
-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 тензорный параллелизм
Распределите большие модели по 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);
Полезные ссылки
Официальная документация
- Официальная страница Docker Model Runner
- Документация Docker Model Runner
- Руководство по началу работы с Docker Model Runner
- Блог Docker: представление Docker Model Runner
Связанные шпаргалки
- Шпаргалка Docker
- Шпаргалка Docker Compose - самые полезные команды с примерами
- Шпаргалка Kubernetes
- Шпаргалка Ollama