Hunyuan3D-2mv 本地部署

发布时间: 2026-05-22

本文记录在 Windows Server 上本地部署 腾讯混元 3D 大模型 (Hunyuan3D-2mv) 的完整流程，包括环境搭建、模型下载、纹理编译及踩坑总结。

测试环境配置：

准备工作 #

硬件要求 #

消费级显卡理论上也可以跑（未验证），本文使用 P40 24G 服务器显卡。

• GPU：NVIDIA 显卡，驱动版本 ≥ 576.57 （2025 年 6 月以后）
• 几何模型显存：≥ 3 GB（2.1 模型最大优化）
• 纹理模型显存：≥ 6 GB（2.0 模型最大优化）
• 系统内存：≥ 24 GB（显存越小，所需内存越大，用于模型卸载）

内容来源：Hunyuan3D-2-WinPortable

软件要求 #

相关资源 #

• Hunyuan3D-2mv 模型文件（国内镜像）
• Hunyuan3D-2 官方代码仓库
• Hunyuan3D-2 模型文件（含纹理模型）
• GLB 在线预览工具

快速开始 #

1. 克隆模型文件（约 50 GB，国内镜像下载速度更快）

   git clone https://gitcode.com/hf_mirrors/tencent/Hunyuan3D-2mv

2. 克隆运行代码

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

3. 创建并激活虚拟环境

   # 进入代码目录
   cd Hunyuan3D-2
   # 创建 Python 3.10 虚拟环境
   py -3.10 -m venv hy3d
   # 激活环境
   hy3d\Scripts\activate

4. 安装 PyTorch（根据 CUDA 版本调整，此处为 CUDA 12.1）

   pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

5. 安装核心依赖

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

6. 验证模型

   提示

   请将 E:/yh3d/Hunyuan3D-2mv 替换为你的模型文件路径，hunyuan3d-dit-v2-mv-turbo 替换为对应的模型名称。

   test.py 测试代码

   from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline
   import torch
   
   # 加载模型（你本地路径）
   pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
   	"E:/yh3d/Hunyuan3D-2mv",
   	subfolder="hunyuan3d-dit-v2-mv-turbo",
   	use_safetensors=True,
   	local_files_only=True,
   	device="cuda"
   )
   
   # 输入多视角图片
   images = {
   	"front": "./images/front.png",
   	"left": "./images/left.png",
   	"back": "./images/back.png",
   }
   
   # P40 最优参数
   mesh = pipeline(
   	image=images,
   	num_inference_steps=25,
   	octree_resolution=320,
   	num_chunks=6000
   )[0]
   
   mesh.export("p40_output.glb")
   print("✅ 3D模型生成完成：p40_output.glb")

7. 执行代码

   python test.py

编译纹理/光栅化扩展 #

安装 VS 编译工具 #

下载 Build Tools for Visual Studio 2022（需登录账号）。

安装时勾选以下组件：

• 使用 C++ 的桌面开发
• Windows 10 SDK 或 11 SDK

安装 CUDA #

实测 CUDA 12.1 编译会报版本过低错误，使用 CUDA 12.4 可正常编译通过。安装方式：双击 exe 选择 精简安装，一路下一步即可。

• CUDA 下载页面
• CUDA 12.4.0 下载

编译纹理 #

1. 启动 x64 Native Tools Command Prompt for VS 2022，显示如下信息表示初始化成功：

   **********************************************************************
   ** Visual Studio 2022 Developer Command Prompt v17.14.33
   ** Copyright (c) 2025 Microsoft Corporation
   **********************************************************************
   [vcvarsall.bat] Environment initialized for: 'x64'
   
   H:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools>

2. 设置环境变量并激活虚拟环境

   set DISTUTILS_USE_SDK=1
   set MSSdk=1
   # 切换到项目目录后激活虚拟环境
   hy3d\Scripts\activate

3. 依次编译光栅化与可微渲染扩展

   cd hy3dgen/texgen/custom_rasterizer
   python setup.py install
   cd ../differentiable_renderer
   python setup.py install
   cd ../../../..

启动 gradio_app #

gradio_app.py 主要参数说明：

options:
  -h, --help            显示帮助信息
  --model_path          【几何模型】根目录
  --subfolder           几何模型的子文件夹名
  --texgen_model_path   【纹理模型】根目录
  --port PORT           服务端口
  --host HOST           服务地址
  --device              使用的 GPU 设备
  --mc_algo MC_ALGO     Marching Cubes 算法
  --cache-path          缓存目录
  --enable_t23d         启用文本生 3D
  --disable_tex         关闭纹理（False=开启，True=关闭）
  --enable_flashvdm     启用 FlashVDM 加速
  --compile             启用编译加速
  --low_vram_mode       启用低显存模式

启动命令示例：

python gradio_app.py ^
--model_path "E:\yh3d\Hunyuan3D-2mv" ^
--subfolder "hunyuan3d-dit-v2-mv" ^
--device cuda ^
--low_vram_mode

使用纹理 #

默认情况下，应用启动时会自动从 Hugging Face 下载纹理模型（约 74.9 GB）。本文使用国内镜像下载，需要配置 HY3DGEN_MODELS 环境变量，否则每次启动都会尝试联网下载。

模型版本对照表：

下载 tencent/Hunyuan3D-2 #

# 1. 激活 hy3d 虚拟环境
hy3d\Scripts\activate

# 2. 安装 huggingface_hub
pip install huggingface_hub

# 3. 设置国内镜像地址
set HF_ENDPOINT=https://hf-mirror.com

# 4. 下载模型文件
huggingface-cli download tencent/Hunyuan3D-2 --local-dir ./Hunyuan3D-2

环境变量 #

设置纹理模型环境变量。注意：不能通过 --texgen_model_path 参数指定，因为源码里写死了路径（tencent\Hunyuan3D-2）。

• HY3DGEN_MODELS：模型文件根目录

set HY3DGEN_MODELS=H:/hy3d/texl

启动 APP #

启动后界面会出现 Gen textured Shape 按钮。经测试生成纹理存在问题，可能是显卡过旧（P40），纹理生成耗时远超白模生成，最终导致 Python 程序崩溃。

测试纹理 #

一、官方 demo：生成小企鹅并附带纹理 #

from PIL import Image

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

model_path = 'tencent/Hunyuan3D-2'
pipeline_shapegen = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(model_path)
pipeline_texgen = Hunyuan3DPaintPipeline.from_pretrained(model_path)

image_path = 'assets/demo.png'
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('demo.glb')

二、为已有白模生成纹理 #

import torch
import trimesh
from PIL import Image
from hy3dgen.texgen import Hunyuan3DPaintPipeline
from hy3dgen.rembg import BackgroundRemover

# ====================== 路径自己改 ======================
GLB_MODEL_PATH  = r"E:/yh3d/Hunyuan3D-2/gradio_cache/dd8fa759-be74-4892-9468-3a3adf87c8c2/white_mesh.glb"  # 你的白模glb
REFERENCE_IMG  = r"E:/yh3d/Hunyuan3D-2/baicai.png"                              # 生成这个3D用的原图
SAVE_PATH      = r"E:/yh3d/Hunyuan3D-2/baicai.glb"                     # 输出带纹理模型
# =========================================================

# 加载纹理模型
print("加载纹理模型...")
tex_pipe = Hunyuan3DPaintPipeline.from_pretrained("tencent/Hunyuan3D-2")

# 加载参考图（必须是生成3D的原图）
print("加载参考图...")
image = Image.open(REFERENCE_IMG).convert("RGB")

# 去背景（必须）
rembg = BackgroundRemover()
image = rembg(image)

# 加载已有的白模
print("加载GLB模型...")
mesh = trimesh.load(GLB_MODEL_PATH)

# 生成纹理（核心！）
print("开始生成纹理...")
textured_mesh = tex_pipe(mesh, image=image)

# 保存带纹理的模型
print("保存模型...")
textured_mesh.export(SAVE_PATH)

print(f"✅ 纹理生成完成！保存到：{SAVE_PATH}")

总结 #

部署过程踩坑总结：

1. 模型文件体积庞大，请预留充足磁盘空间（至少 100 GB）。
2. 必须使用 Python 3.10，其他版本会出现各种依赖兼容问题。
3. 纹理模型路径在源码中写死，无法通过命令行参数 --texgen_model_path 指定全路径、相对路径或模型名称，只能通过 HY3DGEN_MODELS 环境变量来处理。

相关源码位于 Hunyuan3D-2\hy3dgen\texgen\pipelines.py 第 53 行附近：

class Hunyuan3DPaintPipeline:
    @classmethod
    def from_pretrained(cls, model_path, subfolder='hunyuan3d-paint-v2-0-turbo'):
        original_model_path = model_path
        if not os.path.exists(model_path):
            # try local path
            base_dir = os.environ.get('HY3DGEN_MODELS', '~/.cache/hy3dgen')
            model_path = os.path.expanduser(os.path.join(base_dir, model_path))

            delight_model_path = os.path.join(model_path, 'hunyuan3d-delight-v2-0')
            multiview_model_path = os.path.join(model_path, subfolder)

            if not os.path.exists(delight_model_path) or not os.path.exists(multiview_model_path):
                try:
                    import huggingface_hub
                    # download from huggingface
                    model_path = huggingface_hub.snapshot_download(
                        repo_id=original_model_path, allow_patterns=["hunyuan3d-delight-v2-0/*"]
                    )
                    model_path = huggingface_hub.snapshot_download(
                        repo_id=original_model_path, allow_patterns=[f'{subfolder}/*']
                    )
                    delight_model_path = os.path.join(model_path, 'hunyuan3d-delight-v2-0')
                    multiview_model_path = os.path.join(model_path, subfolder)
                    return cls(Hunyuan3DTexGenConfig(delight_model_path, multiview_model_path, subfolder))
                except Exception:
                    import traceback
                    traceback.print_exc()
                    raise RuntimeError(f"Something wrong while loading {model_path}")
            else:
                return cls(Hunyuan3DTexGenConfig(delight_model_path, multiview_model_path, subfolder))
        else: