tencent-hunyuan3d

Tencent Hunyuan3D

Hunyuan3D 是 Tencent 的生成式 3D 模型系列。其标志性特点是先生成形状、再生成纹理的两阶段流程：一个模型根据图像（或文本）生成无纹理几何体，第二个模型为几何体绘制材质。该系列涵盖可自托管的开放权重版本，以及只能通过托管 API 使用的闭源版本。在这两条路线中做出正确选择——并在发布任何商业产品前阅读许可证——是此技能旨在支持的核心生产决策。

**以下所有版本、许可证、硬件和访问方式信息均已于 2026-07-10 核实。**这些信息可能变动；依赖这些信息前，请再次查看一手代码库。信息标注为 [fact]（在主要来源中有文档记录）、[first-party claim]（Tencent 自身的基准测试或营销说法，未经过独立复现）或 [heuristic]（生产经验判断，不属于有文档记录的保证）。

---

此技能的适用场景

当请求涉及以下内容时使用：

• 根据图像或文本提示词生成 3D 物体/资产；
• 生成 3D 场景/世界（全景图、可探索环境）——HunyuanWorld / HY-World 分支；
• 决定自托管还是使用托管 API，或选择适合的 Hunyuan3D 版本；
• 许可证/合规问题（商业用途、Territory、MAU、署名）；
• 本地推理或 ComfyUI 设置的 GPU 配置；
• 检查或后期处理 Hunyuan3D 输出（拓扑、UV、PBR 贴图）。

不要将其用于 2D 图像生成（这是 HunyuanImage 的用途）、视频生成（HunyuanVideo）或 Hunyuan 文本大模型（Hunyuan/Hy3）——它们是不同的模型系列，只是都使用了「Hunyuan」品牌。

---

版本概览（已于 2026-07-10 核实）

分为两条路线。首先要选对路线，因为这会决定成本模式、控制能力和法律依据。

路线 A — 开放权重，可自托管（从 GitHub + Hugging Face 下载）

Model	Released	Params (shape / paint)	What it adds	License
Hunyuan3D-2.0	2025 年 1 月	DiT-v2-0 ~1.1B / Paint-v2-0 ~1.3B（+ Delight）	首个开放的两阶段物体模型	Tencent Hunyuan 3D 2.0 Community License
Hunyuan3D-2mini	2025 年 3 月 18 日	DiT-v2-mini 0.6B	低显存占用的形状生成（约 5 GB）	同 2.0 许可证
Hunyuan3D-2mv	2025 年 3 月 18 日	DiT-v2-mv ~1.1B	多视角形状输入（正面+背面+侧面）	同 2.0 许可证
-Turbo / -Fast + FlashVDM	2025 年 3 月 19 日	上述模型的蒸馏版本	步数/引导蒸馏；快速解码	同 2.0 许可证
Hunyuan3D-2.1	2025 年 6 月 13–14 日	DiT-v2-1 ~3.0B / Paint-v2-1 ~1.3–2B	首个完全开放的 PBR + 完整训练代码	Tencent Hunyuan 3D 2.1 Community License
HunyuanWorld-1.0	2025 年 7 月 26 日	—	开放的场景/世界生成：全景代理 → 分层网格 + 3DGS，360°	Tencent Hunyuan community license
HY-World 2.0 / WorldMirror 2.0	2026 年 4 月 16 日	—	文本/图像/多视角/视频 → 网格 + 3DGS + 点云；可编辑，可用于引擎	开源（GitHub + HF）

[fact] Hunyuan3D-2.1 是物体生成的开放参考基线。 当你需要 PBR，并希望权重和训练代码都采用开源许可证时，应选择此版本进行自托管。来源：GitHub Tencent-Hunyuan/Hunyuan3D-2.1、arXiv 2506.15442。

[fact] FlashVDM 可加速形状解码器：Tencent 报告称，Lightning Vectset Decoder 的速度提升超过 45 倍，并且 Progressive Flow Distillation 采样最快只需 5 步（速度提升幅度为 [first-party claim]）。通过 turbo 检查点 / --enable_flashvdm 启用。

Track B — 仅限封闭式托管 API（无可下载权重，已于 2026-07-10 核实）

模型	发布日期	特有能力	可用性
Hunyuan3D-2.5	2025 年 4 月	约 10B 参数，1024 几何分辨率，4K 纹理，凹凸贴图，“LATTICE” 形状模型，骨骼蒙皮	Tencent Cloud API + 第三方托管
Hunyuan3D-PolyGen	2025 年 7 月 8 日	艺术级拓扑——干净的四边形/三角形网格，自回归网格（BPT tokenization），智能重拓扑	API / Tencent 内部游戏管线
Hunyuan3D-3.0	2025 年 9 月	3D-DiT“分层雕刻”，约 1536³ 分辨率	Tencent Cloud API
Hunyuan3D-3.1	2025/2026 年稍晚	托管版 3.0 精修模型	Tencent Cloud + 托管平台（fal、Replicate 等）

[fact] 2.5 / PolyGen / 3.x 版本均为闭源：只能通过托管 API 使用，无法获取权重。Tencent Cloud International Station 和面向海外用户的 Hunyuan3D API 于 2025 年 11 月 26 日上线。如果任务要求“使用开放权重”，同时又要求“使用 3.0/PolyGen”，那就是自相矛盾——应当指出这一点。 来源：Tencent Cloud 文档 1284/75539；hunyuan3d.cc 版本说明；Tencent 新闻稿。

[heuristic] PolyGen 的存在，正是为了解决开放 2.x 网格的最大弱点：拓扑。 如果你遇到的瓶颈是自托管网格属于密集的三角形杂乱集合，那么答案是使用 PolyGen（托管版）或手动进行重拓扑，而不是换用另一个 2.x 检查点。

---

许可证——任何商业部署前都要阅读

这是该系列中对生产部署影响最大的事实。开放权重并非 MIT/Apache 许可证。它们采用 Tencent Hunyuan 3D Community License Agreement（按模型分别制定版本，例如 “TENCENT HUNYUAN 3D 2.1 COMMUNITY LICENSE AGREEMENT”）。[fact] 已于 2026-07-10 根据 Tencent-Hunyuan/Hunyuan3D-2 和 Hunyuan3D-2.1 中的 LICENSE 文件核实。

以下三项限制常常让人措手不及：

1. 地域排除 [fact]。 许可证授权范围为全球，但不包括欧盟、英国和韩国。禁止在“地域”之外使用。位于柏林、伦敦或首尔的团队无权依据此协议使用开放权重。这是明确的法律障碍，而非个人偏好——只要用户所在地或目标市场在这些地区，就应当指出。

2. 100 万 MAU 商业门槛 [fact]。 如果在模型发布日期前一个日历月内，被许可方提供或代表被许可方提供的产品/服务拥有超过 1,000,000 月活跃用户，被许可方必须向 Tencent 申请单独许可证（发送邮件至 [email protected]，并提供公司名称、行业和用例）。低于 100 万 MAU 时，可在地域范围内免费用于商业用途。

3. 禁止用途 [fact]。 约 20 项条款包括：不得用于改进竞争性 AI 模型；不得用于军事用途；不得生成伤害未成年人的内容；不得用于选举虚假信息；不得用于恶意软件；不得生成未披露的 AI 内容；不得用于“影响个人安全、权利或福祉的高风险自动化决策”。

署名 [fact]： 重新分发时必须附带 NOTICE 文件（“Tencent Hunyuan 3D 2.1 is licensed under the Tencent Hunyuan 3D 2.1 Community License Agreement, Copyright © 2025 Tencent.”），并且产品应标注“Powered by Tencent Hunyuan”。

[heuristic] 托管 API 并不会消除这些问题——它只是改变了适用的文件。 Tencent Cloud 和第三方托管平台（fal、Replicate 等）各自都有服务条款。不要想当然地认为“托管 = 商业用途不受限制”；应查看具体托管方的服务条款。如果用户位于欧盟/英国/韩国，使用托管 API 通常比自托管其无权在该地域使用的权重更稳妥——但仍需确认托管方允许这样做。涉及商业部署且事实不明确时，应建议用户自行咨询法律意见；不要声称已获得你无法提供来源证明的许可。

生成的实际工作原理（两阶段流水线）

[fact]（arXiv 2506.15442，Hunyuan3D-2.1）该流水线有意设计为模块化—— 你可以单独运行任一阶段。

阶段 1 — 形状（Hunyuan3D-DiT + ShapeVAE）：

• 输入：单张图像（已移除背景）、多视图图像（2mv），或文本 （文本会先送入文生图流程）。
• 基于流的扩散模型在 vectset 潜空间上生成有符号距离／占用场；移动立方体 算法提取出水密三角网格。
• octree_resolution 是控制几何密度／质量的主要参数。
• 输出：无纹理网格（GLB/OBJ、trimesh 对象）。

阶段 2 — 纹理／材质（Hunyuan3D-Paint）：

• 输入：阶段 1 生成的网格（Hunyuan3D 自己生成的，或你导入的自有网格）。
• 以网格为条件的多视图扩散模型从多个视角渲染对象（训练时使用 512×512 视图）， 并生成视图一致的材质贴图，然后将其烘焙到 UV 纹理中。
• [fact] 2.1 在 Disney Principled BRDF 下生成 PBR 贴图：反照率 （不含光照，通过光照不变训练策略实现）、金属度和粗糙度。它使用 具备 3D 感知能力的 RoPE 来保证跨视图一致性。2.0 的 Paint 输出更接近烘焙后的漫反射颜色；2.1 是首个开源 PBR 版本。

[heuristic] 由于阶段 2 接受任意网格，一种高效工作流是：只用 Hunyuan3D 为现有 （手工建模或重新拓扑）网格生成纹理，或者只用它生成形状，并在其他地方生成纹理。将这两个阶段视为独立工具。

输入策略：图像比文本更易控制

[heuristic] 文本转 3D 内部会先执行文本→图像→3D，因此你会失去对图像生成步骤的控制。只要几何形状很重要，就提供自己的参考图像。优质形状输入应符合以下条件：

• 主体单一且清晰分离，完整对象位于画面内，不被裁切；
• 背景简单／可移除（流水线会移除背景；复杂背景会降低效果）；
• 正面朝向、近似正交的构图，光线均匀，尽量减少生硬阴影（阴影可能会被烘焙进几何形状）；
• 对于背面或侧面也很重要的对象，请使用包含多个视图的 2mv——单张正面图会迫使模型对不可见面进行幻觉补全，且模型往往无法正确处理凹面、背面细节和细长结构。

---

自托管：硬件与设置（已于 2026-07-10 验证）

[fact] 显存占用（来自模型 README——请注意，两个开源版本给出的数字略有差异，因此请按较大的数值规划）：

任务	Hunyuan3D-2.0 版本	Hunyuan3D-2.1 版本
仅形状	~6 GB（2mini ~5 GB）	~10 GB
仅纹理	—	~21 GB
形状 + 纹理	~12–16 GB	~29 GB

[heuristic] 实际来看：24 GB 显卡（RTX 3090/4090）可以运行 2.1 的形状和纹理生成，前提是在阶段之间卸载模型，而不是让两个阶段同时驻留显存；同时运行两个阶段需要约 29 GB 显存，也就是需要 32–48 GB 显卡，或按顺序执行并卸载模型。对于 8 GB 消费级显卡，2mini 是仅生成形状的选择。蒸馏版 Turbo + FlashVDM 路径适合快速迭代，而非追求最高保真度。

[fact] 2.1 的参考环境：Python 3.10、PyTorch 2.5.1 + CUDA 12.4。安装过程会编译自定义光栅化器和可微渲染器／网格绘制器（C++/CUDA 扩展）——请为构建步骤和匹配的 CUDA 工具链预留时间。纹理升采使用的 Real-ESRGAN 权重需单独下载。仓库中提供 Gradio 应用（gradio_app.py）和 REST 端点（/generate，输入 base64 图像 → 输出 GLB）。来源：Hunyuan3D-2.1 README。

ComfyUI

[fact]（docs.comfy.org，已于 2026-07-10 验证）ComfyUI 仅原生支持形状／几何体阶段——Hunyuan3D-2、2mv 和 2mv-turbo 的工作流会生成无纹理 GLB，并输出到 ComfyUI/output/mesh。**原生节点不支持纹理／材质生成。**要在 ComfyUI 中进行 PBR 贴图，请使用社区封装（例如 ComfyUI-Hunyuan3DWrapper）。如果只使用 ComfyUI，请单独规划纹理阶段。

---

托管访问途径（已于 2026-07-10 验证）

• 腾讯云“Hunyuan 3D APIs”（文档 1284/75539）——官方服务；国际站自 2025 年 11 月 26 日起上线。支持闭源的 2.5、PolyGen 和 3.x 版本。
• Hugging Face Space tencent/Hunyuan3D-2.1——开源模型的免费演示，适合快速检查能力，不适合生产级用量。
• 第三方托管服务——fal.ai、Replicate、3D AI Studio、Atlas Cloud 等通过各自的 API 和计费方式封装 Hunyuan3D。

[fact] 各托管服务中的版本／定价信息（仅供参考，因服务商而异）：“Rapid”版本约需 2–3 分钟完成，具有固定的中等多边形预算和约 1K 纹理；“Pro”版本会调用完整模型，多边形数量可配置（约 40K–1.5M），并支持最高 4K 的 PBR。观察到的单模型价格约为 $0.02–$0.38；某种积分方案中，Pro 收费 60 积分（+20 PBR，+20 多视图，最多 100），Rapid 收费 35 积分（+20 PBR，最多 55）。所有价格都可能变化——向用户报价时，请查询托管服务的实时定价，切勿使用这些数字。

---

网格输出特征与所需的后期处理

[fact] 开源 2.x 网格由扩散场上的行进立方体算法生成。这意味着网格是水密的，但也十分稠密、三角形分布均匀、没有四边形拓扑，也缺少艺术家拓扑（没有边线环）。UV 是为贴图自动生成的，并非为手动编辑而布局。

[heuristic] 对生产流程的影响——请规划以下处理步骤：

• **重拓扑。**原始网格不适合绑定／动画或平滑变形。动画前请进行重拓扑（手动操作、使用自动重拓扑工具，或通过 PolyGen 处理资产；PolyGen 正是为此构建的）。
• **减面。**对于实时应用（游戏／AR／网页）的预算，请将稠密网格减面至目标三角形／多边形数量；预计需要从高分辨率网格烘焙法线贴图以保留细节。
• 重新布局 UV，适用于需要人工绘制或编辑纹理的情况，而非只使用自动烘焙的 PBR 贴图集。
• 标准化比例／朝向／原点——生成的资产很少符合目标引擎的单位、上轴或枢轴约定。
• 验证 PBR 贴图——确认反照率、金属度和粗糙度通道均已导出且彼此正确分离（某些导出路径会将它们合并为漫反射贴图）。

---

检查生成的资产——质量检查清单

[heuristic] 接受资产前，请检查：

1. 从各个方向检查轮廓与比例（环绕观察）——仅有正面输入时，经常会生成正面看似合理、背面却变形的模型。
2. 未见表面的生成效果——凹陷、倒扣和细小特征（绑带、把手、头发）是常见缺陷区域；请确认它们确实存在且为实体。
3. 漂浮部分／断开的壳体／非流形伪影（由行进立方体算法造成）。
4. 几何体密度是否符合需求——密度是否远超用途所需（减面），或过于粗糙（提高 octree_resolution／使用 2.5/3.0）？
5. 拓扑——对于静态道具，现有拓扑可能可以接受；但若要制作动画，未经重拓扑则不可接受。
6. PBR 正确性——反照率应不受光照影响（不应烘焙高光或投射阴影）；金属度／粗糙度应符合物理特性（金属与电介质）。
7. 检查 UV 边界处的纹理接缝与拉伸；根据版本和相机距离确认分辨率是否足够（1K 或 4K）。
8. 确保比例／朝向已标准化为目标引擎所需的设置。

---

生产决策：开放权重自托管还是商业托管

[heuristic] 在以下情况下，自托管开放的 2.x 模型更合适：

• 生成量很大——与按次收费的 API 费用相比，每个资产的边际成本趋近于零；
• 数据不能离开你的环境（尚未发布的 IP、私人客户资产）；
• 需要不产生单资产费用的 PBR，以及完整的管线确定性与集成能力；
• 想要训练代码（2.1 提供了训练代码），以便针对特定领域微调；
• 并且——这是硬性条件——你位于适用地区内（不包括 EU/UK/KR），且月活跃用户少于 100 万，或者持有 Tencent 的商业许可证。

[heuristic] 在以下情况下，托管 API 更合适：

• 需要最高保真度或分辨率（2.5、3.0），或开放权重不具备的干净拓扑（PolyGen）；
• 没有合适的 GPU，或者不想维护 CUDA/构建工具链；
• 使用量较低或波动较大（按使用量付费比闲置 GPU 更划算）；
• 位于EU/UK/KR，且开放权重的自托管未获得适用地区许可（使用允许你这样使用的托管服务，并仍需查看其 ToS）。

[first-party claim] 根据 Tencent 自己的基准测试，Hunyuan3D-DiT（2.1）在形状指标上略胜于可比的开放模型（Uni3D-T 为 0.2556，TripoSG 为 0.2506，Step1X-3D 为 0.2554），而 2.1 的 Paint 将纹理 CLIP-FID 从 2.0 的 26.44 提升至 24.78。这些数据由厂商报告；对“最佳”之类的说法应持怀疑态度。若要真正做出选择，请用你自己的资产测试各个候选模型，而不要盲目相信排行榜。

---

完整示例（标注示例，并非必须遵循的公式）

目标： 一家位于 EU/UK/KR 以外的工作室需要为一款手机游戏制作约 500 个风格化道具网格，带纹理，使用内部管线，不产生单资产云服务费用，预算可购买一张 24 GB GPU。

决策与理由：

• 方案： 自托管——生成量大且 GPU 成本固定，因此边际成本约为 0；500 个资产会产生持续的 API 账单。
• 许可证： 工作室位于适用地区内，月活跃用户远低于 100 万 → 可免费商用；添加 NOTICE 文件和“Powered by Tencent Hunyuan”标记。[fact]
• 模型： Hunyuan3D-2.1——游戏光照需要 PBR，并且希望使用开放权重和代码。在 24 GB 显卡上，使用卸载方式依次运行形状生成和纹理生成（合并运行大约需要 29 GB）。[fact]/[heuristic]
• 输入： 为每个道具提供一张正面参考图（概念图），并移除背景；对于背面细节重要的道具，拍摄两个视角并使用 2mv。[heuristic]
• 使用 Turbo/FlashVDM 检查点迭代，以较低成本确定轮廓和取景，然后再运行完整模型生成最终结果。[heuristic]
• 对每个资产进行后期处理： 将网格简化至手机平台的多边形预算；从高密度网格烘焙法线；对会变形或需要动画的道具进行重新拓扑（或将少数这类道具交给托管版 PolyGen 处理）；验证反照率／金属度／粗糙度贴图组；将比例和上轴统一为引擎所需的设置。[heuristic]

预期结果： 道具网格可形成水密模型，带有 PBR 纹理，面数受控，不产生单资产费用，许可证合规。

可能的失败情况： 单视图道具的背面被幻觉生成（可通过 2mv 缓解）；少数需要动画的道具，其高密度三角形拓扑不可用（重新拓扑／使用 PolyGen）；如果参考图光照过强，反照率中会烘入阴影（使用平坦、均匀光照的参考图）。

变体： 同一家工作室若位于德国，则完全不能依据 Community License 使用开放权重——必须改用其 ToS 允许此类用途的托管 API，这会改变成本核算和整个方案。[fact]

常见失败模式（摘要）

• 背面／侧面几何形状错误，原因是输入为单视图 → 使用 2mv 或多个视图。
• 拓扑结构不适用于动画 → 重新拓扑或使用 PolyGen；开放网格按设计就是 marching-cubes 三角形面片集合。[fact]
• 运行形状和纹理生成时 VRAM OOM → 使用卸载功能按顺序运行各阶段，或将形状生成降至 2mini。[heuristic]
• “albedo” 中烘焙了阴影／高光 → 输入参考图采用了定向光照；重新拍摄平光图。[heuristic]
• 认为开源 = 不受限制 → 适用的是 Community License：有地域限制（不包括 EU／UK／KR）、1M MAU 门槛、禁止用途条款和署名要求。[fact]
• 认为 ComfyUI 会生成纹理 → 原生 ComfyUI 仅支持几何体；纹理需要社区封装。[fact]
• 混淆不同系列 → 2.5／PolyGen／3.x 仅提供 API；无法下载其权重。[fact]

---

主要来源（均已于 2026-07-10 核实）

• GitHub Tencent-Hunyuan/Hunyuan3D-2 — 2.0 模型库、变体、FlashVDM、VRAM。
• GitHub Tencent-Hunyuan/Hunyuan3D-2.1 — 2.1 权重和训练代码、设置、VRAM。
• 两个代码库中的 LICENSE 文件 — Tencent Hunyuan 3D 2.0／2.1 Community License（地域、1M MAU、禁止用途、署名要求）。
• arXiv 2506.15442 — Hunyuan3D 2.1 技术报告（两阶段架构、PBR／Disney BRDF、基准测试数据）。
• arXiv 2506.16504 — Hunyuan3D 2.5 技术报告。
• GitHub Tencent-Hunyuan/HunyuanWorld-1.0 和 Tencent-Hunyuan/HY-World-2.0； arXiv 2507.21809 — 世界／场景模型。
• docs.comfy.org Hunyuan3D-2 教程 — ComfyUI 原生仅支持几何体。
• Tencent Cloud“Hunyuan 3D APIs”（文档 1284/75539）和 Tencent 新闻稿 — 托管 API、国际站发布（2025 年 11 月 26 日）。
• hunyuan3d.cc 版本说明；Tencent Hunyuan 公告 — PolyGen（2025 年 7 月 8 日）、 2.5、3.0/3.1 时间线及闭源状态。