WSL2里Docker调用不到显卡？HeyGem.ai数字人视频合成的GPU透传配置指南
【免费下载链接】Duix-Avatar🚀 Truly open-source AI avatar(digital human) toolkit for offline video generation and digital human cloning.项目地址: https://gitcode.com/GitHub_Trending/he/Duix-Avatar
在 WSL2 中跑 Docker 容器时，Docker GPU 透传（把宿主机上的 NVIDIA 显卡暴露给容器使用）一旦没配好，HeyGem.ai 的三个服务容器就起不来，离线数字人视频合成也无法启动。这篇文章把这条链路拆成 3 个检查点：先核对 WSL2 与显卡驱动版本，再安装 nvidia-container-toolkit 打通容器与显卡之间的桥梁，最后用项目 deploy/ 目录下现成的编排文件拉起服务并逐项验收。全程不需要改一行源码，照着执行即可让--gpus all真正生效。
前置检查：两个版本门槛先过一遍
在动 Docker 之前，先把宿主机的两关确认掉，否则后面装什么都是白装。
| 检查项 | 最低要求 | 作用 |
|---|---|---|
| WSL | WSL2，且wsl --version中 WSL 与 WSLg 均显示 1.0 以上 | GPU 直通能力由新版 WSL2 内核提供 |
| NVIDIA 驱动 | 版本不低于 510.06 | 支持 WSL2 显卡直通，驱动在 Windows 侧安装 |
确认 WSL2 版本是否达标
wsl --version # 查看 WSL 与 WSLg 内核版本成功标志：输出中WSL version和WSLg version都是 1.x 以上。如果显示的是旧格式信息（只有Version: 2一类字样），说明内核过旧，在 Windows PowerShell 里执行wsl --update升级后，重新跑一遍上面的命令复核。
确认显卡驱动是否就绪
nvidia-smi # 在 WSL 终端内直接检查宿主显卡成功标志：能列出 GPU 名称与驱动版本。若提示命令不存在，说明 NVIDIA 驱动 未在 Windows 侧装好（或在 WSL 中未启用"Windows 管理 GPU 驱动"），此时三个服务容器一定无法启动。
给 Docker 装 GPU 运行时：安装 nvidia-container-toolkit
NVIDIA Container Toolkit 是连接 Docker 与显卡的"翻译层"：它向 Docker 注册一个 nvidia 运行时，容器启动时才能看到 GPU 设备。
添加官方软件源并安装
curl -s -L 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 # 安装工具包注册 nvidia 运行时并重启 Docker
sudo nvidia-ctk runtime configure --runtime=docker # 把 nvidia 运行时写进 Docker 守护进程配置 sudo systemctl restart docker注意：这一步重启不能省，漏掉的直接症状是后面测试时提示找不到设备驱动。
用一条命令验收 GPU 透传
docker info | grep -A 2 "Runtimes" | grep nvidia # 成功标志：能列出 nvidia 运行时与 nvidia GPU 设备 docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi成功标志：第二条命令在容器内打印出显卡型号、显存与驱动版本，说明"宿主机 → WSL2 → Docker → 容器"这条透传链路已经通了。若报could not select device driver "nvidia"，回到上一小节确认重启是否执行。
拉起 HeyGem.ai 的三个 GPU 服务
透传验证通过后，服务端部署只剩一条命令。先克隆仓库：
git clone https://gitcode.com/GitHub_Trending/he/HeyGem.aideploy/docker-compose-linux.yml 已为每个服务预置好runtime: nvidia与 GPU 设备预留，你不需要自己编写任何 GPU 参数。核心服务与端口如下：
| 服务 | 镜像 | 端口 | 职责 |
|---|---|---|---|
| duix-avatar-tts | guiji2025/fish-speech-ziming | 18180 | 声音克隆与语音合成 |
| duix-avatar-asr | guiji2025/fun-asr | 10095 | 语音识别 |
| duix-avatar-gen-video | guiji2025/duix.avatar | 8383 | 口型驱动与视频合成 |
一键启动并检查容器状态
cd HeyGem.ai/deploy docker compose -f docker-compose-linux.yml up -d首次会拉取约 70GB 镜像，耗时以网速为准，建议挂在稳定的 Wi-Fi 下等待。完成后：
docker ps --format "table {{.Names}}\t{{.Status}}" # 成功标志：三个容器全部 Running如果你使用 RTX 50 系列显卡，标准镜像的 CUDA 版本可能不匹配，改用 5090 专用编排：
docker compose -f docker-compose-5090.yml up -d验收与排障：跑起来之后还能确认什么
逐端口核对三个服务端
客户端会访问127.0.0.1上的 8383、18180、10095 三个端口。可逐个查看容器日志，确认无异常退出或报错循环：
docker logs --tail 20 duix-avatar-gen-video # 对另外两个容器名同样执行生成视频时盯一眼 GPU 占用
nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv -l 3成功标志：合成期间utilization.gpu出现明显读数。若长时间为 0 且任务卡住，多半是显存不足——该方案建议 8GB 以上显存；机器配置偏低时，可先改用 deploy/docker-compose-lite.yml 启动单服务轻量版。
两个高频故障速查
- 拉镜像超时、连接被取消：WSL 环境下访问 Docker Hub 官方仓库经常不稳定，在 Docker Desktop 的 Docker Engine 设置里配置
registry-mirrors镜像源后重启引擎即可。
- 创建模特或克隆音色时报错：先按 常见问题 里的自查步骤确认三个容器均为 Running，再核对素材视频是否带人声——声音克隆依赖这段音频。
要点回顾
- WSL 版本 ≥ 1.0、驱动 ≥ 510.06，两道门槛先过；
nvidia-ctk注册运行时后必须重启 Docker，再用--gpus all测试容器验证透传；- 服务启动交给 deploy/docker-compose-linux.yml 一条命令，50 系显卡换用 deploy/docker-compose-5090.yml；
- 显存 8GB 起步；镜像拉取慢就配国内镜像源。
部署中遇到具体报错，建议先翻 doc/常见问题.md，并带着docker logs输出的关键日志再去项目仓库提 issue；客户端相关逻辑可参考 src/main/ 源码目录。
【免费下载链接】Duix-Avatar🚀 Truly open-source AI avatar(digital human) toolkit for offline video generation and digital human cloning.项目地址: https://gitcode.com/GitHub_Trending/he/Duix-Avatar
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
