Hunyuan3D-2 Blender Addon 集成指南：在 Blender 中完成文/图生 3D 与网格贴图
【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2
Hunyuan3D-2 仓库官方文档中的 Blender Addon 指南 描述了如何在启动本地 API 服务后，通过随仓库提供的 blender_addon.py 在 Blender 内直接调用 Hunyuan3D 2.0 进行 3D 生成与贴图。读完本文，你将掌握完整链路：API 服务的启动与参数、Addon 的安装与面板配置、四种生成模式（文生 3D、图生 3D、网格贴图、带参考图贴图）的触发条件，以及 Addon 与 api_server.py 之间请求/响应的源码级协作机制。
整体工作流
Add-on 本身不包含模型，而是一个“客户端”：它运行在 Blender 进程内，通过 HTTP 请求把任务转发给独立运行的模型推理服务（api_server.py 中的 FastAPI 应用），服务完成生成后返回 GLB 文件，Addon 再将其导入当前场景。
Blender (blender_addon.py) API 服务 (api_server.py) ┌──────────────────────────┐ POST /generate ┌──────────────────────────────┐ │ 面板：prompt / image / │ ───────────────▶ │ ModelWorker.generate() │ │ octree_resolution 等参数 │ │ ├ rembg 抠图 │ │ 后台线程发起 HTTP 请求 │ ◀─────────────── │ ├ 可选：形状生成 (DiT) │ │ 收到 GLB 后导入场景 │ FileResponse │ └ 可选：贴图 (HunyuanPaint) │ └──────────────────────────┘ (GLB 字节流) └──────────────────────────────┘这一设计与 README 中 API Server 一节的说明一致：先本地启动 API server，再以 Web 请求方式提交 Image/Text to 3D、Mesh 贴图任务。
准备环境：启动 API 服务
安装依赖
按照 README 的Install Requirements一节，先按 PyTorch 官方指引安装对应平台的 PyTorch，再安装仓库其余依赖：
pip install -r requirements.txt pip install -e . # 若需要贴图（texture）功能，需额外编译两个 C++/CUDA 扩展： cd hy3dgen/texgen/custom_rasterizer python3 setup.py install cd ../../.. cd hy3dgen/texgen/differentiable_renderer python3 setup.py install其中 requirements.txt 包含fastapi、uvicorn、trimesh、rembg、diffusers等 API 服务运行所需的库；后两个 setup.py 分别安装custom_rasterizer与differentiable_renderer，是贴图管线Hunyuan3DPaintPipeline的底层光栅化依赖。
启动 api_server.py
api.md 与 README 给出的标准启动命令为：
python api_server.py --host 0.0.0.0 --port 8080若需要网格贴图能力（即 Addon 面板中的Generate Texture），必须追加--enable_tex。从 api_server.py#L300-L315 可以看到全部命令行参数及默认值：
| 参数 | 默认值 | 说明 |
|---|---|---|
--host | 0.0.0.0 | 监听地址 |
--port | 8081 | 监听端口（README 示例显式指定8080，与 Addon 默认一致，见“常见注意事项”） |
--model_path | tencent/Hunyuan3D-2mini | 形状生成 DiT 模型 |
--tex_model_path | tencent/Hunyuan3D-2 | 贴图模型（Paint） |
--device | cuda | 推理设备 |
--limit-model-concurrency | 5 | 并发信号量 |
--enable_tex | 关闭 | 加载Hunyuan3DPaintPipeline以启用贴图 |
ModelWorker.__init__（api_server.py#L146-L171）中会实例化BackgroundRemover（rembg 抠图）与Hunyuan3DDiTFlowMatchingPipeline（形状生成，且开启enable_flashvdm）；仅当enable_tex=True时才额外加载Hunyuan3DPaintPipeline。
显存方面，README 说明形状生成约需 6 GB VRAM，形状加贴图全流程合计约 16 GB，规划硬件时以此为前提。
安装与使用 Blender Addon
安装 Addon
仓库根目录的 blender_addon.py 即完整插件（bl_info声明blender: (3, 0, 0)，即要求 Blender 3.0 及以上）。安装方式为 Blender 标准流程：Edit → Preferences → Add-ons → Install…，选择blender_addon.py并勾选启用。其bl_info中声明的入口位置为View3D > Sidebar > Hunyuan3D-2 3D Generator（blender_addon.py#L15-L23）。
面板参数
Addon 在 3D 视图侧边栏（快捷键 N）的Hunyuan3D-2分类下提供Hunyuan3D-2 3D Generator面板（blender_addon.py#L299-L329）。面板属性定义在Hunyuan3DProperties（blender_addon.py#L34-L90），完整参数表如下：
| 面板字段 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|
api_url | 字符串 | http://localhost:8080 | — | API 服务地址 |
prompt | 字符串 | 空 | — | 文本提示词；与image_path至少填一项 |
image_path | 文件路径 | 空 | — | 参考图（图生 3D / 贴图参考） |
octree_resolution | 整数 | 256 | 128–512 | 八叉树分辨率，决定网格几何精度 |
num_inference_steps | 整数 | 20 | 20–50 | 形状生成推理步数 |
guidance_scale | 浮点 | 5.5 | 1.0–10.0 | 引导强度 |
texture | 布尔 | False | — | 是否生成/应用贴图 |
四种生成模式
Hunyuan3DOperator.invoke会先读取选中对象（context.selected_objects中的MESH），再按参数组合分派到四条请求分支（blender_addon.py#L181-L253）。四种组合如下：
- 文生 3D（Text to 3D）：只填
prompt，不选图、不选网格。Addon 发送{"text": ...}及生成参数，服务侧做形状生成；texture=False时得到白模，texture=True时服务侧先做形状再生成贴图（此时参考图由服务内部的 text2image 链路承担，见下文）。 - 图生 3D（Image to 3D）：选择
image_path并勾选或不勾选texture。Addon 将图片读为二进制并 Base64 编码后发送{"image": ...}。图片不存在时直接报Image path does not exist错误并终止（blender_addon.py#L222-L224）。 - 网格贴图（Mesh Texturing）：在视口中选中一个 Mesh 对象并勾选
texture，Addon 通过临时文件 +bpy.ops.export_scene.gltf(use_selection=True)将其导出为 GLB 并 Base64 编码，以{"mesh": ...}字段提交（blender_addon.py#L145-L153）。服务侧跳过形状生成，直接对已有网格贴图。 - 网格贴图 + 参考图：在模式 3 基础上再提供
image_path，请求同时携带mesh与image，面板日志显示Post Texturing with Image；未提供图片则显示Post Texturing with Text，仅以text作为贴图语义条件。
注意：texture=True要求服务端以--enable_tex启动，否则ModelWorker中没有pipeline_tex，贴图分支不可用。
源码级协作机制
请求构造与后台线程
invoke中启动threading.Thread(target=self.generate_model, ...)后进入RUNNING_MODAL（blender_addon.py#L174-L179），使耗时的 HTTP 等待不阻塞 Blender UI；modal循环中按右键或 ESC 可取消 UI 等待态（注意这只结束客户端等待，服务端的生成任务不会因此中断）。处理期间props.is_processing=True，面板按钮禁用并逐行显示status_message，完成后恢复。
所有请求统一POST {api_url}/generate，JSON 体最多包含以下字段：text、image（Base64 图片）、mesh（Base64 GLB）、octree_resolution、num_inference_steps、guidance_scale、texture。其中api_url会先做rstrip('/')处理，避免拼接出双斜杠。
图片路径支持 Blender 的//相对路径写法：若image_path以//开头，Addon 会剥掉前缀并相对于当前 .blend 文件所在目录解析（blender_addon.py#L157-L163），便于在素材库中组织工程。
服务端处理链
ModelWorker.generate（api_server.py#L186-L229）的处理顺序：
- 若带
image字段，先 Base64 解码为 PIL 图像；若带text，走 text2image 得到参考图；二者皆无则抛ValueError。 - 对图像执行
self.rembg(image)自动抠除背景。 - 形状分支：仅当请求中没有
mesh时执行。此时取seed（默认 1234）构造随机数生成器，参数缺省值为octree_resolution=128、num_inference_steps=5、guidance_scale=5.0、mc_algo='mc'，然后调用形状管线self.pipeline(**params)得到trimesh网格。由于 Addon 面板会显式发送这三个参数，实际生效值以面板为准（面板默认256 / 20 / 5.5）。 - 贴图分支：若
texture为真，依次执行FloaterRemover（去浮点噪声）、DegenerateFaceRemover（去退化面）、FaceReducer(max_facenum=40000)（面数压缩），最后self.pipeline_tex(mesh, image)输出带贴图的网格。 - 结果经临时文件规范化后导出为 GLB，存入
gradio_cache/{uid}.glb，并调用torch.cuda.empty_cache()释放显存。
/generate端点（api_server.py#L244-L274）捕获到ValueError、CUDA 错误或未知异常时统一返回 404 与错误文案；成功时以FileResponse直接返回 GLB 文件字节流。
GLB 回传与场景导入
Addon 收到 200 响应后把字节写入临时.glb文件，再通过bpy.app.timers.register将bpy.ops.import_scene.gltf调度回主线程执行（bpy 操作必须在主线程，blender_addon.py#L263-L287）：
- 导入后自动选中新对象；
- 若本次是“选中网格贴图”流程，新网格会继承原网格的
location、rotation_euler、scale，并把原网格hide_set(True)且hide_render=True隐藏，视觉上相当于原位替换； - 临时文件在导入完成后删除，
is_processing复位。
补充：异步提交接口
除 Addon 使用的/generate（同步等待完整文件）外，服务还提供一对异步接口：POST /send立即返回任务uid，GET /status/{uid}轮询状态，完成后返回model_base64（api_server.py#L277-L297）。从 Addon 源码看它只使用了同步接口；如果你在集成自己的工具链，这对接口可作为不阻塞连接的替代方案。
常见注意事项
- 端口要对齐：Addon 的
api_url默认是http://localhost:8080，而api_server.py的--port代码默认值是8081。README 与 api.md 的示例都显式传了--port 8080；若你启动时未指定端口，需手动把面板api_url改为http://localhost:8081。 - 贴图功能前置条件：勾选
texture前，确认服务端带了--enable_tex，且已编译custom_rasterizer与differentiable_renderer两个扩展（见上文安装步骤）。 - 面板与服务端默认值不同：面板默认
octree_resolution=256、num_inference_steps=20、guidance_scale=5.5，均会显式发送；服务端仅在字段缺失时回退到128 / 5 / 5.0。 - 参数合法性由 UI 约束：面板对
octree_resolution（128–512）、num_inference_steps（20–50）、guidance_scale（1.0–10.0）设置了 min/max；直接构造 HTTP 请求时则不受这些范围约束，需自行保证合理取值。 - 客户端依赖：Addon 使用
requests库发起 HTTP 请求（blender_addon.py#L30），请确保 Blender 运行环境可用（通常随 Python 分发，缺失时可用 Blender 内置 pip 安装）。 - 模型路径：
--model_path/--tex_model_path缺省指向 Hugging Face 上的tencent/Hunyuan3D-2mini与tencent/Hunyuan3D-2，首次运行会拉取权重；也可指向本地已下载目录。
小结
Hunyuan3D-2 的 Blender 集成采用“Blender 插件 + 独立推理服务”的解耦架构：插件负责参数收集、网格导出与结果导入，api_server.py 负责抠图、形状生成与贴图的完整管线。掌握POST /generate的请求字段与四条分支逻辑后，既可以照面板操作，也可以脱离 Blender 直接用curl（参考 api.md 的示例）或自研工具调用同一接口。相关入口：docs/source/started/blender.md、blender_addon.py、api_server.py、examples 目录（更多形状/贴图用法示例）。
【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
