由社区开发者 Saganaki22 制作的 Pixal3D-ComfyUI 节点，将腾讯 ARC 实验室开源的 Pixal3D 模型引入了 ComfyUI 工作流。通过该节点，用户只需一张图片，即可在本地生成高质量的 3D 模型并导出为带贴图的 .glb 格式。

• GitHub：https://github.com/Saganaki22/Pixal3D-ComfyUI

该节点不仅完整保留了原模型的核心能力，还针对 ComfyUI 的使用场景进行了深度优化，支持 FlashAttention 2/3 加速、DynamicVRAM 动态显存管理以及手动相机控制，极大地降低了 3D 内容创作的门槛。

核心功能与优势

• 单图生成 3D：输入单张图像，自动重建几何结构并生成纹理，输出标准的 .glb 文件。
• 高性能推理：集成 FlashAttention 2/3，显著提升生成速度。
• 显存优化：支持 DynamicVRAM 和模型卸载机制，让中低端显卡也能流畅运行。
• 灵活控制：提供手动相机参数调整、背景去除（RMBG）及几何细化（NAF）等高级选项。

安装指南

1. 推荐方式：ComfyUI Manager

1. 打开 ComfyUI Manager。
2. 搜索 Pixal3D，确认作者为 Saganaki22。
3. 安装 稳定版（Stable）（建议避免使用 Nightly 版本以确保稳定性）。
4. 重启 ComfyUI。
5. 关键步骤：首次使用前，务必运行工作流中的 Pixal3D Environment Check 节点，检查环境依赖是否完整。

2. 手动安装

若需自定义环境，可在终端执行以下命令：

cd ComfyUI\custom_nodes
git clone https://github.com/Saganaki22/Pixal3D-ComfyUI.git
cd Pixal3D-ComfyUI
python -m pip install -r requirements.txt
python install.py --check

注意：requirements.txt 仅安装基础 Python 库，核心 CUDA 组件需手动匹配安装。

Windows 环境依赖配置（重点）

Pixal3D 高度依赖 CUDA 加速，以下组件必须与你的 Python、PyTorch、CUDA 及 GPU 架构 严格匹配。建议使用 --no-deps 安装预编译轮子以避免冲突。

必需组件

1. PyTorch CUDA：确保 torch.cuda.is_available() 为 True。
2. Attention：flash_attn (FA2) 或 flash_attn_interface (FA3)。
3. Pixal3D CUDA Kernels：flex_gemm_ap, cumesh_vb, o_voxel_vb_ap, drtk。
4. NATTEN（可选）：仅在启用 strict NAF 模式时需要带 libnatten 的版本。

安装示例（Python 3.12 + PyTorch 2.10 + CUDA 13.0 + Blackwell sm120）

venv\Scripts\python.exe -m pip install --no-deps ^
  "https://github.com/PozzettiAndrea/cuda-wheels/releases/download/flex_gemm_ap-latest/flex_gemm_ap-1.0.0%2Bcu130torch2.10-cp312-cp312-win_amd64.whl" ^
  "https://github.com/PozzettiAndrea/cuda-wheels/releases/download/cumesh_vb-latest/cumesh_vb-1.0%2Bcu130torch2.10-cp312-cp312-win_amd64.whl" ^
  "https://github.com/PozzettiAndrea/cuda-wheels/releases/download/o_voxel_vb_ap-latest/o_voxel_vb_ap-0.0.1%2Bcu130torch2.10-cp312-cp312-win_amd64.whl" ^
  "https://github.com/PozzettiAndrea/cuda-wheels/releases/download/drtk-latest/drtk-0.1.0%2Bcu130torch2.10-cp312-cp312-win_amd64.whl" ^
  "https://huggingface.co/drbaph/NATTEN-0.21.6-torch2100cu130-cp312-cp312-win_amd64/resolve/main/natten-0.21.6+torch2100cu130-cp312-cp312-win_amd64.whl"

提示：若你的环境不匹配上述 NATTEN 轮子，请移除最后一行，并在节点中设置 naf_mode=fallback_if_missing。

模型下载

若未开启自动下载，需手动将以下模型放入指定目录：

推荐设置与显存优化

1. 通用推荐（Windows）

• Pixal3D Model Loader:
  • attention_backend: auto
  • vram_mode: dynamic_vram
  • naf_mode: fallback_if_missing (除非确认 NATTEN 安装正确)
  • preload_naf: false
• Pixal3D Image To 3D:
  • pipeline_type: 1024_cascade (平衡速度与质量)

2. 低显存模式 (<12GB)

• Pixal3D Model Loader:
  • vram_mode: hybrid_low_vram
  • load_moge: false
  • load_rembg: false
• Pixal3D Image To 3D:
  • camera_mode: manual
  • background_mode: keep_alpha (需输入透明背景图)

常见问题排查

• Q: 提示 flash_attn 或缺少 CUDA Kernels？
  • A: 请检查是否安装了与当前 PyTorch/CUDA 版本完全匹配的预编译轮子。
• Q: natten.HAS_LIBNATTEN 为 False？
  • A: 说明未安装带 CUDA 支持的 NATTEN。请设置 naf_mode=fallback_if_missing 以使用 fallback 模式（速度稍慢但兼容性好）。
• Q: RMBG-2.0 下载失败？
  • A: 该模型为 Hugging Face Gated Model，需申请权限并配置 HF_TOKEN，或改用透明背景图输入。
• Q: 生成的 GLB 模型碎裂？
  • A: 尝试开启 remesh=true，并提高 decimation_target 值（如 1,000,000）。