Hunyuan3D-2云端部署实战：从环境搭建到稳定生成3D模型

1. 为什么我选择把Hunyuan3D-2放到云端去跑先讲一个背景。Hunyuan3D-2开源之后我第一时间就在本地机器上试了结果很真实——还没跑到一半显卡直接显存溢出进程被系统杀掉。我那台机器是RTX 4090 24GB按理说已经不算差了但在默认参数下跑一张1024分辨率的输入图峰值显存能飙到接近26GB以上稍微把分辨率调高一点或者增加生成面数就直接爆。后来调整参数勉强能跑但是单张图生成一个3D模型动辄十几分钟中间稍微切个程序或者开个浏览器显存一波动就失败重来体验非常糟糕。当时我就意识到一个事情Hunyuan3D-2这种规模的模型本地玩玩可以真想把它当工具用起来尤其是接一些批量任务或者给团队内部搭服务云端部署几乎是必选项。不只是显存的问题还有几个很现实的因素促成了我的这次云端部署实战。一是环境可控性。云端GPU实例是全新的系统环境我可以从零开始装驱动、配CUDA、装依赖完全按Hunyuan3D-2的官方文档要求来不用跟自己本机乱七八糟的Python环境、PyTorch版本、CUDA版本打架。二是资源按需伸缩。跑批量任务的时候租一张A100或者L40S跑完了直接释放成本远比自己买一张专业卡便宜。三是远端运行的压力小。本地跑大模型时风扇噪音、发热、占满整机资源都是问题丢到云端之后本机只负责发请求写代码、调试、日常办公都不受影响。这篇文章我会把这次云端部署Hunyuan3D-2的全过程完整拆出来包括环境怎么搭、模型怎么下、图生3D和文生3D两个分支分别怎么跑、哪些参数会影响稳定性和出图质量、我踩过的坑和排查思路。总的来说这篇内容适合两类人一类是刚接触3D生成、想在云端低成本跑通Hunyuan3D-2的新手另一类是想把3D生成接进自己工作流、需要稳定输出结果的开发者和设计师。2. 部署前的准备硬件选型、模型分支和基础知识在正式开始敲命令之前有几个东西必须先搞明白否则后面遇到问题容易一头雾水。2.1 云端GPU实例选什么规格Hunyuan3D-2对显存的需求主要集中在推理阶段。模型本身加上推理过程中KV cache、中间特征图等开销实际峰值显存占用远大于模型文件大小。我实测下来不同规格卡的表现差异非常大这里直接给一个参考表GPU型号显存大小实测能否运行单模型生成耗时图生3D512 tile稳定度评价RTX 409024GB勉强运行必须调参约6~10分钟低易超时或溢出RTX 6000 Ada48GB可流畅运行约3~5分钟中高L40S48GB可流畅运行约2~4分钟高A100 80GB80GB轻松运行约1~3分钟高H80080GB轻松运行约1~2分钟最高注意上面这个耗时是在推理阶段关了VLM视觉语言模型之后的结果。如果开着VLM做自动配文每次生成之前还要跑一轮大语言模型推理时间会追加。就性价比来说L40S是我这次的主力选择单卡租用价格远低于A10048GB显存又有足够的冗余不用时刻担心显存爆掉。2.2 Hunyuan3D-2的两个子模型分支Hunyuan3D-2不是一个单模型它内部包含两条生成分支一个是DiT分支扩散Transformer另一个是MGM分支多视图生成模型Multi-view Generation Model。这个要提前讲清楚因为它在使用上直接决定了你该怎么调参数和改配置。DiT分支是Hunyuan3D-2的主干它接收文本条件或者图像条件先预测出多视角的几何信息再经过后续重建模块生成最终的三维网格。它的优势在于对输入条件的理解更全面生成的几何结构更完整但缺点是推理时间相对较长。MGM分支是一个可以独立使用的多视图生成器从给定的一张参考图生成不同角度的多个视图后面再接重建模块得到3D模型。这个分支更适合图生3D的场景速度比DiT快对单张输入图的信息利用率更高。我的建议是如果你的目标是图生3D优先跑MGM分支如果要做文生3D或者希望生成更丰富的拓扑细节走DiT分支。后面实践部分会给出两个分支各自的完整命令。2.3 云端环境的硬性需求清单Hunyuan3D-2对运行环境有几个硬性要求少一个都会在运行时报各种莫名其妙的问题。这次部署我整理了一份环境清单操作系统Ubuntu 22.04 LTS及以上版本优先选带GPU驱动的官方镜像GPU驱动CUDA 12.1及以上驱动版本建议大于530Python3.10官方指定版本过高或过低都会遇到依赖冲突PyTorch2.4.0及以上注意要装CUDA版本显存24GB起步48GB舒适80GB随心所欲网络环境能够正常访问HuggingFace以及Github提示很多人忽略Python版本这个细节。我一开始在本地用的Python 3.11装依赖的时候发现几个包找不到对应wheel后来换成3.10才顺畅。云端部署就直接装3.10少走弯路。3. 云端实例初始化和环境搭建过程这一步是整个部署流程里最枯燥但也最关键的。环境搭得好后面所有步骤都是一路绿灯环境没搭好后面每天都是在跟报错搏斗。我尽量把每一步的细节和原因都写清楚。3.1 创建GPU实例和驱动检查我选择的是UCloud的GPU云主机选了L40S规格镜像选择Ubuntu 22.04带CUDA预装的版本。如果你用的其他云厂商流程大同小异核心就是在创建实例时选好GPU规格系统镜像带Ubuntu 22.04并且注意预留足够的数据盘空间Hunyuan3D-2的模型文件加起来大概需要30GB左右加上依赖和临时文件建议至少给100GB的数据盘。实例创建完成之后首先检查GPU驱动和CUDA是否正常nvidia-smi正常输出会显示GPU型号、显存大小、驱动版本和CUDA版本。如果这里显示N/A或者找不到GPU先执行下面的命令重装驱动ubuntu-drivers autoinstall reboot还有一个很多人会忽略的点就是检查nvcc版本和nvidia-smi显示的CUDA版本是否一致nvcc -V如果nvcc显示找不到说明没有装CUDA toolkit只装了驱动。Hunyuan3D-2的依赖编译过程中会用到nvcc建议提前装好apt update apt install -y nvidia-cuda-toolkit提示云厂商的官方镜像一般已经把CUDA装好了但是版本可能偏新。如果后面编译某个依赖时报不兼容的错误可以先把系统CUDA降到12.1再试这个我在后面问题排查部分会详细说。3.2 创建虚拟环境和安装基础依赖创建一个干净的Python 3.10虚拟环境这是我在所有Python项目中都会做的第一步避免全局环境被各种包污染conda create -n hunyuan3d python3.10 conda activate hunyuan3d接着安装PyTorch。这一步非常关键PyTorch版本直接决定后续所有依赖的兼容性。官方推荐的是2.4.0及以上这里我选择2.4.0的CUDA 12.4版本实测和Hunyuan3D-2的依赖配合得很稳定pip install torch2.4.0 torchvision0.19.0 --index-url https://download.pytorch.org/whl/cu124安装完PyTorch之后先验证一下GPU是否对PyTorch可见python -c import torch; print(torch.__version__, torch.cuda.is_available(), torch.cuda.device_count())如果输出的是2.4.0cu124 True 1说明PyTorch已经正确识别到了GPU可以继续往下走。3.3 拉取代码仓库和安装项目依赖接下来拉取Hunyuan3D-2的代码仓库git clone https://github.com/Tencent-Hunyuan/Hunyuan3D-2.git cd Hunyuan3D-2在安装依赖之前我建议先看一眼requirements.txt文件了解一下大概装了哪些东西。从我的经验看这个项目的依赖还挺重的会装上一批3D相关的库huggingface_hub负责从HuggingFace下载模型权重diffusers扩散模型推理的基础库transformers文本编码器相关trimesh三维网格处理和导出xatlas纹理展开rembg背景移除ftfy文本处理直接用pip安装pip install -r requirements.txt这个过程中大概率会遇到一些包下载慢或者编译报错的问题。在国内网络环境下建议先把pip源切换到清华或者阿里云的镜像速度会快很多一些包的编译超时问题也能得到缓解pip config set global.index-url https://mirrors.cloud.tencent.com/pypi/simple如果遇到某个包编译报错一定要仔细看报错信息。常见的几个坑是einops版本不兼容、triton编译时找不到CUDA等。解决方案一般是先升级pip到最新版然后单独安装报错的包。我在这次部署中遇到的最难缠的一个问题是xatlas的morton编译报错后来发现是因为编译环境缺少C编译器安装build-essential后解决apt install -y build-essential3.4 模型权重下载和目录结构确认Hunyuan3D-2的模型权重放在HuggingFace上需要在代码仓库的weights目录下手动下载。按照官方说明需要在weights/hunyuan3d-2目录下放入以下内容hunyuan3d_dit_v2-1DiT分支的权重hunyuan3d_mgm_v2-1MGM分支的权重hunyuan3d_shape_v2-1形状重建模块权重hunyuan3d_texture_v2-1纹理生成模块权重hunyuan3d_paint_v2-1纹理细化模块权重hunyuan3d_compress_v2-1网格压缩模块权重hunyuan3d_clip图像编码器权重hunyuan3d_llm大语言模型权重VLM用注意官方把权重传到了HuggingFace上文件名带了个-1或者类似后缀目的是让你确认文件完整下载前最好对比一下每个目录里的md5sum校验文件。我在第一次下载时就是因为没有校验结果模型文件不完整跑起来之后总是输出一些奇怪的畸形模型排查了整整一天。推荐直接用huggingface-cli下载每个子目录pip install huggingface_hub huggingface-cli download Tencent-Hunyuan/Hunyuan3D-2 --local-dir ./weights/hunyuan3d-2如果网络不稳定可以在命令后面加上--resume-download参数断点续传避免下载一半失败又从头开始。下载完之后的目录结构可以先用tree看一眼确认没有缺目录apt install -y tree tree -L 2 weights/4. 代码层面的关键调整跑得更稳的核心秘密这个部分是我最想分享的内容。官方仓库的代码直接跑有时候会遇到问题需要做一些微调。这些调整很多是经验问题你在官方文档里不一定能找到答案但实测下来确实能显著提升运行的稳定性。4.1 检查PyTorch版本与CUDA版本的匹配度Hunyuan3D-2的代码在CUDA 12.4和近期的PyTorch版本下运行最稳。如果在运行时报类似下面的错误RuntimeError: addmm_impl_cpu_ not implemented for Half这个错误本质上是半精度浮点在不支持的操作上被调用了。通常是因为你的GPU不支持某些半精度操作或者PyTorch的CUDA版本与GPU驱动之间不匹配。解决办法有两个方向一是把CUDA环境升级到12.4二是在代码里强制用float32计算关键模块。第二个方法我后面会细讲它是跑得稳的关键手段之一。4.2 注意力层改成float32准确性优先Hunyuan3D-2在推理过程中默认会使用半精度来加速计算。但根据我实际使用中的体验有些注意力计算在fp16下容易出现数值溢出结果就是生成的3D模型出现破面、空洞或者纹理扭曲。如果你像我一样更看重生成结果的质量而不是极限速度建议把注意力层的计算精度改成float32。定位到hunyuan3d-2/hy3dgen/shapegen/dit.py或者对应代码文件找到注意力计算相关的地方做一个简单的类型转换# 在Attention类的forward方法中将输入转换为float32 def forward(self, x): x x.to(torch.float32) # 原有注意力计算逻辑或者在调用模型时统一设置import torch from hy3dgen.shapegen import Hunyuan3DDiTForShape model Hunyuan3DDiTForShape.from_pretrained(weights/hunyuan3d-2/hunyuan3d_dit_v2-1) model model.to(torch.float32) # 将整个模型转成float32注意整体转float32会增加显存占用。如果你用的是24GB的卡可能会遇到显存不足的问题。折中方案是只把注意力层转成float32其他部分保持半精度。这个需要你根据实际情况去测试。4.3 Hunyuan3D-2的config文件需要调整哪些内容Hunyuan3D-2在模型加载时会读一个config.json文件里面定义了模型结构相关的超参数。我在云端部署时主要调整了以下几个地方第一是vae相关配置。如果config里指定的VAE模型路径不对或者权重文件不完整加载时会直接报错。这个注意点很好解决对比一下config里的相对路径和实际权重目录结构是否一致就行。第二是text_encoder路径。文生3D的流程中文本编码器是CLIP和T5双塔结构。如果只下载了其中一个运行时会提示找不到另一个模型。我建议在部署时提前检查config.json中text_encoder_config这部分的内容确保路径没问题。第三是attention_mode参数。默认是flash_attention这个模式对GPU显存友好、计算速度快但在某些GPU或者PyTorch版本下可能不受支持。如果你在运行时报flash attention相关的错误就把这个参数改成xformers或sdpa具体看你的环境里装了哪个。{ attention_mode: sdpa }把这里的flash_attention改成sdpa实测运行更稳定生成质量基本无损失。4.4 controlnet处理参数tile_size需要配合调整如果你的图像分辨率比较高比如1024x1024那么在controlnet处理阶段会出现tile切分参数和输入尺寸不匹配的问题。具体报错可能类似这样RuntimeError: The size of tensor a (72) must match the size of tensor b (70) at non-singleton dimension 3这个错误是因为controlnet内部将图像切成tile后tile边缘重叠导致尺寸不一致。处理办法是在调用controlnet前把图像resize到合适的分辨率或者设置tile_size参数来适配from hy3dgen.rembg import BackgroundRemover from hy3dgen.shapegen import Hunyuan3DDiTForShape from hy3dgen.shapegen.controlnet import ControlNet controlnet ControlNet( base_model_dirweights/hunyuan3d-2/hunyuan3d_shape_v2-1, tile_size512, # 确保tile_size能整除输入图像分辨率 dtypetorch.float32 )如果你只是命令行运行不打算改代码的话建议直接把输入图像resize到512x512或者1024x1024而不是用一个奇怪的尺寸比如768x640这样能规避掉大部分tile相关的问题。4.5 关闭torch.autocast避免不稳定因素Hunyuan3D-2的推理脚本里默认会开启torch.autocast也就是自动混合精度。这个机制在大部分情况下能加速计算但对于3D生成这种以数值精度为生命线的任务有时候反而会造成不稳定——中间特征图出现NaN最终生成的网格就是一堆乱七八糟的碎片。我的做法是直接关闭autocast。在推理脚本里注释掉或者去掉with torch.autocast(device_typecuda, dtypetorch.float16):这个上下文强制全精度计算。代价是速度会慢一些但换来的是生成结果的高可靠性。注意如果你的GPU驱动和PyTorch版本较好autocast也能稳定运行那么保持默认即可。这个建议是针对那些生成质量不稳定、时好时坏的情况。调试的时候先关掉autocast等确定整体流程没问题了再打开也不迟。5. 图生3D全流程实操环境配置好之后接下来的重头戏是实际跑任务。先写图生3D因为这是Hunyuan3D-2最核心的使用场景用一张普通图片生成一个可自由旋转、可导入建模软件的3D模型。5.1 输入图像预处理和背景移除图生3D对输入图像有一定要求最好是主体居中、背景干净的图片。如果原图背景复杂会严重干扰模型的几何重建生成结果里容易出现多馀的凸起或者空洞。Hunyuan3D-2自带背景移除功能基于rembg库。在命令行使用时脚本会自动对输入图像做背景处理。但如果你希望有更细致的控制可以先手动预处理from hy3dgen.rembg import BackgroundRemover remover BackgroundRemover() img remover.remove_bg(Image.open(input.png).convert(RGBA)) img.save(output_nobg.png)实测下来背景移除质量对最终3D效果的影响权重很高。同样的输入图干净背景和复杂背景生成的模型差别极大。所以我会在预处理阶段多花一些精力确保主体完整、边缘干净。5.2 图生3D的完整命令和参数解析Hunyuan3D-2官方提供了一套基于Gradio的WebUI但如果你要批量跑任务或者想精细控制参数建议直接使用命令行接口。这次云端部署我用的就是命令行方案。进入项目根目录后最简单的图生3D命令如下python -m hy3dgen.shapegen -a hunyuan3d-2 -i input.png -o output.glb --type image其中各个参数的含义是-a指定方法这里是hunyuan3d-2-i指定输入图像路径-o指定输出文件路径支持.glb、.obj、.fbx等常见3D格式--type指定输入类型图片就是image如果你用Python代码调用则是这样的写法from hy3dgen.shapegen import Hunyuan3DDiTForShape from hy3dgen.rembg import BackgroundRemover from hy3dgen.text2image import HunyuanText2Image # 图生3D model Hunyuan3DDiTForShape.from_pretrained(weights/hunyuan3d-2/hunyuan3d_dit_v2-1) output_mesh model(imageimg) output_mesh.export(output.glb)有几个关键参数会直接影响生成效果和运行稳定性我用一个表格整理一下参数作用推荐值注意事项tile_sizecontrolnet的tile切分大小512必须能整除输入分辨率density生成网格的密度/三角形数量默认即可数值越大生成越慢但细节越多steps扩散模型推理步数30步数太多不显著提升质量但耗时翻倍max_faces_num最终网格的最大面数100000面数越高质量越高但渲染压力大texture_size纹理图分辨率1024纹理越大占显存越多5.3 三个不同的图生3D方法对比Hunyuan3D-2提供的不只一条图生3D路径不同方法在生成速度和效果上差异明显。我实测了三种方式第一种是只用MGM分支的多视图生成方法速度最快适合对拓扑完整性要求不高的场景from hy3dgen.multiview import Hunyuan3DMultiView from hy3dgen.shapegen import Hunyuan3DShapeGen shapegen Hunyuan3DShapeGen.from_pretrained(weights/hunyuan3d-2/hunyuan3d_shape_v2-1) mvgen Hunyuan3DMultiView.from_pretrained(weights/hunyuan3d-2/hunyuan3d_mgm_v2-1) views mvgen(imageimg) # 生成多视角图 mesh shapegen(imagesviews) # 多视角重建3D第二种是走DiT分支直接用单张图预测三维形状生成的几何结构更准确但耗时是MGM的2倍左右。官方推荐的Hunyuan3DDiTForShape就是这类。第三种是先用文生图模型从文本生成一张图再走图生3D流程。这三种方法我建议按需选择如果要求快速出效果用MGM如果模型要用于后续的动画绑定和材质制作用DiT分支。5.4 实测数据不同输入下的表现和耗时为了让你对耗时和效果有个直观的认识我贴一组实测数据。输入图是512x512的商品白底图输出格式为glb参数量使用默认值输入类型使用分支生成耗时显存峰值生成结果质量白底商品图MGM52秒21GB轮廓准确背面细节一般白底商品图DiT3分28秒28GB几何完整侧面和背面细节好实拍场景图(预处理后)MGM1分06秒22GB细节尚可底部有轻微变形实拍场景图(预处理后)DiT4分12秒31GB整体优秀底部略有拉丝从这个表格能看得出来对于简单的主体MGM分支完全够用且速度快得多对于复杂的实拍图建议直接用DiT分支保证模型质量代价是时间成本将近4倍。请根据自己实际需求取舍。如果你跑出来的结果一团糟大概率不是模型问题而是输入图没处理好。比如主体和背景颜色太接近、主体不居中、图片里有多余物体等都会严重影响重建效果。6. 文生3D全流程实操文生3D是Hunyuan3D-2的另一张王牌。和图生3D不同文生3D的输入是一段文本描述整个流程分两截先把文本变成图像再把图像变成3D模型。所以文生3D的质量上限很大程度取决于中间的文生图环节做得怎么样。6.1 文本到3D的级联生成流程Hunyuan3D-2官方仓库里集成了一个文生图模块基于社区里常用的扩散模型结构。当你输入一只戴帽子的柴犬这样一句话时系统会先根据文本生成一张符合描述的图像然后把这张图送到图生3D流程里最终输出3D模型。在命令行模式下文生3D的命令是python -m hy3dgen.shapegen -a hunyuan3d-2 -p 一只戴帽子的柴犬 -o dog.glb --type text其中-p参数后面跟的就是文本提示词。如果你用Python代码方式跑流程如下from hy3dgen.shapegen import Hunyuan3DDiTForShape from hy3dgen.text2image import HunyuanText2Image t2i HunyuanText2Image(weights/hunyuan3d-2/hunyuan3d_clip) model Hunyuan3DDiTForShape.from_pretrained(weights/hunyuan3d-2/hunyuan3d_dit_v2-1) # 第一步文生图 img t2i(一只戴帽子的柴犬) # 第二步图生3D mesh model(imageimg) mesh.export(dog.glb)6.2 提示词编写技巧和实测效果文生3D的提示词和纯文生图还不完全一样因为多了一步图生3D的中间过程提示词需要考虑两个阶段的需求。我总结了几个实用技巧描述要具体但不是越啰嗦越好。一只戴帽子的柴犬比一只狗效果好得多但一只戴棕色帽子的白色柴犬坐姿面对镜头又比简单描述更好。关键是把主体的种类、主要颜色、姿态都说清楚。不要描述背景或者复杂的场景。森林里的鹿这种提示词会让中间阶段的图像把焦点放在场景而不是主体上导致重建出来的模型只保留鹿而丢掉背景或者反过来把树也重建进去了。材质描述要克制。虽然你可以写金属质感的机器人但3D重建阶段的材质表达能力有限最终出来的效果可能不如简单描述然后后期处理材质。我实测了几组提示词的效果提示词中间图像质量最终3D效果备注一个苹果优秀优秀球体拓扑完美简单物体效果好戴帽子的柴犬良好良帽子部分细节丢失复杂物体细节有损穿西装的企鹅良好良好但背面纹理扭曲侧面视角依赖多森林里的鹿一般一般树木被重建为多余结构不建议场景类描述6.3 文生3D的推理加速技巧文生3D因为多了一个文生图步骤整体耗时会更长。实测跑一个中等复杂度的物体从文本输入到最终导出glb大约需要8~15分钟。如果你想加速这个过程最有效的方式是使用官方提供的加速模式在运行命令时加上--fast参数python -m hy3dgen.shapegen -a hunyuan3d-2 -p 一个苹果 -o apple.glb --type text --fast--fast模式的原理是在积水地面阶段使用更小的扩散步数和更少的采样次数VLM视觉语言模型也被关闭整体速度大约能提升1.5~2倍。代价是最终模型的细节会少一些尤其在纹理阶段可能会看到一些模糊。另外可以做的优化是关闭VLM。Hunyuan3D-2在生成过程中默认会加载一个视觉语言模型来处理多视图图像这个模型的显存占用和计算开销都不低。如果只是做常规的图生3D或者文生3D可以在调用时设置--without-vlmpython -m hy3dgen.shapegen -a hunyuan3d-2 -i input.png -o output.glb --type image --without-vlm这样处理速度会快不少显存占用能下降5~8GB左右。7. 跑得更稳的进阶建议量化、临时目录和保活整个链路跑通之后我开始关注跑得更稳这件事。这里有几个经验和坑值得单独拿出来写。7.1 临时目录空间不足导致的中途失败云端实例刚创建时默认的数据盘分配可能比较小但Hunyuan3D-2在运行过程中会在系统临时目录写入大量中间文件包括多视图图像、中间网格缓存、纹理图等轻松就能占用几十GB的空间。如果临时目录所在的分区满了程序会在运行到一半的时候报No space left on device。这个问题在后台跑任务的时候尤其坑因为不是一开始就报错而是跑了十几分钟之后才失败浪费大量时间。我的解决办法是把临时文件目录指到空间充足的数据盘export TMPDIR/data/tmp mkdir -p /data/tmp还可以在Python代码里设置import tempfile tempfile.tempdir /data/tmp建议在创建实例的时候就规划好数据盘至少100GB起步。7.2 模型量化和显存优化方案如果你只有24GB显存想跑Hunyuan3D-2也不是完全没戏但需要做一些取舍。我推荐的方案是使用FP8量化。Hunyuan3D-2官方的量化方案支持将部分模块量化为FP8能有效降低显存占用同时保真度损失在可接受范围内。python -m hy3dgen.shapegen -a hunyuan3d-2 -i input.png -o output.glb --type image --quantize-fp8实测下来FP8量化后显存占用大约能降低15%~20%生成质量几乎无肉眼可见差异。不过要注意FP8加速在当前PyTorch版本里需要最新的CUDA支持如果你的卡不支持FP8指令集命令会直接报错这种情况下可以换用--quantize-int8或者干脆不量化只改tile_size。还有一个调参方向是降低输出网格的分辨率。默认的max_faces_num是100000如果你对这个模型的要求只是看个大概可以调到50000显存占用和生成时间都会有明显下降。7.3 任务防中断用screen和nohup保活云端部署还有一个很现实的问题如果你是通过SSH连接服务器跑任务的一旦网络不稳定或者本地电脑休眠SSH会话断开后正在跑的生成任务通常会被直接杀掉跑到一半的3D模型就白跑了。解决方法有两种。一种是用screen命令创建一个持久会话即使SSH断开任务也会在服务器上继续跑screen -S generate python -m hy3dgen.shapegen -a hunyuan3d-2 -i input.png -o output.glb --type image # 按 CtrlA 然后按 D detach会话 # 重新连接时用 screen -r generate 恢复另一种是用nohup配合重定向日志nohup python -m hy3dgen.shapegen -a hunyuan3d-2 -i input.png -o output.glb --type image generate.log 21 tail -f generate.log第二种方式更轻量看到日志里输出了最终结果文件路径就说明任务完成了。7.4 和模型保持“距离”对于Hunyuan3D-2这种大模型建议多用CLI我知道很多同学一听到云端部署就想搞一个WebUI界面用浏览器点点点就能生成3D。Hunyuan3D-2官方也提供了Gradio WebUI但我个人强烈建议在云端环境里优先使用CLI命令行。原因有三点第一WebUI会额外占用显存。Gradio界面本身消耗的资源虽然不多但对显存敏感的部署场景来说能省则省。第二WebUI不适合批量任务。你要处理100张图的话点100次按钮这种操作想想都痛苦而CLI一行for循环就搞定了。第三排查问题更容易。命令行报错信息直接打在终端里WebUI的错误信息经过层层封装定位问题难度翻倍。8. 常见问题与排查技巧实录部署和运行Hunyuan3D-2这半个月里我把遇到过的典型问题整理成了一份速查表每个问题都附上了排查思路和处理方法希望能帮你少走一些弯路。8.1 显存不足OOM问题这个是出现频率最高的问题。表现是在生成过程中某个时刻程序直接退出报错信息类似CUDA out of memory. Tried to allocate 2.67 GiB (GPU 0; 23.65 GiB total capacity; 21.22 GiB already allocated; 1.01 GiB free; 24.51 GiB reserved in total by PyTorch)出现这个问题优先考虑调整三个参数一是把tile_size从512改到256或128二是把max_faces_num从100000降到50000三是把输入图像分辨率从1024降到512。如果还不行考虑开启FP8量化或者直接在L40S以上规格的实例上运行。注意显存不足往往不是单一原因造成的。如果你同时开了多个进程比如一个在跑图生3D另一个在跑WebUI即便每单个任务看起来都不大加起来也会超过显存上限。跑3D生成任务时尽量保持服务器上其他GPU进程清空。8.2 生成结果出现破面或畸形生成出来的模型表面有大量空洞或者某些面翻转整体的形状看起来像一个没充气的气球。这种问题需要从几个角度排查首先检查输入图像。如果输入图像本身分辨率低或者主体有遮挡重建出来破面的概率会很高。其次检查是否关闭了autocast如果你用了半精度且没有做任何处理float16的精度损失可能会导致几何重建不稳定。最后检查模型权重文件是否完整不完整的权重文件表现之一就是输出畸形网格。8.3 模型加载时提示找不到文件或路径这类报错通常是权重目录结构没放对。比如OSError: weights/hunyuan3d-2/hunyuan3d_dit_v2-1 does not appear to have a file named config.json排查方法是直接看这个目录下有没有config.json以及对应的.safetensors权重文件。注意有些云盘或者网盘下载会重命名文件导致后缀不对这也是常见坑。8.4 HTTP 500 错误HuggingFace 连接超时国内直连HuggingFace有时候会超时表现为下载模型权重时中断或者报Connection error。解决办法是配置HuggingFace的镜像站国内有很多第三方镜像可以选择export HF_ENDPOINThttps://hf-mirror.com设置之后重新用huggingface-cli download下载速度快很多。8.5 运行过程中卡死或超时如果你用的是API方式调用Hunyuan3D-2比如把部署好的服务用FastAPI封装特别注意默认的请求超时时间。单个3D模型的生成动辄几分钟如果你没有设置足够长的超时时间客户端那边往往会在3~5分钟之后自动断开连接造成任务继续跑但客户端报错的假象。这里建议在服务端设置合理的超时时间或者采用异步任务队列的方式先把生成结果保存到本地客户端隔一段时间来查状态。官方仓库里有一个简单的Gradio示例但生产使用我都是自己包装一层任务队列。9. 我最想分享的几个实际经验最后说说几个我使用Hunyuan3D-2过程中沉淀下来的个人体会。第一个是关于稳字的理解。很多人以为跑得稳就是纯粹不报错、不崩溃但实际操作下来稳还包含另外两个层面一是Repeated的结果一致性要够好二是长耗时任务中途不失败。这两个层面在日常使用中比不报错更重要。第二个经验是模型权重的文件校验一定要做。Hunyuan3D-2的权重文件比较大从网上下载很容易出现文件损坏的情况。文件损坏不一定会直接报错更多的情况是生成出来的结果莫名其妙的差——模型形状完全不对、纹理错乱、表面一坨糊。这种问题的排查成本极高因为它不会给你清晰的报错信息。提前校验一下md5或者文件大小能省掉太多不必要的排查时间。第三个经验是关于显卡选择的思路。很多人一上来就选A100 80GB觉得显存越大越好。但实际上L40S或者RTX 6000 Ada在很多场景下已经足够而且性价比高很多。Hunyuan3D-2这种模型对算力的需求主要在扩散模型的去噪过程和后处理阶段对显存带宽的敏感度不如对容量的敏感度高48GB基本就是甜点级别除非你要同时跑多个任务或者处理超高分辨率的输入否则没必要上80GB。最后给一个实用的小技巧跑Hunyuan3D-2的时候把输入图裁成正方形。这个模型在编码阶段会将输入图resize到固定分辨率如果你的原图是长方形它会先裁剪或者拉伸导致主体变形。比如一张1920x1080的图会被强制转换到512x512人物会被压扁。预处理阶段手动裁成正方形能有效避免这个问题。这次云端部署Hunyuan3D-2的完整过程大概就是这些。从环境搭建到跑通两条生成链路再到性能调优和问题排查各个环节都有可以深挖的细节。如果你也在部署这个模型建议先从图生3D的MGM分支入手跑通全流程再逐步切到DiT分支和文生3D这样整个学习曲线最平滑遇到问题也更容易定位。希望这篇文章能帮你在云端顺利跑起Hunyuan3D-2生成出理想的3D模型。