图片生成三维模型本地搭建以及接入tvt.js

在线预览地址：
opensource.icegl.cn/#/plugins/hunyuan3D/index

本教程主要通过腾讯的开源混元3D图生模型【hunyuan3D】，本地部署后，以api的方式，将图片生产成glb三维模型，载入tvt.js生态， 并提供下载，只使用本地算力，而不使用云api。

Hunyuan3D-2代码 github地址：
https://github.com/Tencent-Hunyuan/Hunyuan3D-2

Hunyuan3D-2模型 huggingface地址：
https://huggingface.co/tencent/Hunyuan3D-2mini

代码详情查看：
https://gitee.com/ice-gl/icegl-three-vue-tres/blob/master/src/plugins/hunyuan3D/pages/index.vue

关于本地混元服务的启动

下载Hunyuan3D-2源码

根据上面的github地址 ：https://github.com/Tencent-Hunyuan/Hunyuan3D-2
下载源码。
解压或者git后，cd到项目目录

安装依赖

这里我做了简化，因为本人用的是mac mini m4，所以没法使用cuda，生产材质，所以本教程，只针对图片生成三维白膜，材质通过程序更改。

# cd Hunyuan3D-2-main

pip install -r requirements.txt
pip install -e .

下载混元模型

这一步如果你有翻墙的条件，并且翻墙的下载速度足够，可以跳过，因为程序默认会自动下载混元模型
不过还是建议自行通过huggingface下载 想用的模型，更好的维护。

# 进入：
https://huggingface.co/tencent/Hunyuan3D-2mini/tree/main

# 页面，选择 目录 hunyuan3d-dit-v2-min
# 下载三个文件
config.yaml
model.fp16.ckpt
model.fp16.safetensors

# 自己新建目录如下
models-tencent-Hunyuan3D/hunyuan3d-dit-v2-min
把三个文件都放在该目录下，并记住这个地址

修改和启动api程序

修改项目根目录的 api_server.py 文件

// 修改最后的 314行，调用的ModelWorker参数，就是增加模型子目录subfolder指向 你自己得地址
  worker = ModelWorker(model_path=args.model_path, device=args.device, enable_tex=args.enable_tex,
                         tex_model_path=args.tex_model_path, subfolder='hunyuan3d-dit-v2-mini')
                         
// 主要增加的就是：*, subfolder='hunyuan3d-dit-v2-mini' * 
hunyuan3d-dit-v2-mini 这个子目录就是你之前创建的

然后 回到cd到项目目录的终端，输入命令启动

python3 ./api_server.py --port 8081 --model_path /Volumes/L-SSD/AI/to3D/models-tencent-Hunyuan3D --device mps

# port 为端口号，它默认是8081，你可以随意设置
# model_path 为你自己存放下载的模型的目录
# device 你本机设备的类型，因为我是mac 所以是*mps*，如果你是win，又是cuda的英伟达显卡，那么设置成*cuda* ，它默认的就是*cuda*

# 当然这些命令可以不带参数 直接为：
python3 ./api_server.py
# 那么模型会下载到系统缓存，端口是8081，默认机器是cuda英伟达显卡

至此，你可以看到如下画面，证明已经启动了这个api接口，供你调用了，后面我们讲用它在tvt的生态案例中，或者tvt的区域编辑器中直接调用它

hawk@Mac-mini Hunyuan3D-2-main % python3 ./api_server.py --port 8081 --model_path /Volumes/L-SSD/AI/to3D/models-tencent-Hunyuan3D --device mps
2025-07-30 10:41:12 | INFO | controller | args: Namespace(host='0.0.0.0', port=8081, model_path='/Volumes/L-SSD/AI/to3D/models-tencent-Hunyuan3D', tex_model_path='tencent/Hunyuan3D-2', device='mps', limit_model_concurrency=5, enable_tex=False)
2025-07-30 10:41:12 | INFO | controller | Loading the model /Volumes/L-SSD/AI/to3D/models-tencent-Hunyuan3D on worker d4ad9d ...
2025-07-30 10:41:13,057 - hy3dgen.shapgen - INFO - Try to load model from local path: /Volumes/L-SSD/AI/to3D/models-tencent-Hunyuan3D/hunyuan3d-dit-v2-mini
2025-07-30 10:41:13 | INFO | hy3dgen.shapgen | Try to load model from local path: /Volumes/L-SSD/AI/to3D/models-tencent-Hunyuan3D/hunyuan3d-dit-v2-mini
2025-07-30 10:41:13,061 - hy3dgen.shapgen - INFO - Loading model from /Volumes/L-SSD/AI/to3D/models-tencent-Hunyuan3D/hunyuan3d-dit-v2-mini/model.fp16.safetensors
2025-07-30 10:41:13 | INFO | hy3dgen.shapgen | Loading model from /Volumes/L-SSD/AI/to3D/models-tencent-Hunyuan3D/hunyuan3d-dit-v2-mini/model.fp16.safetensors
2025-07-30 10:41:45 | ERROR | stderr | INFO:     Started server process [12702]
2025-07-30 10:41:45 | ERROR | stderr | INFO:     Waiting for application startup.
2025-07-30 10:41:45 | ERROR | stderr | INFO:     Application startup complete.
2025-07-30 10:41:45 | ERROR | stderr | INFO:     Uvicorn running on http://0.0.0.0:8081 (Press CTRL+C to quit)

关于在tvt.js案例中引用

本地地址：http://localhost:8000/#/plugins/hunyuan3D/index
远程演示地址：https://opensource.icegl.cn/#/plugins/hunyuan3D/index
点击右上角 设置好调用地址

然后重新 生产，选择本地图片，提交即可。

我这里默认配置，等待时间大概在1-2分钟，根据系统配置不同时间也不一致。
生产之后，可以下载模型以及更换材质 预览效果。