Hunyuan3D-Omni Shape-DiT 剖析:3.3B 三维扩散 Transformer 如何从潜空间去噪到几何网格

原创2026-11-07 16:53:15555 阅读
文章标签:人工智能深度学习计算机视觉多模态3D建模媒体生成

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 多模态控制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 抽取网格。

Hunyuan3D-Omni 整体框架图

二、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:

  1. 图像分支:用 DINOv2 提取图像的 patch 特征(last_hidden_state),承载"长什么样";
  2. 几何分支:控制信号(骨骼点/边界框/体素/点云坐标)先经 Fourier 位置编码(FourierEmbedder),再过线性层+RMSNorm+GELU 投影到 1024 维;
  3. 类型标记:每种控制类型分配一个可学习的 embedding 编号(pose=0、bbox=1、voxel=2、point=3),重复 10 次作为"控制信号 token",让 DiT 明确知道自己收到的控制类型。

一个巧妙的细节:体素控制会先把输入点云量化到 16³ 网格(generate_voxel),去重后取每个体素中心作为控制点;边界框则先展开为 8 个角点(bbox_to_corners)。这保证了不同模态在统一的"点坐标"语义下进入同一套编码流程。

bbox 控制示例:由边界框约束生成的 3D 家具模型

四、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)分四步:

  1. 潜向量投影:latent_in 把 64 维潜 token 投影到 1024 维;
  2. 时间嵌入:去噪步长 t 经正弦编码 + MLP 得到 vec,通过 AdaLN 调制(shift/scale/gate)注入每一层——这是扩散模型"知道当前该去噪多少"的机制;
  3. 16 层双流块:图像流与条件流(DINO 特征 + 控制 token)各自做归一化与调制后,拼接 q/k/v 做联合自注意力,实现条件与潜变量的双向信息交换(DoubleStreamBlock);
  4. 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 中按需调整。

姿态控制示例:骨骼点控制生成 3D 人物

七、关键要点总结

  1. 潜空间是效率关键:3.3B 的 Shape-DiT 在 64 通道、固定长度的 latent token 上去噪,而非直接处理百万级点云,这是能单卡 10 GB 显存跑通的前提;
  2. 统一编码器 = 一个入口四种控制:所有几何模态都被归一化为"点坐标 + 类型 token",DINOv2 图像特征提供外观语义,两者在双流块中联合注意力交互;
  3. AdaLN + 时间嵌入让 Transformer 感知去噪进度,CFG 让生成结果更贴近条件;
  4. VAE 解码负责"从隐到显":八叉树 + Marching Cubes 把连续占用场变成可渲染网格,octree_resolution 直接决定细节上限。

沿着 inference.py → pipeline_generation_sit_omni.py → hunyuan3ddit.py 这条主线读源码,就能完整复现"条件编码 → 潜空间去噪 → 几何重建"的全过程。

登录后查看全文
Hunyuan3D-Omni