Skip to content

Latest commit

 

History

History
361 lines (242 loc) · 13.7 KB

README.zh.adoc

File metadata and controls

361 lines (242 loc) · 13.7 KB

Comfy3D Windows 整合包

Screenshot

中文 | English

用于在 Windows 上运行 ComfyUI-3D-Pack 的整合包。

背景

“通过图片生成 3D 模型”是一项热门研究领域，且有众多开源项目， 但大部分项目以研究导向为主，开发者也多为 AI 研究人员而非专业软件开发者， 因而照顾到部署便利性的项目并不多。

ComfyUI-3D-Pack 试图将诸多模型的下载、使用整合到 ComfyUI 节点中，并提供示例工作流以便于用户理解、使用，其作者为此付出了很大努力。

但由于整个 AI3D 生态都是建立在面向研究的基础上的，用户在部署运行 AI3D 模型时，相当程度上是在复现研究者的开发环境。 强如 Stability AI，其 Stable Fast 3D 也需要运行时编译部分内容，且对 Windows 仅“实验性支持”，生态特点可见一斑。

与此同时，AI 领域依然在狂飙猛进，PyTorch 一年内从 2.1 飙到了 2.5，ComfyUI 也总是在第一时间适配最新技术。 但不是整个生态都能跟得上前锋的节奏，不少关键项目是要慢半拍的，比如 3D-Pack 要用到的 PyTorch Scatter 和 PyTorch3D 。 而更细分的研究领域就更跟不上了，在一些研究成果的展示中，使用的 PyTorch 甚至还停留在 1.x，作者们忙于新的研究也不太可能专门来更新维护旧的项目。

综上种种，导致了 3D-Pack 兼容性问题频发，这一点不应苛责相关作者。

我在创建维护 ComfyUI-Windows-Portable 的过程中处理了大量有关 3D-Pack 兼容问题的提问。 日积月累，有感而发。 遂创建了这个仓库，尝试定点解决相关问题。

兼容列表

当前整合包 pt25-cu124 基于 PyTorch 2.5.1 和 CUDA 12.4， 针对 2024/12/18 版本的 ComfyUI-3D-Pack 构建。

我在一块古老的 TITAN Xp (12GB VRAM) 上测试了所有样例工作流，结果如下表：

工作流 结果 截图 备注

(新) Trellis_Image_to_Mesh

🆗

🖼️

默认使用 xFormers 以保证兼容性，若想改用 Flash Attention 需定制（见文尾）

(新) Hunyuan3D_V1

🆗

🖼️

默认使用 xFormers 以保证兼容性，若想改用 Flash Attention 需定制（见文尾）

(新) StableFast3D / sf3d_by_stability_ai

🆗

🖼️

工作流来自 Stability AI

StableFast3D_to_Mesh

🆗

🖼️

工作流来自 3D-Pack

CharacterGen_Vanilla

🆗

🖼️

为了兼容 CharacterGen Loader 而使用了旧版 diffusers。未来考虑移除支持，以免影响新模型的使用。

CharacterGen_to_Unique3D

🆗

🖼️

可运行，但生成 Mesh 残缺，原因不明

CharacterGen_InstantMesh

❓

CharacterGen: 🆗; InstantMesh: OOM

CRM MVDiffusion_to_Craftsman

🆗

🖼️

为了兼容 CRM Loader 而使用了旧版 open-clip-torch，对其他模型暂无影响。

CRM MVDiffusion_to_Unique3D

🆗

🖼️

CRM_Img_to_Multi-views_to_CCMs_to_Mesh

🆗

🖼️

CRM MVDiffusion_to_InstantMesh

❌

InstantMesh 节点不匹配，可能不兼容

CRM_T2I_V2
CRM_T2I_V3

❓

模型尚未发布

Unique3D_All_Stages

🆗

🖼️

该工作流已包含 Unique3D 0~3 步骤，此处省略

Unique3D_with_Era3D_All

🆗

🖼️

上一版整合包不兼容，新版改进

[FlexiCubes] Multi-View Depth plus Optional Normal maps to 3D Mesh

🆗

🖼️

Era3D_to_InstantMesh

❓

🖼️

Era3D: 🆗; InstantMesh: OOM 或出方块

Multi-View-Images_to_Instant-NGP_to_ DiffRast_to_3DMesh

🆗

🖼️

上一版整合包不兼容，新版改进

MVDream_to_Large_Multiview_Gaussian_ Model_to_3DGS and_3DMesh

🆗

🖼️

上一版整合包不兼容，新版改进

Render_Mesh_and_3DGS_Example

🆗

🖼️

Triplane_Gaussian_Transformers_to_ 3DGS_and_3DMesh

🆗

🖼️

上一版整合包不兼容，新版改进

TripoSR_to_Mesh

🆗

🖼️

最易运行的模型

Using_Stack_Orbit_Camera_Poses_ to_conditioning_StableZero123

🆗

🖼️

Wonder3D_to_Large_Multiview_ Gaussian_Model_to_3DGS and_3DMesh

🆗

🖼️

上一版整合包不兼容，新版改进

Zero123Plus_to_InstantMesh

🆗

🖼️

额外信息

  • 相较于旧版 pt24-cu121，新版 pt25-cu124 在兼容性上没有退化，之前兼容的工作流均可继续工作。

  • 如需运行上表中不兼容的工作流，可尝试在 Linux 下运行。 Linux 下通过 GCC 生态编译 CUDA 核函数要顺畅得多，甚至可移植性也更好。 可以参考 3D-Pack 提供的 Dockerfile 或我的 Docker 镜像 。

使用步骤

1. 基本需求

1.1. 了解你的 GPU CUDA 架构版本，比如 RTX 2080 是 7.5，RTX 3090 是 8.6，RTX 4090 是 8.9。 完整列表可以看 这篇文章 。

1.2. 安装 CUDA Toolkit 12.4.1

  • 安装时仅需要选择 Libraries 与 Compilers

  • 如果显卡驱动较老（低于 550）， 安装 CUDA Toolkit 时可一并选择安装新驱动。该工具不会安装最新驱动，而是 CUDA 12.4.1 对应版本。如果已经安装了更新版本的驱动，则没有必要降级。

1.3. 安装 Visual Studio Build Tools 2022 （ 下载页面 | 安装程序 ）

  • 在安装界面选择“桌面C++开发”。

  • 如已安装 Visual Studio C++ 工作负载，不必重复安装。Build Tools 与普通 VS 基本相同，只是没有 GUI 界面。

  • （备忘）如果新版 VS 发布，你需要手动选择安装 17.x 版本（比如 17.12）以及 MSVC v143。参考 CUDA 12.4 编译器支持 。

2. 下载并配置

2.1. 在 Releases 页面下载压缩包：

2.2. （按需）改用中文脚本

  • 这些脚本全部为中文注释，并配置了大陆地区镜像站点，避免卡下载。

  • 将 中文脚本 目录下的文件复制到上一级目录下即可。

  • 脚本之间无调用关系，英文脚本文件可以移走或删除。

2.3. 编辑 !首次运行-编译安装依赖项.bat

将该行：

set TORCH_CUDA_ARCH_LIST=6.1+PTX

根据你的 GPU 架构 来修改。

比如 RTX 4060 Ti 用户应配置为：

set TORCH_CUDA_ARCH_LIST=8.9

2.4. 编辑 run_cn.bat

同样的，修改该行：

set TORCH_CUDA_ARCH_LIST=6.1+PTX

此外，该脚本中还有若干可选项，比如：

  • 配置代理（如遇到下载模型时卡住的情况，可尝试配置）

  • 是否自动打开浏览器

各项均有相应说明，可按需取消注释（删除行首的 rem）并编辑保存文件。

3. （可选）用于 Stable Fast 3D 的额外设置

SF3D 的模型不能直接下载，需要先同意协议，再使用身份令牌下载。

3.1. 注册／登录 Hugging Face。

3.2. 打开 Stable Fast 3D 仓库页面 ，填写表格，并同意 Stability AI 的协议。

3.3. 打开 Access Tokens 页面 ，创建一个只读 token。

3.4. 编辑启动脚本，找到：

rem set HF_TOKEN=

将其修改为：

set HF_TOKEN=你刚创建的只读token

比如：

set HF_TOKEN=hf_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefgh

之后在执行 SF3D 工作流时，加载器节点就会自行下载模型文件。

4. （可选）沙盒化

如果你想用 Sandboxie 来隔离整个 Python + ComfyUI 实例，接下来的步骤应在沙盒中进行。

因程序最多可下载上百 GiB 模型文件，考虑到 I/O 性能， 建议在“沙盒选项”-“资源访问”中，将程序主目录（Comfy3D_WinPortable）配置为“开放”。

5. 首次启动

5.1. 运行 !首次运行-编译安装依赖项.bat ，等待其完成，耗时约 10~30 分钟。如果过程中失败，再次运行该脚本即可。

5.2. 如果你需要运行 Unique3D 相关工作流，运行 下载Unique3D所需模型.bat 。

5.3. 运行 run_cn.bat ，待启动完毕后，程序会自动打开浏览器，或可手动访问： http://localhost:8188/

5.4. 在网页左侧，找到“工作流”按钮，点击后可看到 3D-Pack 样例工作流，相关的样例文件也已经放在 input 目录下。 打开一个工作流，点击“队列”或“Queue”即可开始执行。

如需关闭程序，关闭命令行窗口即可。

下一次启动程序时，只需运行 run_cn.bat 即可。

备用脚本

强制更新

不建议更新本整合包中的任何组件，无论是 Python 包、ComfyUI 还是自定义节点（”能用勿修“）。

但若确有需要，整合包中提供了一个脚本。你需要装有 Git for Windows，在 Git Bash 中运行该命令：

bash 使用国内镜像强制更新全部节点.sh

该脚本会 git-pull 更新 ComfyUI 和各节点，但 ComfyUI-3D-Pack 除外，该文件夹不是一个 git 仓库，不受 git 命令影响。

重新编译安装依赖项

运行 重新编译安装3D-Pack依赖项.bat 即可，注意该文件同样需要修改 TORCH_CUDA_ARCH_LIST 。

与“首次运行”脚本不同的是：

  • 该脚本不是下载特定版本的依赖项源代码，而是下载最新版本。考虑到用户执行该脚本时，很可能是“首次运行”脚本不起作用的情况，故此设计。

  • 该脚本会额外编译安装 kiuikit、utils3d 与 nvdiffrast。在我之前的测试中，这三者没必要放入“首次运行”脚本中，此处补全以防万一。

  • 该脚本会在 tmp_build 目录下保留临时文件，并保存轮子（.whl）文件，以便日后复用。注意这些二进制文件并非完整可移植，在其他机器上很可能报错。

DIY 打包

如需定制本项目，先 fork 本仓库，然后在 Actions 页面下找到 Build & Upload pt25-cu124 Package 工作流，再点击 Run workflow 即可。 流水线执行需约 20 分钟，之后在 Releases 页面即可找到待发布状态的压缩包。

定制举例：

  • 如果不需要使用 CharacterGen，可在 requirementsB.txt 中删除 diffusers==0.29.1

  • 如果不需要使用 CRM，可在 requirementsB.txt 中删除 open-clip-torch==2.24.0

  • 如使用 Ampere 及以上显卡，可在 requirements8.txt 中启用 Flash Attention