为 Docker 模型运行器添加 NVIDIA GPU 支持

Docker Model Runner 是 Docker 官方用于本地运行 AI 模型的工具，但 在 Docker Model Runner 中启用 NVidia GPU 加速 需要特定的配置。

与标准的 docker run 命令不同，docker model run 不支持 --gpus 或 -e 标志，因此 GPU 支持必须在 Docker 守护进程级别和安装运行器时进行配置。

如果您正在寻找一个具有更简单 GPU 配置的替代 LLM 托管解决方案，请考虑 Ollama，它内置了 GPU 支持并具有更简单的设置。然而，Docker Model Runner 提供了与 Docker 生态系统和 OCI 软件包分发更好的集成。

这张漂亮的图片由 AI 模型 Flux 1 dev 生成。

先决条件

在配置 GPU 支持之前，请确保您具备以下条件：

• NVIDIA GPU 并已安装兼容的驱动程序。如需帮助选择适合 AI 工作负载的 GPU，请参阅我们的指南 比较 NVidia GPU 规格对 AI 的适用性。
• NVIDIA Container Toolkit 已安装（请参阅 NVIDIA RTX 支持部分）。
• Docker Model Runner 已安装（可以使用 GPU 支持重新安装）。

验证您的 GPU 是否可用：

nvidia-smi

测试 Docker 的 GPU 访问：

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

如需更多 Docker 命令和配置选项，请参阅我们的 Docker 快速参考。

第一步：为 NVIDIA 运行时配置 Docker 守护进程

Docker Model Runner 需要将 NVIDIA 运行时设置为 Docker 守护进程配置中的默认运行时。

查找 NVIDIA 容器运行时路径

首先，找到 nvidia-container-runtime 的安装位置：

which nvidia-container-runtime

通常输出为 /usr/bin/nvidia-container-runtime。请记下此路径以进行下一步操作。

配置 Docker 守护进程

创建或更新 /etc/docker/daemon.json 以将 NVIDIA 设置为默认运行时：

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 服务

通过重启 Docker 应用配置：

sudo systemctl restart docker

验证配置

确认 NVIDIA 运行时已配置：

docker info | grep -i runtime

输出中应显示 Default Runtime: nvidia。

第二步：安装带有 GPU 支持的 Docker Model Runner

Docker Model Runner 必须使用显式 GPU 支持进行安装或重新安装。运行器容器本身需要是 CUDA 启用版本。

停止当前运行器（如果正在运行）

如果 Docker Model Runner 已经安装，请先停止它：

docker model stop-runner

安装/重新安装带有 CUDA 支持

安装或重新安装带有 CUDA GPU 支持的 Docker Model Runner：

docker model reinstall-runner --gpu cuda

此命令：

• 拉取 CUDA 启用版本 (docker/model-runner:latest-cuda) 而不是仅 CPU 版本
• 配置运行器容器使用 NVIDIA 运行时
• 为所有模型启用 GPU 加速

注意： 如果您已经安装了没有 GPU 支持的 Docker Model Runner，则必须使用 --gpu cuda 标志重新安装。仅配置 Docker 守护进程是不够的——运行器容器本身需要是 CUDA 启用版本。

可用的 GPU 后端

Docker Model Runner 支持多种 GPU 后端：

• cuda - NVIDIA CUDA（NVIDIA GPU 最常见）
• rocm - AMD ROCm（用于 AMD GPU）
• musa - Moore Threads MUSA
• cann - 华为 CANN
• auto - 自动检测（默认，可能无法正确工作）
• none - 仅 CPU

对于 NVIDIA GPU，始终显式使用 --gpu cuda。

第三步：验证 GPU 访问

安装完成后，验证 Docker Model Runner 是否可以访问您的 GPU。

检查运行器容器的 GPU 访问

从 Docker Model Runner 容器内测试 GPU 访问：

docker exec docker-model-runner nvidia-smi

这将显示您的 GPU 信息，确认容器具有 GPU 访问权限。

检查运行器状态

验证 Docker Model Runner 是否正在运行：

docker model status

您应该看到运行器处于活动状态并支持 llama.cpp。

第四步：使用 GPU 测试模型

运行模型并验证其是否使用 GPU。

运行模型

启动模型推理：

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

在日志中验证 GPU 使用情况

检查 Docker Model Runner 日志以确认 GPU 使用情况：

docker model logs | grep -i cuda

您应该看到以下信息：

• using device CUDA0 (NVIDIA GeForce RTX 4080) - 检测到 GPU 设备
• offloaded 41/41 layers to GPU - 模型层已加载到 GPU
• CUDA0 model buffer size = 10946.13 MiB - GPU 内存分配
• CUDA0 KV buffer size = 640.00 MiB - GPU 上的键值缓存
• CUDA0 compute buffer size = 306.75 MiB - GPU 上的计算缓冲区

监控 GPU 使用情况

在另一个终端中，实时监控 GPU 使用情况：

nvidia-smi -l 1

当模型运行时，您应该看到 GPU 内存使用和利用率增加。

如需更多高级 GPU 监控选项和工具，请参阅我们的指南 Linux / Ubuntu 上的 GPU 监控应用。

故障排除

模型仍在使用 CPU

如果模型仍在使用 CPU：

1. 验证 Docker 守护进程配置：

   docker info | grep -i runtime
   

   应显示 Default Runtime: nvidia

2. 检查运行器容器的运行时：

   docker inspect docker-model-runner | grep -A 2 '"Runtime"'
   

   应显示 "Runtime": "nvidia"

3. 使用 GPU 支持重新安装运行器：

   docker model reinstall-runner --gpu cuda
   

4. 检查日志中的错误：

   docker model logs | tail -50
   

未检测到 GPU

如果未检测到 GPU：

1. 验证是否已安装 NVIDIA Container Toolkit：

   dpkg -l | grep nvidia-container-toolkit
   

2. 使用标准 Docker 测试 GPU 访问：

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

   如需排查 Docker 问题，请参阅我们的 Docker 快速参考。

3. 检查 NVIDIA 驱动程序：

   nvidia-smi
   

性能问题

如果 GPU 性能较差：

1. 检查 GPU 利用率：

   nvidia-smi
   

   查看 GPU 利用率百分比是否较高

2. 验证模型层是否在 GPU 上：

   docker model logs | grep "offloaded.*layers to GPU"
   

   所有层都应卸载到 GPU

3. 检查内存问题：

   nvidia-smi
   

   确保 GPU 内存未耗尽

最佳实践

1. 始终显式指定 GPU 后端： 对于 NVIDIA GPU，使用 --gpu cuda 而不是 --gpu auto 以确保正确配置。

2. 更改配置后验证： 修改 Docker 守护进程设置后，始终检查 docker info | grep -i runtime。

3. 监控 GPU 使用情况： 使用 nvidia-smi 监控模型推理期间的 GPU 内存和利用率。如需更多高级监控工具，请参阅我们的指南 Linux / Ubuntu 上的 GPU 监控应用。

4. 定期检查日志： 查看 docker model logs 以确保模型使用 GPU 加速。

5. 使用适当的模型大小： 确保您的 GPU 具有足够的内存来运行模型。使用量化模型（Q4、Q5、Q6、Q8）以提高 GPU 内存效率。如需帮助选择适合 AI 工作负载的 GPU，请参阅我们的指南 比较 NVidia GPU 规格对 AI 的适用性。

有用链接

• Docker Model Runner 快速参考
• Docker Model Runner 官方文档
• NVIDIA Container Toolkit 安装指南
• Docker Model Runner 与 Ollama 对比
• Ollama 快速参考 - 带有内置 GPU 支持的替代 LLM 托管解决方案
• Docker 快速参考 - Docker 命令和配置的完整参考
• Linux / Ubuntu 上的 GPU 监控应用 - NVIDIA GPU 监控工具列表和比较
• 比较 NVidia GPU 规格对 AI 的适用性 - 选择适合 AI 工作负载的 GPU 指南