让 HeyGem.ai 在 WSL 中用上 GPUDocker 数字人服务部署与排障【免费下载链接】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-AvatarHeyGem.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 DesktopWSL2 后端内存 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 流量耐心等它拉完不要中途 CtrlC。完成后检查状态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刷新镜像社区迭代比较频繁不少问题已经在新版里修掉了。要点速览驱动在 Windows 侧WSL2 只做透传GPU 验证容器先跑通再启动服务Connection refused 多为 ASR 启动慢镜像源会失效不工作就换新的更多故障场景可参考项目内的 doc/常见问题.md完整部署流程与自查清单见 README_zh.md。如果你有同类环境的坑欢迎带着docker logs输出提 issue方便一起复现讨论。【免费下载链接】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），仅供参考 
长河君 · 2026/9/11 6:13:04 · 阅读 1.2k 让 HeyGem.ai 在 WSL 中用上 GPU：Docker 数字人服务部署与排障
让 HeyGem.ai 在 WSL 中用上 GPUDocker 数字人服务部署与排障【免费下载链接】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-AvatarHeyGem.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 DesktopWSL2 后端内存 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 流量耐心等它拉完不要中途 CtrlC。完成后检查状态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刷新镜像社区迭代比较频繁不少问题已经在新版里修掉了。要点速览驱动在 Windows 侧WSL2 只做透传GPU 验证容器先跑通再启动服务Connection refused 多为 ASR 启动慢镜像源会失效不工作就换新的更多故障场景可参考项目内的 doc/常见问题.md完整部署流程与自查清单见 README_zh.md。如果你有同类环境的坑欢迎带着docker logs输出提 issue方便一起复现讨论。【免费下载链接】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），仅供参考