SUPRA-Tex训练工作流揭秘:从Pixal3D数据准备到Flow Matching补全训练
SUPRA-Tex训练工作流揭秘:从Pixal3D数据准备到Flow Matching补全训练
SUPRA-Tex 是一个从单张图片生成带 PBR 材质纹理的 3D 资产的项目,其核心训练由「数据准备 → 2D 材质预测 → 3D 材质补全」三段式工作流构成。本文完整拆解 SUPRA-Tex 的训练流程:如何沿 Pixal3D 范式准备多视角 PBR 数据、如何用 DiffSynth-Studio 微调 Qwen-Image-2.1 做材质预测、以及如何借鉴 TRELLIS.2 的稀疏潜空间与 Flow Matching 目标完成 3D 材质补全训练。
💡 需要说明的是:本仓库开源的是推理代码与预训练权重,训练流程在 docs/train.md 中以训练总览形式公开,供研究者复现与二次研究。
训练工作流全景:三段式架构
SUPRA-Tex 的训练工作流可以概括为三张「接力棒」:
| 阶段 | 职责 | 技术基础 |
|---|---|---|
| 1️⃣ 数据准备 | 从 PBR 资产生成对齐的 RGB、材质图与相机参数 | 沿用 Pixal3D 数据处理流程 |
| 2️⃣ 2D 材质预测 | 从参考图联合预测 albedo / metallic / roughness | DiffSynth-Studio + Qwen-Image-2.1 |
| 3️⃣ 3D 材质补全 | 将「可见区域材质」补全为完整 PBR 表面 | TRELLIS.2 稀疏潜空间 + Flow Matching |
2D 材质预测器与 3D 补全模型分开训练、推理时串联:先由图像预测材质,再编码为 3D 表面观测,最终补全成完整 PBR 材质。各阶段的实现位置可在 docs/method.md 的组件表中查到。
第一步:数据准备——完全遵循 Pixal3D 范式
训练数据的质量决定 3D 生成的上限。SUPRA-Tex 的数据处理流程与 Pixal3D 保持一致,链路如下:
- 从带 PBR 材质的 3D 资产出发,对资产做归一化(统一尺度与坐标系);
- 渲染多视角,得到对齐的 RGB 图像、材质图与相机参数;
- 使用预训练编码器,为几何和完整材质分别提取稀疏 3D 潜变量(sparse latent);
- 将参考视角的可见材质投影到物体表面,构建「部分材质观测」(partial material observation);
- 关键约束:几何、完整材质、部分观测三者必须共享同一 3D 坐标系。
这个「部分观测」概念正是 SUPRA-Tex 方法的核心:它告诉模型"这里已经确定了,别动",只让你补全看不见的区域。仓库中推理侧对应实现在 supratex/inference/native_observation.py,其中观测以稀疏坐标编码,每个观测携带 32 个潜变量通道加覆盖度与边界距离(共 34 通道)。
第二步:2D 材质预测——冻结骨干 + LoRA 适配
2D 材质预测阶段基于 DiffSynth-Studio 实现,以 Qwen-Image-2.1 为底座模型,从参考图像联合预测三张材质图:albedo(反照率)、metallic(金属度)、roughness(粗糙度)。
训练策略非常"轻",这也是它能高效适配的关键:
- 🧊 冻结预训练骨干,不从头训练大模型;
- 🎯 使用 LoRA + 可学习模态嵌入(learnable modality embeddings)适配材质预测任务;
- 📐 监督信号作用在潜空间(latent space)的材质输出上,数据为空间对齐的 RGB 图与材质图。
训练样本由仓库自带的示例输入格式体现得淋漓尽致,例如 assets/examples/pitcher_plant 目录同时保存了条件图 condition_rgba.png、几何 geometry.npz、相机 camera.json 以及预测出的 albedo.png 与 mra.png——这正是「空间对齐的 RGB 与材质图」训练对的具体形态。
第三步:Flow Matching 补全训练——3D 阶段的核心
3D 阶段沿用 TRELLIS.2 的稀疏潜空间表示与 Flow Matching 训练范式,并引入 SUPRA-Tex 自有的观测编码与 Interleaved Flow Transformer(交错流 Transformer)。训练过程拆解如下:
- 加噪:对完整材质潜变量添加噪声;
- 学习预测流速度(flow velocity):条件输入是几何潜变量 + 部分材质观测;
- 观测 token 全程固定:作为引导信号参与注意力,但不随去噪过程被更新——可见区域的细节因此被严格保留;
- 训练目标覆盖所有有效表面位置:模型既要"保住可见细节",又要"补全未见区域",两条能力同时被训练。
推理时,采样由 FlowEuler 完成(默认 25 步,rescale_t=3.0),实现见 supratex/pipelines/observation_guided_completion.py。
Interleaved Flow Transformer:偶数块与奇数块交错
这是 SUPRA-Tex 补全模型最有辨识度的设计。以 60 个 Transformer 块为例:
- 偶数块:只更新未观测的单元格(U-only);
- 奇数块:更新整个表面(full-X);
- 观测流 O 自始至终是只读的:它不参与 Q 投影、注意力输出与 MLP 计算,只向各层提供 K/V,让生成流持续"看得见"观测。
这套架构与推理默认配置记录在 configs/inference_model.json:num_blocks: 60、base_block_policy: "alternating_u_x"、潜空间分辨率 64、材质潜变量 32 通道。
归一化统计:训练与推理的一致性契约
补全训练学到的潜变量分布会沉淀为归一化统计量,随权重一起发布:
- configs/partial_normalization.json:部分观测潜变量的 32 维均值与标准差;
- 完整配置中同时包含
partial_mean/partial_std与pbr_mean/pbr_std。
推理加载器会严格校验检查点内的归一化 buffer 与配置是否一致,任何不匹配都会报错——这正是训练期统计量与推理期行为保持严格一致的一道保险。
外部依赖:训练工作流站在哪些肩膀上
SUPRA-Tex 的外部模型依赖在 configs/pipeline.json 的 external_models 中固定了版本,训练侧涉及的主要有:
| 外部模型 | 在训练/推理链路中的角色 |
|---|---|
| Qwen-Image-2.1 | 2D 材质预测的底座模型 |
| TRELLIS.2-4B 的四个 VAE | 形状/材质的稀疏 VAE 编解码 |
| Pixal3D | 数据准备范式与几何生成 |
| DINOv3 / NAF | 几何条件特征 |
第三方代码来源与许可证可查阅 THIRD_PARTY_NOTICES.md 与 deployment/runtime/SOURCE_PROVENANCE.json。
总结:训练到推理的完整闭环
SUPRA-Tex 的训练工作流设计哲学可以总结为一句话:"所见必保,未见必补"。
- Pixal3D 式数据准备保证了 RGB、材质、几何三者在同一坐标系下严格对齐;
- 冻结骨干 + LoRA 的 2D 材质适配,让大图像模型低成本学会输出 PBR 材质图;
- Flow Matching 训练中"固定观测 token + 全表面损失"的组合,教会 Interleaved Flow Transformer 在保留参考视角细节的同时,补全背面的金属度与粗糙度。
如果你想亲自体验这套训练流程的产出,最快的路径是:安装运行时(python scripts/install_runtime.py)→ 准备模型(python scripts/prepare_models.py)→ 运行自带示例(python scripts/run_example.py --output outputs/spiny_whelk_shell.glb),详见 docs/quickstart.md。



