Hunyuan3D-Omni Shape-DiT 剖析:3.3B 三维扩散 Transformer 如何从潜空间去噪到几何网格
Hunyuan3D-Omni Shape-DiT 剖析:3.3B 三维扩散 Transformer 如何从潜空间去噪到几何网格
Hunyuan3D-Omni 是腾讯混元开源的统一可控 3D 资产生成框架,其核心是一个 3.3B 参数的 Shape-DiT(三维扩散 Transformer)。它继承 Hunyuan3D 2.1 的潜空间扩散结构,并新增统一控制编码器,支持点云、体素、骨骼姿态、边界框四种控制信号。本文将带你快速看懂:从一张图片加控制条件,到 Flow Matching 在潜空间逐步去噪,最终经八叉树与 Marching Cubes 还原出高保真 3D 网格的完整链路。
一、整体架构:五大核心模块协同工作
Hunyuan3D-Omni 的推理管线由五个模块组成,定义在 pipeline_generation_sit_omni.py 的 Hunyuan3DOmniSiTFlowMatchingPipeline 中:
| 模块 | 作用 | 源码位置 |
|---|---|---|
| Shape-VAE | 点云 ↔ 64 维潜向量互转 | shape_vae.py |
| Condition Encoder | 融合图像与多模态控制信号 | omni_encoder.py |
| Shape-DiT | 潜空间去噪主力(3.3B) | hunyuan3ddit.py |
| Flow Matching Scheduler | 50 步 ODE 采样 | transport/ |
| Image Processor | 图像预处理与抠图 | preprocessors.py |
生成流程可以概括为一句话:图像与控制条件编码为上下文 → 随机潜向量沿 Flow Matching 轨迹迭代去噪 50 步 → Shape-VAE 解码出八叉树占用场 → Marching Cubes 抽取网格。
二、Shape-VAE:点云如何压缩进潜空间
Shape-DiT 并不直接操作点云,而是在一个紧凑的潜空间中去噪,这正是 VAE(变分自编码器)的价值所在。
- 编码:
PointCrossAttentionEncoder从模型表面采样数十万个点,按 FPS(最远点采样)降采样出一组 query 点,再用交叉注意力把点云"吸收"进固定数量的 latent tokens(见 shape_vae.py); - 解码:
CrossAttentionDecoder反过来用查询点 cross-attention 潜向量,输出八叉树上的占用概率;推理时按octree_resolution=512逐级细化,再用 Marching Cubes(mc_level)从占用场切出网格面(解码入口在 shape_vae.py)。
💡 潜空间的形状由
self.vae.latent_shape决定,初始噪声就是按这个形状采样的高斯随机向量(pipeline_generation_sit_omni.py)。
三、统一条件编码器:一张图 + 四种控制信号
OmniEncoder 是 "Omni" 的关键,它把图像语义与几何控制拼成同一个条件序列,见 omni_encoder.py:
- 图像分支:用 DINOv2 提取图像的 patch 特征(
last_hidden_state),承载"长什么样"; - 几何分支:控制信号(骨骼点/边界框/体素/点云坐标)先经 Fourier 位置编码(
FourierEmbedder),再过线性层+RMSNorm+GELU 投影到 1024 维; - 类型标记:每种控制类型分配一个可学习的 embedding 编号(pose=0、bbox=1、voxel=2、point=3),重复 10 次作为"控制信号 token",让 DiT 明确知道自己收到的控制类型。
一个巧妙的细节:体素控制会先把输入点云量化到 16³ 网格(generate_voxel),去重后取每个体素中心作为控制点;边界框则先展开为 8 个角点(bbox_to_corners)。这保证了不同模态在统一的"点坐标"语义下进入同一套编码流程。
四、Shape-DiT 内部:48 层双流 + 单流 Transformer
3.3B 主干定义在 hunyuan3ddit.py,核心参数一览:
| 参数 | 默认值 | 说明 |
|---|---|---|
in_channels |
64 | 潜向量通道数 |
hidden_size |
1024 | 隐层维度 |
num_heads |
16 | 注意力头数 |
depth |
16 | 双流块(DoubleStreamBlock)层数 |
depth_single_blocks |
32 | 单流块(SingleStreamBlock)层数 |
其前向逻辑(forward)分四步:
- 潜向量投影:
latent_in把 64 维潜 token 投影到 1024 维; - 时间嵌入:去噪步长 t 经正弦编码 + MLP 得到
vec,通过 AdaLN 调制(shift/scale/gate)注入每一层——这是扩散模型"知道当前该去噪多少"的机制; - 16 层双流块:图像流与条件流(DINO 特征 + 控制 token)各自做归一化与调制后,拼接 q/k/v 做联合自注意力,实现条件与潜变量的双向信息交换(DoubleStreamBlock);
- 32 层单流块:条件 token 与潜 token 拼成一条长序列,用 32 层
SingleStreamBlock充分融合,最后丢弃条件段、经LastLayer投影回 64 维,输出速度场预测。
此外,Q/K 均使用 RMSNorm(QKNorm)稳定注意力,注意力后端默认 PyTorch SDPA,也可通过环境变量切换 sageattention 加速。
五、Flow Matching:50 步从纯噪声走到几何
Hunyuan3D-Omni 采用 Flow Matching + Euler 积分(sampling_method='euler'),调度器由 transport/ 中的 sample_ode 驱动:
纯高斯噪声 z_T ──(第1步)──▶ 第2步 ──▶ … ──(第50步)──▶ 干净潜向量 z_0
▲ ▲ ▲
└─ Shape-DiT 每步预测"下一步往哪走"(速度场)
每一步中,管线用 Classifier-Free Guidance(CFG) 增强条件跟随:把"有条件"与"无条件"两份输入拼成双倍 batch 一起前向,再按 noise = uncond + guidance_scale × (cond − uncond) 放大条件差异,默认 guidance_scale=4.5(见 denoise_with_cfg)。无条件分支就是把 DINO 图像特征置零,而几何控制 token 始终保留——这解释了为什么控制信号比图像更"刚性"。
去噪完成后,z_0 除以 scale_factor 还原尺度,交给 Shape-VAE 解码出 512³ 八叉树网格,并经 FloaterRemover、DegenerateFaceRemover 后处理清理浮点与退化面(postprocessors.py),最终导出 GLB。
六、一键上手:从命令到 GLB
整个仓库只需约 10 GB 显存。安装依赖:
pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt
然后修改 inference.py 中 --save_dir、--repo_id 等参数后运行:
python3 inference.py --control_type bbox
python3 inference.py --control_type pose --use_ema
python3 inference.py --control_type point --flashvdm
四种 control_type 分别对应四类控制,演示数据在 demos/bbox/data.json、demos/pose/、demos/point/data.json、demos/voxel/data.json。三个实用开关:
--use_ema:加载 EMA 权重,输出更稳定;--flashvdm:启用 FlashVDM 快速解码,显著提速;num_inference_steps=50/octree_resolution=512/guidance_scale=4.5:步数、几何分辨率与引导强度的默认甜点值,可在 inference.py 中按需调整。
七、关键要点总结
- 潜空间是效率关键:3.3B 的 Shape-DiT 在 64 通道、固定长度的 latent token 上去噪,而非直接处理百万级点云,这是能单卡 10 GB 显存跑通的前提;
- 统一编码器 = 一个入口四种控制:所有几何模态都被归一化为"点坐标 + 类型 token",DINOv2 图像特征提供外观语义,两者在双流块中联合注意力交互;
- AdaLN + 时间嵌入让 Transformer 感知去噪进度,CFG 让生成结果更贴近条件;
- VAE 解码负责"从隐到显":八叉树 + Marching Cubes 把连续占用场变成可渲染网格,
octree_resolution直接决定细节上限。
沿着 inference.py → pipeline_generation_sit_omni.py → hunyuan3ddit.py 这条主线读源码,就能完整复现"条件编码 → 潜空间去噪 → 几何重建"的全过程。



