Hunyuan3D本地部署

1.环境准备

新建一个python 3.10的环境并激活进入该环境

Hunyuan3D要求CUDA版本为12.1，先查一下有没有对应版本

ls -l /usr/local/ | grep cuda-12.1

有的话我们需要在该虚拟环境中指向该CUDA版本的路径

# 手动创建 activate.d 目录（按 conda 规范路径）
mkdir -p $CONDA_PREFIX/etc/conda/activate.d/

# 进入刚创建的 activate.d 目录
cd $CONDA_PREFIX/etc/conda/activate.d/

# 创建环境变量配置文件
touch cuda121_env.sh
echo 'export PATH=/usr/local/cuda-12.1/bin:$PATH' >> cuda121_env.sh
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH' >> cuda121_env.sh

# 赋予执行权限
chmod +x cuda121_env.sh

# 先退出环境
conda deactivate

# 重新激活环境，加载新配置
conda activate hunyuan3d

指向后，可以nvcc -V查看一下当前虚拟环境对应的CUDA版本

无误后，从GitHub上把项目拉下来。如果外网下载不下来，或者比较慢的话，可以手动去官网下载zip，再上传服务器，再unzip即可。

git clone https://github.com/Tencent/Hunyuan3D-2.git

而后先指定下pip镜像源，再进行安装

# 更换 pypi 源加速库
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

cd ./Hunyuan3D-2
pip install -r requirements.txt

# for texture
cd hy3dgen/texgen/custom_rasterizer
python3 setup.py install
cd ../../..
cd hy3dgen/texgen/differentiable_renderer
python3 setup.py install

2.下载模型

        截至2025.3.20，Hunyuan3D-2模型仓库大小约为56GB，Hunyuan3D-2mv为28GB，Hunyuan3D-2mini为23GB，请参考官方运行硬件要求以及显存消耗拉取所需模型仓库，完整拉取供需106GB硬盘空间。先df -h指令查看一下硬盘存储情况，按需安装即可。模型下载指令中记得将‘—local-dir’后或’cache_dir‘的路径替换为自己存放的本地数据盘路径

export HF_ENDPOINT="https://hf-mirror.com"
source ~/.bashrc
# Hunyuan3D-2
huggingface-cli download --resume-download tencent/Hunyuan3D-2 --local-dir /root/autodl-tmp/weights/Hunyuan3D-2
# Hunyuan3D-2mv
huggingface-cli download --resume-download tencent/Hunyuan3D-2mv --local-dir /root/autodl-tmp/weights/Hunyuan3D-2mv
#Hunyuan3D-2mini
huggingface-cli download --resume-download tencent/Hunyuan3D-2mini --local-dir /root/autodl-tmp/weights/Hunyuan3D-2mini

3.模型调用

我只拉了Hunyuan3D-2，也就是单视图白模生成+纹理生成

3.1单视图白模生成

在项目仓库下（Hunyuan3D-2/hy3dgen/shapegen/utils.py:83）更改模型加载路径base_dir

新建一个测试脚本

import time
import torch
from PIL import Image

from hy3dgen.rembg import BackgroundRemover
from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline

image_path = '输入图像路径'
image = Image.open(image_path).convert("RGBA")
if image.mode == 'RGB':
    rembg = BackgroundRemover()
    image = rembg(image)

pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
    '模型上一层文件路径/Hunyuan3D-2-main/model/Hunyuan3D-2',
    subfolder='hunyuan3d-dit-v2-0',
    variant='fp16'
)

start_time = time.time()
mesh = pipeline(image=image,
                num_inference_steps=50,
                octree_resolution=380,
                num_chunks=20000,
                generator=torch.manual_seed(12345),
                output_type='trimesh'
                )[0]
print("--- %s seconds ---" % (time.time() - start_time))
mesh.export(f'输出路径/Hunyuan3D-2-main/output/yaya.glb')

执行该脚本，大概30s内就生成了

生成的文件是glb文件，可以在线查看，也可以blender导入。这里是我随手放的一个手托乌鸦玩偶的图片。

3.2单视图纹理生成

        同理先去改一下模型的读取路径，在Hunyuan3D-2/hy3dgen/texgen/pipelines.py:55，这边要改两个地方，一个是base_dir，一个是multiview_model_path的第二个参数

        再新建一个测试脚本

from PIL import Image

from hy3dgen.rembg import BackgroundRemover
from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
from hy3dgen.texgen import Hunyuan3DPaintPipeline

model_path = '调用的模型的本地路径Hunyuan3D-2-main/model/Hunyuan3D-2/AI-ModelScope/Hunyuan3D-2'
pipeline_shapegen = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(model_path)
pipeline_texgen = Hunyuan3DPaintPipeline.from_pretrained(model_path)

image_path = '自己图像的输入路径"
image = Image.open(image_path).convert("RGBA")

if image.mode == 'RGB':
    rembg = BackgroundRemover()
    image = rembg(image)

mesh = pipeline_shapegen(image=image)[0]
mesh = pipeline_texgen(mesh, image=image)
mesh.export('输出保存路径Hunyuan3D-2-main/output/rixiang_textured.glb')

        运行脚本，输出信息如下，这里需要的时间会很长，可以直接扔后台去输出

        用blender打开输出的模型。blender刚打开还是白模，需要 z 快捷键选择blender进行渲染一下

4.致谢

多谢datawhale官方提供的指导手册

Hunyuan3D官方GitHub主页