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-2Hunyuan3D-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.pyapi.md 与 README 给出的标准启动命令为python api_server.py --host 0.0.0.0 --port 8080若需要网格贴图能力即 Addon 面板中的Generate Texture必须追加--enable_tex。从 api_server.py#L300-L315 可以看到全部命令行参数及默认值参数默认值说明--host0.0.0.0监听地址--port8081监听端口README 示例显式指定8080与 Addon 默认一致见“常见注意事项”--model_pathtencent/Hunyuan3D-2mini形状生成 DiT 模型--tex_model_pathtencent/Hunyuan3D-2贴图模型Paint--devicecuda推理设备--limit-model-concurrency5并发信号量--enable_tex关闭加载Hunyuan3DPaintPipeline以启用贴图ModelWorker.__init__api_server.py#L146-L171中会实例化BackgroundRemoverrembg 抠图与Hunyuan3DDiTFlowMatchingPipeline形状生成且开启enable_flashvdm仅当enable_texTrue时才额外加载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 Generatorblender_addon.py#L15-L23。面板参数Addon 在 3D 视图侧边栏快捷键 N的Hunyuan3D-2分类下提供Hunyuan3D-2 3D Generator面板blender_addon.py#L299-L329。面板属性定义在Hunyuan3DPropertiesblender_addon.py#L34-L90完整参数表如下面板字段类型默认值取值范围说明api_url字符串http://localhost:8080—API 服务地址prompt字符串空—文本提示词与image_path至少填一项image_path文件路径空—参考图图生 3D / 贴图参考octree_resolution整数256128–512八叉树分辨率决定网格几何精度num_inference_steps整数2020–50形状生成推理步数guidance_scale浮点5.51.0–10.0引导强度texture布尔False—是否生成/应用贴图四种生成模式Hunyuan3DOperator.invoke会先读取选中对象context.selected_objects中的MESH再按参数组合分派到四条请求分支blender_addon.py#L181-L253。四种组合如下文生 3DText to 3D只填prompt不选图、不选网格。Addon 发送{text: ...}及生成参数服务侧做形状生成textureFalse时得到白模textureTrue时服务侧先做形状再生成贴图此时参考图由服务内部的 text2image 链路承担见下文。图生 3DImage to 3D选择image_path并勾选或不勾选texture。Addon 将图片读为二进制并 Base64 编码后发送{image: ...}。图片不存在时直接报Image path does not exist错误并终止blender_addon.py#L222-L224。网格贴图Mesh Texturing在视口中选中一个 Mesh 对象并勾选textureAddon 通过临时文件 bpy.ops.export_scene.gltf(use_selectionTrue)将其导出为 GLB 并 Base64 编码以{mesh: ...}字段提交blender_addon.py#L145-L153。服务侧跳过形状生成直接对已有网格贴图。网格贴图 参考图在模式 3 基础上再提供image_path请求同时携带mesh与image面板日志显示Post Texturing with Image未提供图片则显示Post Texturing with Text仅以text作为贴图语义条件。注意textureTrue要求服务端以--enable_tex启动否则ModelWorker中没有pipeline_tex贴图分支不可用。源码级协作机制请求构造与后台线程invoke中启动threading.Thread(targetself.generate_model, ...)后进入RUNNING_MODALblender_addon.py#L174-L179使耗时的 HTTP 等待不阻塞 Blender UImodal循环中按右键或 ESC 可取消 UI 等待态注意这只结束客户端等待服务端的生成任务不会因此中断。处理期间props.is_processingTrue面板按钮禁用并逐行显示status_message完成后恢复。所有请求统一POST {api_url}/generateJSON 体最多包含以下字段text、imageBase64 图片、meshBase64 GLB、octree_resolution、num_inference_steps、guidance_scale、texture。其中api_url会先做rstrip(/)处理避免拼接出双斜杠。图片路径支持 Blender 的//相对路径写法若image_path以//开头Addon 会剥掉前缀并相对于当前 .blend 文件所在目录解析blender_addon.py#L157-L163便于在素材库中组织工程。服务端处理链ModelWorker.generateapi_server.py#L186-L229的处理顺序若带image字段先 Base64 解码为 PIL 图像若带text走 text2image 得到参考图二者皆无则抛ValueError。对图像执行self.rembg(image)自动抠除背景。形状分支仅当请求中没有mesh时执行。此时取seed默认 1234构造随机数生成器参数缺省值为octree_resolution128、num_inference_steps5、guidance_scale5.0、mc_algomc然后调用形状管线self.pipeline(**params)得到trimesh网格。由于 Addon 面板会显式发送这三个参数实际生效值以面板为准面板默认256 / 20 / 5.5。贴图分支若texture为真依次执行FloaterRemover去浮点噪声、DegenerateFaceRemover去退化面、FaceReducer(max_facenum40000)面数压缩最后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_renderTrue隐藏视觉上相当于原位替换临时文件在导入完成后删除is_processing复位。补充异步提交接口除 Addon 使用的/generate同步等待完整文件外服务还提供一对异步接口POST /send立即返回任务uidGET /status/{uid}轮询状态完成后返回model_base64api_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_resolution256、num_inference_steps20、guidance_scale5.5均会显式发送服务端仅在字段缺失时回退到128 / 5 / 5.0。参数合法性由 UI 约束面板对octree_resolution128–512、num_inference_steps20–50、guidance_scale1.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），仅供参考