Odysseus Docker 容器如何启用并验证 NVIDIA GPU 直通Cookbook 可见 GPU【免费下载链接】odysseusSelf-hosted AI workspace.项目地址: https://gitcode.com/gh_mirrors/ody/odysseusOdysseus 用 Docker Compose 部署后Cookbook 模块只能检测到 Docker 暴露给容器的那部分 GPU。如果宿主机没有配好 NVIDIA 容器运行时或设备直通Cookbook 看到的是集显、另一张卡甚至只是 CPU——模型推荐会基于错误的 VRAM。这篇文档描述的就是从宿主诊断、启用 NVIDIA overlay、到在容器内确认 GPU 可见的完整路径适用于 Odysseus 以docker compose方式运行的 Linux 宿主机。CPU-only 用户可以跳过整条流程。准备条件在仓库根目录已 clone Odysseus 并跑过docker compose up -d --build或准备首次启动的位置完成以下检查宿主机 NVIDIA 驱动可用nvidia-smi -L能列出 GPU。Docker 守护进程正在运行且当前用户有权限调用docker info。宿主机安装了 NVIDIA Container Toolkit。docker/gpu.nvidia.yml的注释给出了各发行版的安装方式# Arch: sudo pacman -S nvidia-container-toolkit # Debian: sudo apt install nvidia-container-toolkit # Fedora: sudo dnf install nvidia-container-toolkit安装后配置 Docker 运行时并重启 Dockersudo nvidia-ctk runtime configure --runtimedocker sudo systemctl restart docker这两条会修改/etc/docker/daemon.json并重启 Docker daemon该动作会使宿主机上所有正在运行的容器短暂停止需要 sudo 权限。第一步只读诊断 GPU 直通仓库自带scripts/check-docker-gpu.sh默认模式是只读的——不安装软件、不改配置、不重启 Dockerscripts/check-docker-gpu.sh它依次检查三项宿主机nvidia-smi是否工作、列出了哪些 GPUDocker daemon 是否可用GPU 直通测试实际执行docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi注意这条验证命令第一次运行会拉取nvidia/cuda镜像。输出以[PASS]/[FAIL]汇总。直通通过时会提示用scripts/check-docker-gpu.sh --enable-nvidia-overlay启用 overlay失败时按序给出修复步骤安装 toolkit →nvidia-ctk runtime configure→systemctl restart docker。诊断模式下若检测到 WSL2 snap Docker 的组合会额外警告这是已知不兼容snap 的隔离策略让 Docker 看不到 WSL2 注入的/usr/lib/wsl/lib/libdxcore.so重装或重新配置nvidia-container-toolkit无法解决需要移除 snap Docker 改装官方 apt 版 Docker Engine 后再重跑诊断。如果不想跑完整诊断只想看当前系统适用的安装命令可以用只打印不执行的模式scripts/check-docker-gpu.sh --print-install-commands可选分支用脚本安装 NVIDIA Container Toolkitscripts/check-docker-gpu.sh --install-nvidia-toolkit仅支持 Ubuntu/Debian 系且需要 sudo。它会添加 NVIDIA apt 源、安装nvidia-container-toolkit、执行nvidia-ctk runtime configure --runtimedocker并提示是否重启 Docker——重启 Docker 会中断宿主机上所有容器。每一步执行前都会先展示命令并征求确认--yes可跳过确认提示用于自动化环境但它不能绕过直通门控。# 安装 toolkit直通验证通过后自动写 .env overlay scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay其他发行版请参照--print-install-commands打印的命令手工执行然后重跑只读诊断确认。第二步在 .env 中启用 NVIDIA overlayoverlay 文件是docker/gpu.nvidia.yml它给odysseus服务追加NVIDIA_VISIBLE_DEVICESall、NVIDIA_DRIVER_CAPABILITIEScompute,utility以及deploy.resources.reservations.devicesdriver: nvidia, count: all, capabilities: [gpu]。它只负责把宿主 GPU 直通进容器——slim 版 Odysseus 镜像本身不捆绑 CUDA 用户态或推理引擎GPU 模型还需要通过 Cookbook → Dependencies 安装 vLLM / llama-cpp-python / SGLang。启用方式二选一手动推荐先理解再操作在仓库根目录的.env中添加一行COMPOSE_FILEdocker-compose.yml:docker/gpu.nvidia.yml脚本代劳scripts/check-docker-gpu.sh --enable-nvidia-overlay该模式的行为边界在文档中有明确说明只有 GPU 直通测试通过时才会修改.env直通不通时直接中止hard gate--yes也不能绕过这个门控因为直通没修好就写COMPOSE_FILE会导致 Odysseus 启动失败修改前会先创建带时间戳的备份.env.bak.时间戳如果.env已含该 overlay脚本幂等返回提示重启即可已有其他COMPOSE_FILE值时overlay 会追加到现有值后面需要撤销时把备份拷回cp .env.bak.时间戳 .env。第三步重建容器overlay 生效后重新构建并启动docker compose up -d --build验证确认容器内能看到 GPUdocs/setup.md给出的验证命令是docker compose exec odysseus nvidia-smi -L宿主机侧还可以用以下命令确认 Docker 已识别 NVIDIA 运行时docker info | grep -i nvidiaArch Linux 用户如果走的是手工安装路径sudo pacman -Syu、sudo pacman -S docker docker-compose nvidia-container-toolkit nvidia-utils、nvidia-ctk runtime configure、重启 docker宿主机侧的直通验证命令为docker run --rm --gpus all nvidia/cuda:12.9.0-base-ubuntu22.04 nvidia-smi脚本内置的诊断用nvidia/cuda:12.4.1-base-ubuntu22.04文档中两处出现的镜像 tag 不同均可用于同一目的确认容器内能跑nvidia-smi。直通通过 ≠ Cookbook 能用 CUDAnvidia-smi在容器内通过只说明 Docker GPU 访问没问题。文档把两层问题分得很清楚如果 Cookbook 日志里出现Unable to find cudart library、Could NOT find CUDAToolkit、CUDA Toolkit not found或张量/层被分配到了 CPU那是 Cookbook/llama.cpp 的 CUDA 构建或运行时问题不是直通失败——处理方式是到Cookbook → Dependencies重新安装 serve engine 以获得带 CUDA 的构建。同样地直通正常也不等于 ROCm/CUDA 推理引擎已就绪引擎需要另行安装见上文 overlay 注释。替代路径与已知限制只支持单个 Compose 文件的栈管理 UIPortainer、Coolify 等通常不认COMPOSE_FILE叠加。此时把栈指向单文件版docker-compose.gpu-nvidia.yml它内嵌了基础栈加 NVIDIA 设置仍然要求宿主机已装 NVIDIA Container Toolkit。CLI 用户继续用docker-compose.ymldocker/gpu.nvidia.ymloverlay 这一来源为准的组合。首次跑本地模型文档建议 8 GB 笔记本 GPU 先试 llama.cpp 的 GGUF/Q4 模型再尝试 vLLM/SGLang 的 GPTQ/AWQ 模型以便先确认直通可用。撤销 overlay把.env恢复为备份或删掉COMPOSE_FILE中的 overlay 片段然后docker compose up -d --build。参考资料docs/setup.md、docker/gpu.nvidia.yml、scripts/check-docker-gpu.sh、docker-compose.gpu-nvidia.yml。【免费下载链接】odysseusSelf-hosted AI workspace.项目地址: https://gitcode.com/gh_mirrors/ody/odysseus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考