HeyGem.ai 在 WSL2 下配置 Docker GPU 直通-平芜编程栈

HeyGem.ai 在 WSL2 下配置 Docker 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

给 HeyGem.ai（数字人视频合成项目）在 WSL2 里配 Docker GPU，"调不到卡"的根因不在 WSL 本身：容器默认与宿主设备隔离，GPU 设备文件必须由 NVIDIA Container Toolkit 在容器启动时显式注入，缺了这一环，--gpus all必然失败。本文按环境自检、直通链路、启动排障、运行期调优四段，把整条链路走完。

🔍 开机自检：核查 WSL2 版本、NVIDIA 驱动与 Docker 后端

部署前先做一轮环境体检，三个检查点各跑一条命令：

WSL 版本：Windows 10 19042.1526 以上系统，在 Windows 终端执行wsl --version，确认目标发行版的VERSION为2；若停在 1，先wsl --set-version <发行版名> 2升级。
NVIDIA 驱动：WSL 终端直接跑nvidia-smi，能列出显卡且驱动≥510.06才满足 WSL2 直通要求。驱动装在 Windows 侧，WSL 内不需要另装。
Docker 后端：Docker Desktop 的 Resources 页应显示使用 WSL 2 backend，且 WSL Integration 中已启用对应发行版。

三项都过再往下走，任何一项不达标，后面的容器验证都会卡在同一位置。

打通 GPU 直通链路：安装 NVIDIA Container Toolkit 并验证 nvidia-smi

Toolkit 是 Docker 识别 GPU 的核心组件，Docker Desktop 的 WSL2 环境多数已预装。若nvidia-ctk命令不存在，先按 README_zh.md 的 Ubuntu 安装章节添加 NVIDIA 软件源，再执行安装与 runtime 注册：

sudo apt update && sudo apt install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtime=docker sudo systemctl restart docker

装完先用一条最小容器验证直通是否真正生效：

docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

输出里能看到显卡型号与显存大小，说明设备注入成功；若报could not select device driver "nvidia"，基本就是 runtime 没注册，回到上一步确认。

拉起服务并排障：Compose 启动 HeyGem.ai 并核对容器状态

把仓库 clone 进 WSL 发行版后，在部署目录拉起服务：

git clone https://gitcode.com/GitHub_Trending/he/HeyGem.ai cd HeyGem.ai/deploy && docker-compose -f docker-compose-linux.yml up -d

首次启动要拉取三个镜像，官方说明会消耗约 70G 流量，耐心等。GPU 预留参数已预置在编排文件里，见 deploy/docker-compose-linux.yml 的reservations段：

deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu]

拉取完成后核对状态，三个服务全部 Running 即部署完成：

docker ps --format "table {{.Names}}\t{{.Status}}"

duix-avatar-tts、duix-avatar-asr、duix-avatar-gen-video分别对外暴露 18180、10095、8383 端口。有服务起不来时，按顺序排查：

显存不足：容器在加载模型阶段 OOM 退出。显存紧张可换docker-compose-lite.yml，只保留视频合成单服务。
驱动不匹配：容器内 CUDA 初始化失败、宿主机nvidia-smi版本偏旧。这个报错基本就是驱动没对上，更新 Windows 侧驱动后重启 Docker Desktop。
runtime 未注册：启动即报could not select device driver "nvidia"，重跑sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker。
镜像拉取超时：request canceled一类网络错误，按 doc/常见问题.md 在 Docker Engine 里配置 registry-mirrors，配置位置如下：

其余报错直接看容器日志，Docker Desktop 里点开对应服务即可复制完整 Log：