让 HeyGem.ai 在 WSL 中用上 GPU：Docker 数字人服务部署与排障-育师

让 HeyGem.ai 在 WSL 中用上 GPU：Docker 数字人服务部署与排障

【免费下载链接】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 在 Windows 机器上本地部署时，最常见的卡点是容器拿不到 GPU：服务反复退出，或者起来了但推理慢得像卡死。下面以 WSL2 环境为主线，把 Windows 驱动、Docker 后端到三个数字人服务这条链路逐段打通，照做即可跑通。适合有基础 Linux 和命令行经验、但没摸过这套部署链路的开发者。

读完本文你将得到：

一套 WSL2 + GPU 驱动环境自查命令
一条可复用的 Docker GPU 访问验证容器命令
三类高频故障（拉镜像超时、Connection refused、容器反复重启）的定位方法

摸清环境底线 🖥️

这套部署的依赖链是：Windows 端驱动 → WSL2 透传 → Docker 运行时。注意一个反直觉的点：GPU 驱动不装在 WSL 里，而是装在 Windows 侧，WSL2 负责透传。所以每一层都要单独确认。

确认 WSL2 版本

wsl --list --verbose

预期你会看到目标发行版的 VERSION 列为 2。如果显示 1，执行下面两条命令升级：

# 将目标发行版升级到 WSL2 并刷新 WSL 组件 wsl --set-version Ubuntu-22.04 2 wsl --update

升级后重跑第一条命令确认版本。

确认驱动真正可用

在 Windows 侧通过 Windows Update 或 NVIDIA 官方渠道把显卡驱动装好，然后直接在 WSL 里执行：

nvidia-smi

预期你会看到显卡型号、驱动版本和 CUDA 版本。只要这条命令能出信息，透传就没问题。如果它报错，后面所有容器的 GPU 挂载都会失败，先别往下走，把驱动问题解决了再说。

环境底线一览：

Windows 10 19042.1526 或更高版本
NVIDIA 独显 + Windows 侧驱动已正确安装
Docker Desktop（WSL2 后端）
内存 32G 及以上，16G 时 ASR 服务可能起不来

驱动这关过了，下一环就是让 Docker 里的容器也看到 GPU。

打通 GPU 调用链路

开启 Docker Desktop 的 WSL2 后端

在 Docker Desktop 的 Settings → Resources 中，把目标 WSL 发行版的 WSL Integration 打开。如果 C 盘空闲空间不足 100G，可以在同一页的 Disk image location 里点 Browse 换到空间充足的磁盘，再 Apply & restart。

验证容器能看到 GPU

部署前先跑一条验证容器，这是整条链路的试金石：

# 用官方 CUDA 基础镜像在容器内执行 nvidia-smi，验证 GPU 透传 docker run --rm --gpus all nvidia/cuda:11.6.2-base-ubuntu20.04 nvidia-smi

预期你会看到和宿主机里nvidia-smi基本一致的 GPU 信息。如果报could not select device driver "nvidia"或No CUDA-capable device detected，说明链路断在驱动或 WSL 集成上，回到上一节逐项重查。这一步通过后，后面三个服务基本可以直接拉起。

拉通服务并确认健康

链路验证通过后，部署本身很轻。先拉一份源码：

# 获取项目代码 git clone https://gitcode.com/GitHub_Trending/he/HeyGem.ai

三个服务（ASR、TTS、视频合成）在 deploy/docker-compose-linux.yml 里都声明了runtime: nvidia，启动命令如下：

# 启动三个数字人服务（镜像体积大，拉取约需半小时） cd deploy && docker-compose -f docker-compose-linux.yml up -d

这里容易踩坑：镜像下载约 70G 流量，耐心等它拉完，不要中途 Ctrl+C。完成后检查状态：

docker ps

预期你会看到duix-avatar-tts、duix-avatar-asr、duix-avatar-gen-video三个容器均为 Running。

三个容器对外暴露的端口分别是 18180（语音合成）、10095（语音识别）、8383（视频合成）。服务全绿之后，打开客户端创建一个模特，就能端到端验证了。另外，如果你用的是 50 系列显卡（30、40 系列在 cuda 12.8 下也可参考），换用 deploy/docker-compose-5090.yml 启动即可。

服务起来了不等于万事大吉，接下来这几类报错出现频率最高。

高频卡点排查 🔍

拉镜像超时或连接失败

up -d失败、日志里出现Get "https://registry-1.docker.io/v2/": ... timeout，基本就是 Docker Hub 官方源连不上。在 Docker Desktop 的 Docker Engine 配置里加上镜像源，再 Apply & restart：

{ "registry-mirrors": [ "https://docker.zhai.cm", "https://a.ussh.net", "https://hub.littlediary.cn" ] }

这里容易踩坑：镜像源会随时间失效，配置里的地址不生效时，需要自己找一份当前可用的源替换进去。

定制模特报 Connection refused

创建模特时 TTS 服务日志出现[Errno 111] Connection refused，常见原因是 ASR 服务启动慢——服务刚起来时等几分钟再操作即可。另一个隐藏条件是内存：机器内存太小（比如 16G）时 ASR 可能根本起不来，对照前面的推荐配置先检查硬件。

查日志的口诀：服务端用docker logs -f <容器名>分别看三个容器；客户端日志在AppData\Roaming\heygem.ai\logs\main.log，两边对照才能判断问题出在哪一端。

容器反复重启

TTS 服务一直重启的话，先用docker logs <容器名>看退出原因，多数还是 GPU 链路问题（回到前文的验证容器命令重跑一遍）或镜像版本过旧。到deploy目录重新执行docker-compose -f docker-compose-linux.yml up -d刷新镜像，社区迭代比较频繁，不少问题已经在新版里修掉了。