Docker Model Runner 快速参考：命令与示例

Docker Model Runner 命令快速参考

Docker Model Runner (DMR) 是 Docker 官方用于本地运行 AI 模型的解决方案，于 2025 年 4 月推出。此快速参考提供了所有关键命令、配置和最佳实践的快速查阅。

docker model runner 中可用的 gemma 模型列表

安装

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 窗口

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 的 NVIDIA RTX 支持

为了使 LLM 在 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

为 Docker Model Runner 添加 NVIDIA 支持

Docker Model Runner 需要显式配置 GPU。与标准的 docker run 命令不同，docker model run 不支持 --gpus 或 -e 标志。相反，你需要：

  1. 配置 Docker 守护进程默认使用 NVIDIA 运行时

首先，检查 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 返回不同的路径，请相应地更新 JSON 配置中的 "path" 值。

重启 Docker：

sudo systemctl restart docker

验证配置：

docker info | grep -i runtime

你应该在输出中看到 Default Runtime: nvidia。

  1. 使用 GPU 支持重新安装 Docker Model Runner

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

注意： 如果你已经安装了没有 GPU 支持的 Docker Model Runner，你必须使用 --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 "What is 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 配置命令时，使用 --context-size 参数，例如：

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

然后你可以使用 curl 调用它，但不能使用 docker model run... - 该命令将忽略配置。

  1. 在 docker-compose.yaml 文件中，但我们不能以这种方式使用 docker-model-runner 图像，因为它是传递给模型的硬编码上下文大小为 4096
...
models:
  llm_model:
    model: ai/gemma3-qat:4B
    context_size: 10240
...

有关更多详细信息，请参阅专门的帖子： 在 DMR 中指定上下文大小

打包自定义模型

从 GGUF 创建 OCI 工件

打包自己的 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": "Hello!"}]
  }'

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

# 流式响应
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
  }'

# 通过 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 模式

当 GPU 可用时强制使用 CPU 推理：

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 的生产部署，可以使用标准的 Kubernetes 清单对 Docker Model Runner 容器进行编排。定义带有资源限制、自动扩展和负载均衡的部署。有关全面的 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  # 对于 NVIDIA GPU

内存不足错误：

# 使用较小的量化模型
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": "Hello!"}
    ]
)

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

# 流式传输
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="")

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);

有用链接

官方文档

相关快速参考

比较文章