%20(1).png)
ComfyUI-Hunyuan3D-1-wrapper 插件完整教程
1. 插件简介
插件地址： https://github.com/jtydhr88/ComfyUI-Hunyuan3D-1-wrapper
这个插件就像一个神奇的魔法盒子，能把你的文字描述或者图片变成真正的3D模型！想象一下，你只需要输入"一只可爱的小兔子在吃胡萝卜"，或者上传一张图片，这个插件就能帮你生成一个完整的3D模型，就像拿着3D打印机一样厉害。
主要功能：
- 文字生成3D模型（就像跟电脑说话让它做3D模型）
- 图片生成3D模型（把平面图片变成立体模型）
- 支持多种3D格式输出（可以导入到其他3D软件继续编辑）
2. 如何安装
重要提醒： 这个插件比较"娇气"，建议你用一个全新的ComfyUI来安装，就像给它单独准备一个房间一样。
通用安装方法：
-
下载插件
- 在ComfyUI的
custom_nodes文件夹里，用git克隆这个项目 - 或者直接下载ZIP文件解压到
custom_nodes文件夹
- 在ComfyUI的
-
安装依赖
- 这个插件需要一些"营养品"才能正常工作
- 主要需要安装：PyTorch3D、Open3D、nvdiffrast等
-
下载模型文件
- 需要下载Hunyuan3D的模型文件
- 放在指定的
weights文件夹里
3. 节点详细解析
基于GitHub页面信息和工作流程，这个插件主要包含以下节点：
3.1 HunyuanDiTText2ImageNode - 文字转图片节点
这个节点就像一个"想象画家"，你告诉它你想要什么，它就先画出来。
参数详解：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 提示词 | prompt | 文本输入 | "一只可爱的兔子在吃胡萝卜, 白色背景,3D风格,最佳质量" | 就像跟画家说话，告诉它你想要什么样的画面 | 文本提示词，用于生成图像的描述 | 输入你想要的物体描述，记住要加上"白色背景,3D风格,最佳质量" |
| 负面提示词 | negative_prompt | 文本输入 | 保持默认 | 告诉电脑你不想要的东西，比如"不要模糊" | 负面提示词，用于避免不想要的特征 | 输入你不想看到的效果，比如"模糊，变形，低质量" |
| 种子值 | seed | 数字 | 随机或固定值 | 就像抽奖的号码，相同号码会得到相同结果 | 随机种子，控制生成的随机性 | 固定一个数字可以重复生成相同效果 |
| 步数 | steps | 数字 | 20-50 | 就像画家画画的次数，越多越精细但越慢 | 扩散步数，控制生成质量 | 新手建议用20-30，追求质量用50+ |
| 引导强度 | cfg_scale | 数字 | 7-12 | 控制电脑有多听话，数字越大越按你说的做 | 分类器自由引导强度 | 7-9比较自然，10-12更严格按提示词 |
3.2 HunyuanText2MeshNode - 文字转3D模型节点
这个节点就像一个"3D雕刻师"，把文字直接变成立体模型。
参数详解：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 提示词 | prompt | 文本输入 | "一只小猫, 白色背景,3D风格,最佳质量" | 告诉3D雕刻师你要什么样的模型 | 3D生成的文本描述 | 描述你想要的3D物体，必须包含特定后缀 |
| 种子值 | seed | 数字 | 随机或固定 | 控制3D模型的随机性 | 3D生成的随机种子 | 固定种子可以生成相同的3D模型 |
| 生成步数 | steps | 数字 | 50-100 | 3D模型雕刻的精细程度 | 3D生成的迭代步数 | 步数越多模型越精细，但时间越长 |
| 引导强度 | guidance_scale | 数字 | 100-300 | 控制模型按文字描述的严格程度 | 3D生成的引导强度 | 数值越高越严格按照提示词生成 |
3.3 HunyuanImage2MeshNode - 图片转3D模型节点
这个节点就像一个"魔法师"，能把平面图片变成立体模型。
参数详解：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 输入图片 | input_image | 图片文件 | PNG/JPG格式 | 就像给魔法师一张照片让它变成模型 | 输入的2D图像 | 上传一张清晰的、最好是白色背景的图片 |
| 种子值 | seed | 数字 | 随机或固定 | 控制3D转换的随机性 | 3D重建的随机种子 | 固定种子可以得到一致的转换结果 |
| 生成步数 | steps | 数字 | 50-100 | 控制3D转换的精细程度 | 3D重建的迭代步数 | 步数越多转换越精细 |
| 引导强度 | guidance_scale | 数字 | 100-300 | 控制转换时对原图的忠实度 | 图像引导的强度 | 数值越高越接近原图 |
3.4 MeshSaveNode - 模型保存节点
这个节点就像一个"文件管理员"，帮你把生成的3D模型保存到电脑里。
参数详解：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 文件名 | filename | 文本 | "my_3d_model" | 给你的3D模型起个名字 | 保存文件的名称 | 输入你想要的文件名，不用加后缀 |
| 文件格式 | format | 选择项 | "obj" | 选择3D模型的格式类型 | 3D文件的保存格式 | obj格式兼容性好，ply格式包含颜色信息 |
| 保存路径 | save_path | 路径 | 默认路径 | 选择模型保存到哪个文件夹 | 文件保存的目录路径 | 一般用默认路径，在ComfyUI/output/文件夹里 |
3.5 MeshViewerNode - 模型查看节点
这个节点就像一个"3D展示台"，让你能在ComfyUI里直接查看生成的3D模型。
参数详解：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 旋转角度 | rotation | 数字 | 0-360 | 控制模型的旋转角度 | 3D模型的旋转参数 | 可以从不同角度查看模型 |
| 缩放比例 | scale | 数字 | 0.5-2.0 | 控制模型显示的大小 | 3D模型的缩放比例 | 1.0是原始大小，0.5是缩小一半 |
| 视角位置 | camera_position | 坐标 | 默认值 | 控制观察模型的位置 | 相机在3D空间中的位置 | 一般用默认值即可 |
3.6 TextureMapNode - 纹理贴图节点
这个节点就像一个"化妆师"，给3D模型涂上漂亮的颜色和纹理。
参数详解：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 纹理分辨率 | texture_resolution | 数字 | 512-1024 | 控制纹理的清晰程度 | 纹理贴图的分辨率 | 512适合预览，1024适合最终输出 |
| 纹理格式 | texture_format | 选择项 | "png" | 选择纹理图片的格式 | 纹理文件的保存格式 | png支持透明，jpg文件更小 |
| 是否生成法线贴图 | generate_normal | 布尔值 | True | 是否生成让模型看起来更有立体感的特殊贴图 | 是否生成法线贴图 | 开启后模型细节更丰富 |
3.7 GifGeneratorNode - GIF生成节点
这个节点就像一个"动画师"，能把3D模型变成旋转的动画GIF。
参数详解：
| 参数名 (UI显示) | 参数名 (代码里) | 参数值 | 建议值 | 通俗解释 (能干嘛的) | 专业解释 | 怎么用/举个例子 |
|---|---|---|---|---|---|---|
| 帧数 | frames | 数字 | 24-60 | 控制GIF动画的流畅程度 | 动画的总帧数 | 24帧够用，60帧更流畅但文件更大 |
| 旋转速度 | rotation_speed | 数字 | 1-10 | 控制模型旋转的快慢 | 旋转的角度增量 | 1是慢速，5是中速，10是快速 |
| GIF尺寸 | gif_size | 数字 | 256-512 | 控制GIF的大小 | GIF图像的像素尺寸 | 256适合分享，512适合展示 |
| 帧率 | fps | 数字 | 12-30 | 控制GIF播放的速度 | 每秒播放的帧数 | 12是标准速度，30是流畅速度 |
4. 使用技巧和建议
4.1 文字提示词技巧
- 必须包含后缀：每个提示词都要加上"白色背景,3D风格,最佳质量"
- 描述要具体：比如"一只毛茸茸的橘色小猫坐着"比"猫"效果更好
- 避免复杂场景：单个物体比复杂场景更容易成功
4.2 图片处理技巧
- 背景透明：最好使用透明背景的PNG图片
- 主体清晰：确保要转换的物体清晰可见
- 避免遮挡：物体不要被其他东西遮挡
4.3 参数调节建议
- 新手设置：步数30，引导强度100，其他用默认
- 追求质量：步数100，引导强度200-300
- 快速测试：步数20，引导强度50
4.4 性能优化
- 固定种子：测试时固定种子可以节省时间
- 分步骤处理：先生成低质量预览，满意后再生成高质量
- 内存管理：如果内存不足，可以重启ComfyUI再试
5. 常见问题解答
Q1：安装后节点不显示怎么办？
A1： 检查是否正确安装了所有依赖，特别是PyTorch3D和Open3D。重启ComfyUI，确保权重文件下载完整。
Q2：生成时出现内存错误怎么办？
A2： 这是正常现象。有时ComfyUI会随机抛出torch.OutOfMemoryError错误，但多试几次通常能成功生成。可以固定种子来节省重复时间。
Q3：生成的3D模型质量不好怎么办？
A3： 尝试以下方法：
- 增加生成步数（50-100）
- 调高引导强度（100-300）
- 优化提示词描述
- 使用更清晰的输入图片
Q4：纹理贴图无法生成怎么办？
A4： 如果使用ComfyUI内置Python，纹理贴图和GIF输出功能可能不可用。建议使用conda环境安装。
Q5：工作流程加载失败怎么办？
A5： 确保下载了正确的模型文件，检查工作流程中的节点连接是否正确。
6. 工作流程示例
插件作者提供了三个示例工作流程：
6.1 文字转3D（原生）
使用ComfyUI自带的HunyuanDiT检查点，配合本插件生成3D模型。
6.2 文字转3D（标准）
使用插件自带的HunyuanDiT模型进行文字到3D的转换。
6.3 图片转3D
将2D图片转换为3D模型的完整流程。
7. 注意事项
- 环境要求：建议使用全新的ComfyUI安装
- 系统要求：Windows 10 + CUDA 12.4 + Python 3.12
- 存储空间：需要足够空间存储模型文件（约几GB）
- 显卡要求：需要支持CUDA的显卡
- 网络要求：首次使用需要下载模型文件
8. 相关资源
- 原始项目：Tencent/Hunyuan3D-1
- ComfyUI主项目：ComfyUI
- 相关3D插件：ComfyUI-3D-Pack
这个插件为ComfyUI带来了强大的3D生成能力，虽然安装过程稍显复杂，但一旦配置成功，就能轻松创建各种3D模型。记住多实验不同的参数设置，找到最适合你需求的配置！