企业官网建设流程全解析

Odysseus Docker 如何启用并验证 AMD ROCm GPU 直通（RENDER_GID 与 gpu.amd overlay）

【免费下载链接】odysseusSelf-hosted AI workspace.项目地址: https://gitcode.com/gh_mirrors/ody/odysseus

如果你用 Docker 部署 Odysseus，主机上有一块 AMD GPU，并想讓容器内的 Cookbook 真正看到这块 GPU，就需要把宿主机的 ROCm 设备节点直通进容器，并通过docker/gpu.amd.ymloverlay 完成配置。Odysseus 官方对 AMD 的处理方式是“只读诊断 + 手动改.env”：先运行 scripts/check-docker-amd-gpu.sh 拿到宿主机 render 组的数字 GID，再把COMPOSE_FILE和RENDER_GID写入.env，重启后用一条docker compose exec命令确认容器内能看到/dev/kfd与/dev/dri/renderD*。适用前提是 docs/setup.md 中给出的环境：CPU-only 用户可以直接跳过这套配置。

前置条件：主机 ROCm 驱动与组权限

docker/gpu.amd.yml 的文件头注释写明了启用 overlay 的两个硬性前提：

• 主机已安装 ROCm 驱动，即/dev/kfd与/dev/dri设备节点存在；
• 在宿主机上运行 Docker 的用户必须属于video和render两个组。

overlay 本身只做一件事：把宿主 GPU 直通给odysseus服务——挂载/dev/kfd、/dev/dri两个设备，并通过group_add把容器加入video组和${RENDER_GID:-render}指定的组。也就是说，RENDER_GID必须是你宿主机 render 组的数字 GID；如果不设置，overlay 会退回用组名render。另一个要注意的边界：slim 版 Odysseus 镜像不打包 ROCm 用户态（userspace）和推理引擎，overlay 只负责设备直通这一层。

第一步：运行只读诊断脚本，拿到 RENDER_GID

scripts/check-docker-amd-gpu.sh

脚本自身的定位是只读诊断：不安装任何包、不编辑.env、不重启 Docker 守护进程。它做四项检查：

1. 宿主机/dev/kfd与/dev/dri/renderD*是否存在；
2. 宿主机 render 组（以及 video 组）的数字 GID，即后续要写进.env的RENDER_GID；
3. 宿主机上rocminfo是否可见（可选项，找不到不阻塞直通）；
4. 用一个小型容器做直通冒烟测试：docker run --rm挂载/dev/kfd和/dev/dri、带上对应--group-add，测试容器内能否列出 render 节点。

副作用说明：第 4 项会实际启动一个临时容器，--rm会立即删除它；首次运行可能拉取默认的alpine:3.20测试镜像，可用环境变量ODYSSEUS_AMD_TEST_IMAGE换成别的镜像。

脚本输出逐项标记[PASS]/[FAIL]/[WARN]，最后汇总为一行=== Results: N passed, N warnings, N failed ===，且只有FAIL为 0 时退出码才是 0。常见的 FAIL 项和脚本给出的提示：

• /dev/kfd缺失——宿主机没有 ROCm 内核驱动访问；
• Docker 守护进程未运行或当前用户没有 Docker 权限；
• 直通冒烟失败——脚本建议检查 Docker 能否访问/dev/kfd和/dev/dri后重试；
• render 组找不到——提示按发行版实际的组名手动设置RENDER_GID；video 组找不到只是 WARN，脚本注明部分主机上/dev/kfd与renderD*可能已经够用。

诊断通过后，脚本会打印一段建议写入.env的值，格式为：

COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml RENDER_GID=<宿主机 render 组的数字 GID>

第二步：把 COMPOSE_FILE 与 RENDER_GID 写入 .env

RENDER_GID有两个可靠来源，二选一即可：

• 脚本输出中的render group GID: NNNN；
• overlay 文件头注释给出的宿主机命令：

getent group render | cut -d: -f3

拿到数字后写入.env（也可以 export 到运行docker compose的 shell 环境中），按 docs/setup.md 的示例：

COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml RENDER_GID=989

其中989是 setup 文档里给出的示例值，替换成你自己宿主机上查到的 render 组 GID。配置好 overlay 后，建议通读 docker/gpu.amd.yml 中的注释，确认 devices 与 group_add 的行为符合你的预期。

重启并验证容器内设备节点

重启 Odysseus 让新的.env生效（compose 会用 overlay 的 devices 与 group 配置重建odysseus容器），然后执行 AMD 的验证命令：

docker compose up -d docker compose exec odysseus sh -lc 'test -e /dev/kfd && test -d /dev/dri && ls -l /dev/kfd /dev/dri/renderD*'

判断方式：命令以退出码 0 结束、ls -l列出/dev/kfd与/dev/dri/renderD*节点，说明设备直通已经在容器内就位。

这里有一条必须记住的边界（setup 文档明确强调）：看到/dev/kfd与/dev/dri只确认了设备直通，不代表 ROCm 用户态或 vLLM/llama.cpp 的 ROCm 构建可用。slim 版 Odysseus 镜像内不预期存在rocm-smi或rocminfo，所以不要试图在容器里用它们做验证。

直通成功之后：安装 ROCm 兼容的推理运行时

设备直通是 GPU 推理的必要条件而非充分条件。要实际跑 GPU 模型，按 overlay 注释和诊断脚本末尾的提示，先通过Cookbook → Dependencies（或 pip）安装 ROCm 兼容版本的 vLLM 或 llama-cpp-python，再开始 serve 模型。如果你只是让容器内应用连接远程模型端点，则不需要这一步。

可选分支：堆栈管理 UI 使用单文件 Compose

Portainer、Coolify、Dockhand 等工具通常只接受单个 Compose 文件，且不能可靠地识别COMPOSE_FILE或多个-foverlay。这种环境下把 stack 指向仓库根目录的 docker-compose.gpu-amd.yml 即可，它等价于docker-compose.yml+docker/gpu.amd.yml，前置要求相同：宿主机 ROCm/kfd/DRI 配置、video/render组成员身份，以及需要时的RENDER_GID。文档明确说明基础文件加 overlay 才是权威来源，单文件版本只是为单文件部署做的镜像。CLI 用户继续走COMPOSE_FILEoverlay 流程。

限制与排查

• Cookbook 看不到预期的 GPU 时：Cookbook 只能检测到 Docker 暴露给容器的 GPU。如果主机运行时或设备直通没配置好，Cookbook 看到的是核显、另一块卡或 CPU，而不是你预期的 GPU——先回到第一步确认冒烟测试通过。
• 验证命令非 0 退出：说明容器内缺少/dev/kfd或/dev/dri的 render 节点，对照诊断脚本的 FAIL 项逐项排查宿主机驱动、组权限与 Docker 访问。
• 直通通过但推理仍落到 CPU：这与 Docker 直通无关，属于运行时问题——vLLM 与 llama.cpp 仍需要 ROCm 兼容构建或 ROCm 专用 Docker 镜像，参见上一节的安装步骤。

整套流程到此形成闭环：诊断脚本给出 GID 与直通冒烟结果，.env里两行配置启用 overlay，docker compose exec一条命令完成容器内验证，后续再按 Cookbook 安装 ROCm 运行时。

【免费下载链接】odysseusSelf-hosted AI workspace.项目地址: https://gitcode.com/gh_mirrors/ody/odysseus