企业官网建设流程全解析

HeyGem.ai WSL Docker GPU 部署完整指南：先排掉 4 类故障再动手

【免费下载链接】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 数字人项目，针对 WSL + Docker 部署时"Docker GPU 识别不到"的常见故障，讲解 WSL 无法识别 GPU、Docker 调不动 GPU、服务反复重启等现象的定位方法，并完成三个服务的本地部署与验收。

为什么 WSL 里的 Docker 识别不到 GPU：先搞懂这一点

WSL2 本质上是一台轻量虚拟机，物理显卡长在 Windows 一侧。只要 Windows 端的 NVIDIA 驱动支持 WSL2 直通（510.06 及以上版本），并且 Docker Desktop 使用 WSL2 后端，容器就能直接拿到物理 GPU，WSL 里面反而不用装任何东西。

所以"WSL 下 Docker 识别不到 GPU"这类问题，多数出在 Windows 驱动或 Docker Desktop 设置上，而不是 WSL 内部。纯 Linux 裸机用户则需要在系统里装 nvidia-container-toolkit，这条线下面单独说。

场景一：WSL 里 nvidia-smi 打不开，先查 Windows 侧

在 WSL 终端执行 nvidia-smi，如果提示 command not found 或找不到相关库，说明 GPU 直通链路断了。按两步查：

先看 WSL 版本。在 Windows 终端执行wsl --list --verbose，如果 VERSION 一列显示 1，就要升级到 2：

wsl --set-version Ubuntu 2 wsl --update

其中 Ubuntu 换成wsl --list显示的实际发行版名。

再确认 Windows 上的 NVIDIA 驱动版本，低于 510.06 需要重新安装新驱动。

改完后回 WSL 再跑一次 nvidia-smi：能看到显卡型号、驱动版本、显存，即直通生效；仍无输出就先重启一次 Windows 再试。

场景二：docker run --gpus all 报错，查两处开关

驱动没问题后，验证 Docker 是否真的能调用 GPU。拉一个测试镜像跑一遍：

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

看到显卡信息输出就是成功；如果报could not select device driver之类的错误，打开 Docker Desktop 设置，确认"Use WSL 2 based engine"已开启，并且你的 WSL 发行版对应的那一行 WSL 集成开关是开着的，改完重启 Docker 再验证。

纯 Linux 裸机用户，先安装 nvidia-container-toolkit（步骤见项目中文 README的 NVIDIA 安装一节），然后重复上面这条验证命令，以输出显卡信息为准。

场景三：拉镜像失败或特别慢，先配镜像源

HeyGem.ai 要拉三个镜像，体积不小。如果卡在拉取或超时报错，打开 Docker Desktop 的 Settings → Docker Engine，在配置里加一个 registry-mirrors 数组，填可用镜像地址后点 Apply & restart（镜像源清单可参考项目自带的常见问题文档）：

纯 Linux 用户改的是/etc/docker/daemon.json里的同一字段，改完重启 docker 服务。配完再拉，正常应该能看到持续的下载进度；如果依旧秒失败，多半是网络问题，换个镜像地址重试。

场景四：服务起来了又反复重启，查三处

镜像就绪后启动服务。若容器反复重启，或客户端报 Connection refused，按顺序查：

1. 看容器日志。Docker Desktop 里点开容器，用右侧的复制按钮把日志拷出来。ASR 服务（duix-avatar-asr）加载较慢，启动后等几分钟再操作，前几次连接被拒不一定是故障。
2. 看显存和内存。视频合成服务建议 8GB 以上显存；WSL2 默认大约只分配一半物理内存，内存小的机器建议在%LOCALAPPDATA%\wsl\wslconfig里显式设置 memory 大小。
3. 看版本。项目更新频繁，拉取最新代码后到/deploy目录重新执行启动命令。

部署与验收：三条命令跑起 HeyGem.ai 三服务

克隆代码（本地已有代码可跳过这一步）：

git clone https://gitcode.com/GitHub_Trending/he/HeyGem.ai

启动服务。GPU 运行时和显存参数在 docker-compose 配置文件 里已预置，直接按它启动即可：

cd HeyGem.ai/deploy docker-compose -f docker-compose-linux.yml up -d

首次执行要等镜像下载完成，耗时视网速而定。随后检查状态：

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

duix-avatar-tts、duix-avatar-asr、duix-avatar-gen-video 三个服务全部处于 Up，即部署成功。此时安装客户端，进入创建页就能合成第一条数字人视频。

视频合成时怎么观察 GPU 占用

合成过程中开一个终端持续观察：

nvidia-smi -l 3

GPU-Util 一列持续非零，说明容器确实吃到了 GPU，属正常负载；如果合成视频时它一直是 0，回到场景二重新排查。其余报错情况，可按常见问题文档中的自查步骤对照处理。

【免费下载链接】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