Windows WSL2运行SAM3DBody-cpp CUDA加速保姆级教程:避开6个高频踩坑点

原创2026-11-02 18:45:381,607 阅读

Windows WSL2运行SAM3DBody-cpp CUDA加速保姆级教程:避开6个高频踩坑点

SAM3DBody-cpp 是一款纯 C++ 的单摄像头实时 3D 全身重建推理引擎:给它一张照片或一段视频,它就能输出全身 3D 网格、70 个关节骨骼点(含手部),并支持多人 BVH 动作捕捉导出。在 Windows 上跑它,推荐路线是 WSL2 + CUDA GPU 加速。本文带你从零走通完整流程,并提前拆掉 6 个新手高频踩坑点,让你一次跑通、不返工。

SAM3DBody-cpp 实时3D全身重建演示(CUDA加速多人效果)

一、准备工作:先在 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 准备了独立安装包:

  1. 前往 NVIDIA 官网 CUDA 下载页,筛选条件选 Linux → x86_64 → WSL-Ubuntu(本文以 12.2 为例)
  2. 按页面给出的 wget + dpkg -i 两条命令安装 .deb 包
  3. 验证:
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。

  1. 前往 NVIDIA 官网 cuDNN 下载页,选 Linux → x86_64 → Ubuntu、cuDNN for CUDA 12,按页面命令安装
  2. 刷新动态库缓存并确认:
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 身体网格叠加在画面上的效果:

SAM3DBody-cpp 单摄像头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

📎 延伸阅读

跑通之后,你就拥有了一个无需 Python 运行时、可多人追踪、能直接产出动作捕捉文件的 3D 人体重建工具链。祝顺利!

登录后查看全文
SAM3DBody-cpp