【3D Gen 入坑（1）】Hunyuan3D-Paint 2.1 安装 `custom_rasterizer` 报错完整排查

Hunyuan3D-Paint 2.1 安装 custom_rasterizer 报错完整排查

适用场景：在 hy3dpaint/custom_rasterizer 目录执行
pip install . 或 pip install -e . 时出现 Failed building wheel / No module named ‘torch’ / nvcc fatal 等编译错误。

---

一、问题现象

1. pip install 日志开头正常，但到 Building wheel for custom_rasterizer 阶段报错退出。
2. 典型报错片段（按出现顺序）
   • ModuleNotFoundError: No module named 'torch'
   • Your compiler ... is not compatible with the compiler Pytorch was built with
   • /bin/sh: ... g++-11: No such file or directory
   • nvcc fatal : Failed to preprocess host compiler properties.

---

二、根因分析

1. pip 隔离环境导致缺少 torch
   pip install -e . 默认会临时创建 “build-isolation” 环境。里面没装 PyTorch，cpp_extension 找不到头文件而直接报错。

2. CUDA 12.4 对 GCC 13 不兼容
   系统原本只有 gcc-13；nvcc 解析 C 头文件时遇到 _Float128 类型即失败。

3. nvcc 找不到正确的 host compiler
   我们通过 conda 安装了 gcc-11，但默认可执行文件名是
   x86_64-conda-linux-gnu-g++（无后缀）。
   路径写错就会触发 “No such file or directory”。

---

三、解决方案总览

环节	目标	命令 / 处理方式
1. 安装匹配的 GCC 11	让 nvcc 使用受支持的版本	conda install -c conda-forge gcc_linux-64=11 gxx_linux-64=11
2. 指定编译器变量	nvcc & pip 都用 gcc-11	bash<br>export CUDAHOSTCXX=$CONDA_PREFIX/bin/x86_64-conda-linux-gnu-g++<br>export CC=$CUDAHOSTCXX<br>export CXX=$CUDAHOSTCXX<br>export PATH=$CONDA_PREFIX/bin:$PATH<br>hash -r<br>
3. 禁用 build-isolation	让 pip 直接用当前环境（含 torch）	普通安装：pip install . --no-build-isolation --no-deps -i https://pypi.tuna.tsinghua.edu.cn/simple 可编辑：PIP_NO_BUILD_ISOLATION=1 pip install -e . --no-deps -i https://pypi.tuna.tsinghua.edu.cn/simple
4. 验证	导入 .so 并检查函数	python<br>import custom_rasterizer_kernel as k<br>print(hasattr(k, "rasterize_image")) # True 即成功<br>

---

四、完整操作步骤

下文假设 conda 环境名为 hunyuan21_wenda，CUDA Toolkit 路径 /usr/local/cuda-12.4，请按实际情况调整。

1. 准备 conda 环境并安装 GCC-11

conda activate /opt/.../envs/hunyuan21_wenda
conda install -c conda-forge gcc_linux-64=11 gxx_linux-64=11   # 不会覆盖 gcc-13

2. 配置编译器变量

# 让 nvcc & pip 都用 gcc-11
export CUDAHOSTCXX=$CONDA_PREFIX/bin/x86_64-conda-linux-gnu-g++
export CC=$CUDAHOSTCXX
export CXX=$CUDAHOSTCXX

# 确保 conda/bin 在 PATH 最前
export PATH=$CONDA_PREFIX/bin:$PATH
hash -r

# 验证
$CUDAHOSTCXX --version      # 输出 gcc 11.4.0 即 OK

可将上述 export 写入 ~/.bashrc，以后无需重复设置。

3. 进入源码目录并清理残留

cd /opt/.../Hunyuan3D-2.1/hy3dpaint/custom_rasterizer
pip uninstall -y custom_rasterizer custom_rasterizer_kernel 2>/dev/null
rm -rf build dist *.egg-info

4. 编译安装

方式 A：普通安装（最推荐）

pip install . --no-build-isolation --no-deps \
    -i https://pypi.tuna.tsinghua.edu.cn/simple

方式 B：可编辑安装

PIP_NO_BUILD_ISOLATION=1 \
pip install -e . --no-deps \
    -i https://pypi.tuna.tsinghua.edu.cn/simple

成功后日志应包含：

Building wheel for custom_rasterizer (setup.py) ... done
Successfully installed custom_rasterizer-0.1

5. 快速自测

python - <<'PY'
import custom_rasterizer_kernel as k
print("rasterize_image 函数存在？", hasattr(k, "rasterize_image"))
PY

若输出 True 或 rasterize_image 函数存在？ True，编译链全部打通。

---

五、常见坑与排查清单

现象	排查点
No module named 'torch'	忘记 --no-build-isolation 或未安装 torch
Your compiler ... not compatible with the compiler Pytorch was built with	用的是系统 /usr/bin/g++，未设置 CC/CXX
/bin/sh: ... g++-11: No such file or directory	路径写成 g++-11 而实际文件无后缀
nvcc fatal : Failed to preprocess host compiler properties	CUDAHOSTCXX 指向不存在的文件或 gcc 版本过高（≥13）

---

六、总结

1. 编译器三选一：GCC 11 / 12 / 9 均与 CUDA 12.x 兼容，选 11 最省事。
2. pip 隔离环境 常导致 “缺包” 问题，开发者插件建议一律加 --no-build-isolation。
3. 环境变量 CUDAHOSTCXX 决定 nvcc 的 host compiler，必须指向真实可执行文件。
4. Hunyuan3D-Paint 2.1 编译通过后即可继续执行 bash run_local.sh ... 等下游脚本。

祝大家少踩坑，愉快玩转 Hunyuan3D！