HeyGem.ai 数字人项目 WSL 环境 Docker 无法调用 GPU 的排查与修复指南-港品优选

HeyGem.ai 数字人项目 WSL 环境 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（Duix.Avatar）是一款本地离线数字人视频合成工具，服务端由三个 Docker 容器构成，全部依赖 NVIDIA GPU 加速。在 WSL2 环境下，Docker 无法调用 GPU 会导致容器反复重启或启动即退出。本文按「现象定位—底层体检—组件装配—服务拉起—持续监控」的顺序，给出可复现的排查与修复路径。

现象识别：GPU 访问失败的典型信号

在 WSL2 上执行docker-compose -f docker-compose-linux.yml up -d后容器无法稳定运行，可对照以下表现快速判断问题是否出在 GPU 链路上：

docker ps中duix-avatar-gen-video、duix-avatar-asr、duix-avatar-tts的状态在Restarting与Exited (1)之间反复切换
容器日志出现CUDA not available、No CUDA-capable device detected、NVIDIA driver on this system一类报错
执行docker run --gpus all直接返回could not select device driver "nvidia"

三者都指向同一根因：Docker 与 NVIDIA 驱动之间缺少 NVIDIA Container Toolkit 桥接，容器拿不到 GPU 设备。下面从最底层开始逐层排除。

环境体检：先确认 WSL2 与宿主机驱动

GPU 直通的前提是宿主机满足条件，先排除 WSL2 版本与 NVIDIA 驱动两块最底层的短板。

确认 WSL2 版本与 Docker 后端

# 查看 WSL 发行版版本，VERSION 列应为 2 wsl --list --verbose

若版本为1，执行wsl --set-version <发行版名> 2与wsl --update升级；同时确认 Docker Desktop（4.12 及以上）使用 WSL2 后端，否则 GPU 直通不会生效。

验证宿主机驱动是否支持 WSL2 GPU 直通

在 WSL 内直接调用nvidia-smi，能输出显卡信息说明驱动已正确直通：

# 在 WSL 内确认驱动直通，应打印 GPU 型号、显存与驱动版本 nvidia-smi

支持 WSL2 直通的 NVIDIA 驱动门槛常见为 510.06 及以上，具体以 NVIDIA 官方发布为准。宿主机命令无输出或报驱动错误，需先在 Windows 侧安装/升级显卡驱动，再回到 WSL 复核。

组件装配：安装并验证 NVIDIA Container Toolkit

这是让 Docker 识别--gpus all与runtime: nvidia的关键组件，缺它则上层 compose 里的 GPU 配置全部失效。

配置 Docker 使用 NVIDIA 运行时

# 安装工具包并注册运行时（以 Ubuntu 22.04 为例，版本以实际为准） sudo apt-get install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtime=docker sudo systemctl restart docker

完成以上配置后，若上一步输出异常（nvidia-ctk未找到或报错），回到驱动体检环节确认nvidia-smi正常，再检查nvidia-container-toolkit是否安装完整。

用测试容器确认 GPU 直通

# 运行 CUDA 测试容器，容器内能打印 nvidia-smi 输出即直通成功 docker run --rm --gpus all nvidia/cuda:11.6.2-base-ubuntu20.04 nvidia-smi

预期输出与宿主机nvidia-smi一致，包含 GPU 型号、显存与驱动号。若该命令能跑通而业务容器仍失败，问题即落在 compose 配置或服务冷启动，而非 GPU 直通本身。

服务拉起：启动 HeyGem.ai 并核对 GPU 挂载

选择正确的 compose 文件

按显卡选择编排文件：常规 NVIDIA 显卡用deploy/docker-compose-linux.yml，RTX 50 系列（如 5090）用deploy/docker-compose-5090.yml。两份文件里的runtime: nvidia、NVIDIA_VISIBLE_DEVICES与deploy.resources.reservations.devices都已预设，无需手动补 GPU 参数。

# 在 deploy 目录拉起三个服务 cd deploy && docker-compose -f docker-compose-linux.yml up -d

核对三个服务的 GPU 挂载状态

# 确认三个容器均 Running docker ps --format "table {{.Names}}\t{{.Status}}"

三个容器duix-avatar-tts、duix-avatar-asr、duix-avatar-gen-video都应处于Up。再检查 GPU 设备是否真正注入到合成主容器：

# 检查 GPU 设备是否注入容器 docker inspect duix-avatar-gen-video --format '{{.HostConfig.Devices}}'

稳定性兜底：验证命令与故障速查

服务稳定后，用监控确认 GPU 利用率，合成任务期间 GPU-Util 维持在 60%–80% 属正常区间：

# 每 3 秒刷新 GPU 利用率 nvidia-smi -l 3

镜像拉取失败时，在/etc/docker/daemon.json增加registry-mirrors国内镜像源后重启 Docker 即可：

高频故障速查：

镜像拉取超时，报net/http: request canceled ... awaiting headers
- 属 Docker Hub 官方源不稳定，按上图配置国内镜像源，sudo systemctl restart docker后重新up -d
容器启动后报File not exists或Connection refused
- asr 服务冷启动较慢，需等日志出现start worker process就绪后再操作克隆形象；内存小于 16G 时可能起不来
报could not select device driver "nvidia"
- 回到「组件装配」一节确认nvidia-ctk runtime configure已执行且 Docker 已重启

整条排查链路为「WSL2/驱动体检 → 安装 NVIDIA Container Toolkit → 拉起三服务并核对 GPU 注入 → 监控利用率」。仍卡住时，携带nvidia-smi与docker logs <容器名>的完整输出到项目 Issue 区提问，响应更快。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析