Windows WSL2运行SAM3DBody-cpp CUDA加速保姆级教程:避开6个高频踩坑点
Windows WSL2运行SAM3DBody-cpp CUDA加速保姆级教程:避开6个高频踩坑点
SAM3DBody-cpp 是一款纯 C++ 的单摄像头实时 3D 全身重建推理引擎:给它一张照片或一段视频,它就能输出全身 3D 网格、70 个关节骨骼点(含手部),并支持多人 BVH 动作捕捉导出。在 Windows 上跑它,推荐路线是 WSL2 + CUDA GPU 加速。本文带你从零走通完整流程,并提前拆掉 6 个新手高频踩坑点,让你一次跑通、不返工。
一、准备工作:先在 WSL 里确认 GPU 可见
⚠️ 坑点 1:
nvidia-smi看不到显卡,后面所有步骤都会失败
WSL2 的 GPU 直通能力来自 Windows 侧的 NVIDIA 驱动,与 Linux 里装什么无关。开始前请确认三件事:
- ✅ Windows 10/11 已启用 WSL2,并安装了一个 Ubuntu 发行版
- ✅ Windows 端已安装最新 NVIDIA 显卡驱动(去 NVIDIA 官网驱动页下载 Windows 版)
- ✅ 进入 WSL 后执行下面命令,能看到你的 GPU:
nvidia-smi
如果这里看不到显卡,先修 Windows 驱动 / 确认用的是 WSL2 而非 WSL1——否则后文全部白做。
二、安装 CUDA 12 工具包(只装工具包,别装驱动)
⚠️ 坑点 2:在 WSL 里装了完整版 Linux NVIDIA 驱动
这是 WSL2 用户最容易犯的错。GPU 驱动必须留在 Windows 侧,WSL 内部只装 CUDA 工具包 + cuDNN,而且官方专门为 WSL 准备了独立安装包:
- 前往 NVIDIA 官网 CUDA 下载页,筛选条件选 Linux → x86_64 → WSL-Ubuntu(本文以 12.2 为例)
- 按页面给出的
wget+dpkg -i两条命令安装.deb包 - 验证:
nvcc --version
# 看到 "release 12.x" 即成功
💡 版本要求:CUDA 12.x(ONNX Runtime 1.20.1 GPU 版的要求,见 knowledge/DEPENDENCIES.md)。
三、安装 cuDNN 9(CUDA EP 的命根子)
⚠️ 坑点 3:cuDNN 装了 8 而不是 9
cuDNN 8 与本项目 不兼容,它是 Failed to load library libonnxruntime_providers_cuda.so 这个报错的第一大元凶。ONNX Runtime ≥ 1.19 只认 cuDNN 9。
- 前往 NVIDIA 官网 cuDNN 下载页,选 Linux → x86_64 → Ubuntu、cuDNN for CUDA 12,按页面命令安装
- 刷新动态库缓存并确认:
sudo ldconfig
ldconfig -p | grep -i cudnn
# 必须看到 libcudnn.so.9
四、安装 gcc-12 并拉取代码
较新版本的 Ubuntu 默认源里没有 gcc-12,需要先添加已归档的 lunar (23.04) 源。编辑源文件:
sudo nano /etc/apt/sources.list.d/ubuntu.sources
文件末尾追加:
Types: deb
URIs: http://old-releases.ubuntu.com/ubuntu/
Suites: lunar
Components: universe
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
然后:
sudo apt update
sudo apt install gcc-12
如果你的 Ubuntu 已提供 gcc-12(
apt-cache policy gcc-12能看到候选版本),可跳过这一步。
接着克隆仓库并构建:
git clone https://gitcode.com/gh_mirrors/sa/SAM3DBody-cpp
cd SAM3DBody-cpp
💡 快捷方式:
bash scripts/setup.sh --cuda-arch 89可一条命令完成装依赖、下模型(~5.2 GB)、编译。注意 WSL 下脚本询问"是否安装 NVIDIA drivers"时请选 N(驱动在 Windows 侧),CUDA 工具包询问选 Y(若尚未安装)。下面继续看手动流程。
五、编译:选对 CUDA 架构号
⚠️ 坑点 6:
CMAKE_CUDA_ARCHITECTURES没设或设错
架构号对应你的显卡世代,填错会导致编译产物在 GPU 上直接崩:
| 架构号 | 对应显卡 |
|---|---|
89 |
Ada:RTX 40 系列(如 4060、4090) |
86 |
Ampere:RTX 30 系列 |
75 |
Turing:RTX 20 系列 |
参考 scripts/build.sh 的写法,手动编译:
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_CUDA_ARCHITECTURES=89
make -j$(nproc)
CMake 会自动下载 ONNX Runtime 1.20.1 到 build/onnxruntime_dl/,无需手动处理。
六、修复 PATH:Windows 污染是隐形大坑
⚠️ 坑点 4:WSL 把 Windows 的 PATH 拼了进来,加载器找错了 GPU 库
WSL 会把所有 Windows 的 PATH 条目追加进 Linux 环境,动态加载器可能解析到 Windows 侧的 GPU 驱动而不是 WSL 的 /usr/lib/wsl/lib。运行前手动导出干净路径:
export PATH=/usr/local/cuda-12.2/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
export LD_LIBRARY_PATH=/usr/lib/wsl/lib:/usr/local/cuda-12.2/lib64
把 cuda-12.2 换成你的实际版本。想一劳永逸,把这两行 export 追加到 ~/.bashrc 并 source ~/.bashrc。
七、验证 CUDA EP 并首次运行
先验证,再运行。 下面这条命令输出为空 = CUDA Provider 依赖全部就绪:
ldd build/onnxruntime_dl/lib/libonnxruntime_providers_cuda.so | grep -i "not found"
⚠️ 坑点 5:把
Could not find an implementation for Expand(13)当 CPU bug 去修这个报错(以及 decoder 里的
MatMul(13)版)不是 CPU 的 bug,而是 CUDA EP 加载失败后的副作用:标准backbone.onnx是 BFloat16 格式,只支持 CUDA 执行提供器;CUDA EP 加载失败后 ORT 静默回退 CPU,然后撞死在第一个 BF16 算子上。正确做法是回上面用ldd排查缺哪个库(通常是 cuDNN 9 或 CUDA 12 运行库),而不是去追Expand错误本身。
验证通过后,跑摄像头实时演示或离线视频:
./scripts/webcam.sh
./scripts/video.sh --from clip.mp4
首次运行若 onnx/ 目录缺失会自动从 HuggingFace 拉取 CUDA 版模型(约 5.2 GB,中断可续传)。成功运行后你会看到实时 3D 身体网格叠加在画面上的效果:
进一步玩法:加 --bvh ./p.bvh 可输出每个检测人物的标准 BVH 文件(p_0.bvh、p_1.bvh…),可直接导入 Blender,仓库还附带了驱动 MakeHuman 角色的插件 blender/blender_bvh_plugin.py。
八、6 个高频踩坑点速查表
| # | 症状 / 表现 | 根因 | 解法 |
|---|---|---|---|
| 1 | nvidia-smi 看不到显卡 |
Windows 驱动缺失或用了 WSL1 | Windows 侧装最新 NVIDIA 驱动,确认 WSL2 |
| 2 | 装了 Linux 版 NVIDIA 驱动到 WSL | 驱动应留在 Windows 侧 | WSL 内只装 WSL-Ubuntu 版 CUDA 工具包 + cuDNN |
| 3 | Failed to load library libonnxruntime_providers_cuda.so |
cuDNN 8 不兼容(需 9) | 装 cuDNN 9,ldconfig -p | grep cudnn 确认 libcudnn.so.9 |
| 4 | CUDA 库加载异常 / 找错驱动 | Windows PATH 污染 WSL 环境 |
export LD_LIBRARY_PATH=/usr/lib/wsl/lib:...(见第六节) |
| 5 | Could not find an implementation for Expand(13) |
CUDA EP 失败回退 CPU,撞 BF16 算子 | 用 ldd ... | grep "not found" 修好 CUDA EP,别追 Expand |
| 6 | 编译通过但运行崩溃 / 无加速 | CMAKE_CUDA_ARCHITECTURES 填错 |
按显卡世代填 89 / 86 / 75 |
📎 延伸阅读
- WSL2 完整官方设置指南:knowledge/WSL.md
- 运行时依赖与故障排查矩阵:knowledge/DEPENDENCIES.md
- 输出格式(BVH/CSV/关键点)说明:knowledge/OUTPUT.md
- 一键环境脚本:scripts/setup.sh
- 构建与运行脚本:scripts/build.sh、scripts/webcam.sh、scripts/video.sh
跑通之后,你就拥有了一个无需 Python 运行时、可多人追踪、能直接产出动作捕捉文件的 3D 人体重建工具链。祝顺利!

