图片转3D模型完整教程Hunyuan3D-2 本地部署与首次生成上手【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2手里有一张角色插画想把它变成能直接丢进游戏场景的带纹理 3D 模型Hunyuan3D-2 做的就是这件事输入一张图片或一段文字描述它输出一个可编辑的 glb 模型。本文带你在一台带 NVIDIA 显卡的电脑上完成 Hunyuan3D-2 本地部署从克隆仓库到跑通第一次图片转 3D全程给出可复制的命令。环境门槛本地部署 Hunyuan3D-2 前的硬件与系统要求先核对你的机器是否达标避免装到一半才发现跑不动项目最低要求推荐配置不满足时的替代方案GPU 显存6 GB仅生成形状16 GB形状 纹理全流程显存不足时改用 Hunyuan3D-2mini 模型并关闭纹理生成操作系统macOS / Windows / Linux三端均官方支持无替代跨平台运行Python3.10.x3.10.9配合虚拟环境装依赖前先用python -m venv venv建环境磁盘空间10 GB 可用20 GB存放多组模型权重只保留 mini 系列权重可省一半空间⚠️ 注意显存数据来自仓库官方说明——6 GB VRAM for shape generation and 16 GB for shape and texture generation in total。8 GB 显存的卡建议全程带--low_vram_mode参数。从克隆仓库到编译完成的部署主线部署共四步拉代码 → 装依赖 → 编译两个 C 扩展。前两步装 Python 依赖后两步只在你需要纹理生成给模型上色时才必须执行。第一步克隆仓库并进入目录。执行后终端不会输出内容目录切换成功即可git clone https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2 cd Hunyuan3D-2第二步安装 PyTorch 与 Python 依赖。PyTorch 需按你的 CUDA 版本从 PyTorch 官网单独安装仓库未锁定版本其余依赖一条命令装完随后把项目本身以可编辑模式装入环境。预期看到一行行Successfully installed ...pip install -r requirements.txt pip install -e .第三步编译自定义光栅化器custom rasterizer负责把 3D 网格渲染成 2D 图供纹理模型参考。编译成功后终端无报错、扩展装进当前 Python 环境然后退回项目根目录cd hy3dgen/texgen/custom_rasterizer python3 setup.py install cd ../../..第四步编译可微分渲染器differentiable renderer纹理生成时对渲染结果求梯度用。命令结构与上一步一致cd hy3dgen/texgen/differentiable_renderer python3 setup.py install cd ../../.. 小贴士这两步依赖 C 编译工具链requirements 里已包含 ninja 和 pybind11。Windows 上需要 Visual Studio 2022 的 C 桌面开发组件Linux 上确保有 g。只用形状生成、不上色的话这两步可以跳过。三种使用入口网页界面、Blender 集成与 API 调用新手Gradio 网页界面最省事的入口。启动后浏览器自动打开 Gradio 页面左侧选输入模式右侧调参数并生成python3 gradio_app.py --model_path tencent/Hunyuan3D-2 --subfolder hunyuan3d-dit-v2-0 \ --texgen_model_path tencent/Hunyuan3D-2 --low_vram_mode界面默认带纹理生成只想看速度可加--disable_tex想再快就换 turbo 子文件夹--subfolder hunyuan3d-dit-v2-0-turbo --enable_flashvdm。首次启动会从 Hugging Face 自动下载模型权重模型名tencent/Hunyuan3D-2需要联网耐心等待进度条走完。进阶Blender 插件先启动一次 API 服务插件通过它通信python api_server.py --host 0.0.0.0 --port 8080然后在 Blender 中编辑 → 偏好设置 → 插件 → 安装选择项目根目录下的blender_addon.py启用后就能在 Blender 侧边栏面板里直接发起生成结果自动导入当前场景。开发者API 服务调用不想维护长连接或想批量跑任务时直接用 HTTP 接口。服务启动命令同上注意api_server.py的默认端口是 8081README 示例中用--port 8080显式指定。请求体把图片转成 base64 放进 JSONimg_b64_str$(base64 -i assets/demo.png)再发送 POST 请求返回的响应体就是 glb 文件本身curl -X POST http://localhost:8080/generate \ -H Content-Type: application/json \ -d {image: $img_b64_str} \ -o test2.glbJSON 里还可传texture: true开启纹理、octree_resolution、num_inference_steps、guidance_scale调整生成效果。如果你要写脚本而非调 HTTP代码 API 只有几行from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline pipeline Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(tencent/Hunyuan3D-2) mesh pipeline(imageassets/demo.png)[0]mesh是 trimesh 对象可直接mesh.export(out.glb)。效果与原理文字和图片转 3D 模型实测文字模式一段描述生成卡通角色启动 Gradio 时加--enable_t23d开启文本入口输入assets/example_prompts.txt里的提示词如 a lovely rabbit eating carrots即可得到带纹理的卡通角色图片模式一张照片转可渲染模型上传图片后点生成等待进度条结束即可导出 glb。用仓库自带的示例图assets/example_images/075.png生成的人物雕塑多视角模式同样支持把物体的前、左、后三张视图仓库assets/example_mv_images/下有 14 组示例一起上传几何还原更准。两阶段架构先形状后纹理Hunyuan3D-2 是两阶段流水线形状模型 Hunyuan3D-DiT基于 flow matching 的扩散 Transformer把条件图片对齐成网格几何纹理模型 Hunyuan3D-Paint 再为网格合成高分辨率贴图。形状与纹理解耦所以它既能给自动生成的网格上色也能为你手工做的网格生成纹理。参数调优按硬件选择参数组合下表组合均取自仓库真实参数耗时为本地参考值随机器波动硬件推荐参数组合预估耗时质量16 GB 显存以上tencent/Hunyuan3D-2--subfolder hunyuan3d-dit-v2-0 Octree Resolution 2565-10 分钟高8-12 GB 显存同上 --low_vram_mode5-10 分钟高略慢6 GB 显存--model_path tencent/Hunyuan3D-2mini--low_vram_mode3-6 分钟中追求速度--subfolder hunyuan3d-dit-v2-0-turbo --enable_flashvdm大幅缩短中三个关键参数Gradio 界面均有对应滑条Octree Resolution网格细节精度默认 256范围 16-512调高更精细但更吃显存。Steps推理步数默认 50越多越稳但越慢。Guidance Scale引导强度默认 7.5调高让结果更贴近输入图调低更有随机性。问题排错显存不足、编译失败等高频故障直答Q生成时报 CUDA out of memory按优先级依次尝试加--low_vram_mode启动 → 换成--model_path tencent/Hunyuan3D-2mini→ 去掉纹理Gradio 加--disable_texAPI 请求不传texture。Q编译两个 C 扩展时报cl.exe not foundWindows 上以管理员身份运行 x64 Native Tools Command Prompt for VS 2022在其中重新执行python3 setup.py install确认 VS 2022 装了 C 桌面开发组件。Linux 上则是缺 g装上再试。Q生成太慢想快速出图启动参数换成--subfolder hunyuan3d-dit-v2-0-turbo --enable_flashvdm这是官方蒸馏出的 Turbo 权重 FlashVDM 加速。Q纹理发糊、几何细节不够界面里把 Steps 调到 50 以上、Guidance Scale 提高到 7.5-10、Octree Resolution 保持 256 起步API 中对应guidance_scale与octree_resolution字段默认分别为 5.0 和 128偏低。QAPI 请求返回 404 或 JSON 错误确认服务真的在跑的端口上——api_server.py默认端口 8081而示例请求发到 8080两边要一致另外image字段必须是 base64 字符串缺图或格式错误会返回error_code: 1。延伸阅读官方文档、示例代码与模型来源入门文档docs/source/started/代码、Gradio、API、Blender、ComfyUI 各有一篇官方文档首页docs/source/index.md进阶示例多视角转 3D、给手工网格上色等examples/端到端最小脚本形状 纹理完整流程minimal_demo.py文本模式示例提示词assets/example_prompts.txt模型权重来源与规格docs/source/modelzoo.md技术报告 PDFassets/report/Tencent_Hunyuan3D_2_0.pdf结语到这里你的机器上已经有一套能出活的本地图片转 3D 工具。下一步建议随便找一张边缘干净的单物体图手办、玩偶、道具都合适丢进 Gradio 的图片模式用默认参数跑一次并导出 glb。拿到模型后拖进 Blender 或任何 3D 查看器里转一圈再决定是否需要调 Octree Resolution 或换 Turbo 子文件夹提速——多跑两次参数的手感就来了。【免费下载链接】Hunyuan3D-2High-Resolution 3D Assets Generation with Large Scale Hunyuan3D Diffusion Models.项目地址: https://gitcode.com/GitHub_Trending/hu/Hunyuan3D-2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考