揭秘SUPRA-Tex材质适配器:Qwen-Image-2.1如何联合预测PBR材质
揭秘SUPRA-Tex材质适配器:Qwen-Image-2.1如何联合预测PBR材质
SUPRA-Tex 的材质适配器(Material Adapter)是整条"单图生成 3D 资产"流水线的第一步:它基于 Qwen-Image-2.1 图像大模型,通过 LoRA 微调 + 模态嵌入,从一张参考图联合预测出 PBR 材质——反照率(albedo)与金属度/粗糙度(metallic/roughness)贴图,再交给 3D 补全模型完成未见区域,最终输出可重光照的 GLB 资产。下面带你拆解它的预测机制、推理细节和运行方式。
一、材质适配器是 SUPRA-Tex 流水线的"第一步" 🧭
SUPRA-Tex 的完整流程是:前景提取 → MoGe-2 相机估计 → 材质预测(本适配器) → 表面观察编码 → Interleaved Flow Transformer 补全 → 导出 GLB。材质适配器负责"图像到材质的翻译"(Image-to-Material Translation):给定参考视图的 RGBA 前景图,一次性输出与图像逐像素对齐的两张 PBR 材质图。这些 2D 材质随后被投影到 3D 表面作为"观察",引导补全模型生成全表面材质,方法总览见 docs/method.md。
二、如何从一张图联合预测 PBR 材质:输入与输出 🖼️
以仓库内置的捕蝇草示例(assets/examples/pitcher_plant/)为例,输入是一张带前景 alpha 的参考图:
输出永远是一对 1024×1024 的贴图:
albedo.png:反照率贴图(sRGB),前景保留物体固有色,无覆盖的背景区域用品红色占位;mra.png:MRA 打包贴图,R 通道=金属度、G 通道=粗糙度(均为线性 0–255),B 通道=前景覆盖。
注意:适配器不预测法线和 AO——它只负责"参考视图看到了什么材质",几何与背面交给后续阶段。
三、Qwen-Image-2.1 联合预测的三大架构设计 🔬
1. 共享噪声流的"模态组"
联合预测的核心在 qwen_image_21_pbr.py:QwenImage21PBRModel 把 albedo 和 MRA 两路目标 latent 折进同一个噪声目标组(shared noisy target group),并为每种模态加上可学习的模态嵌入 modality_embeddings。条件侧(输入图像 latent + 文本提示嵌入)是共享且干净的,两路目标在一次前向中同时去噪——因此两张贴图天然像素对齐,不会出现颜色图与粗糙度图"对不上"的问题。
2. 注意力层 LoRA + 模态嵌入:只学 33.6M 参数
适配器没有重训整个基座,而是在 Qwen-Image-2.1 的 32 层 DiT 的注意力投影(attn.to_q/to_k/to_v/to_out.0)上注入 LoRA(默认 rank/alpha 均为 32),并加入模态嵌入,可训练参数仅 33.6M。基座模型(transformer、text_encoder、vae、processor)完整保留,默认值定义见 inference_utils.py。
3. 一步"端点预测",无需多步采样
推理采用端点预测(endpoint prediction):模型只在 sigma=1(timestep=1000)处预测一次速度场,用 噪声 − 速度 直接得到干净 latent(见 infer.py 的 predict)。没有多步迭代、没有 CFG 引导,单张图像材质预测只需一次前向,速度非常快。
四、推理时固定了哪些参数 ⚙️
为保证可复现,适配器把推理契约全部钉死(adapter_config.json 会逐字段校验):
| 参数 | 固定值 | 说明 |
|---|---|---|
| 分辨率 | 1024×1024 | 方形画布,LANCZOS 一次缩放,不裁剪 |
| 随机种子 | 42 | 确定性端点噪声 |
| 采样 | 1 步端点预测 | sigma=1,无 CFG |
| 注意力 | torch | 基座注意力后端 |
| 提示词 | 固定英文指令 | 见下方引用 |
固定提示词定义在 inference_utils.py:
"Generate aligned albedo and metallic/roughness material maps for the object in the input image. Pack MRA with red=metallic, green=roughness, and blue=constant one placeholder. No observed ambient occlusion is available."
此外,输入 RGB 通道保持直线(straight)色彩、不做 alpha 预乘;alpha 只表示覆盖,不推断材质透明度。前端运行器 supratex/frontend/qwen_image.py 还会把原生 MRA 的蓝色占位通道替换为输入覆盖,生成规范 albedo.png/mra.png 供 3D 阶段消费。
五、从 2D 材质贴图到可重光照 3D 资产 🧊
金属度与粗糙度决定了资产在新光照下的表现:
适配器输出的两张贴图会进入"原生观察编码":可见像素被投影到表面,每个观察携带 32 通道材质 latent + 覆盖 + 边界距离(共 34 通道);Interleaved Flow Transformer 以这些观察为键值补全整张表面,最终烘焙成带 base color / metallic / roughness 的可重光照 GLB。输入格式与参数见 docs/texturing.md,前端全流程见 docs/frontend.md。
💡 仓库还内置了 FireRed 后端作为替代:它用"模态轴联合注意力"同时预测 albedo、MRA 与法线三种模态(另一套因子化实现,见 supratex/frontend/material_model/),默认后端仍是 Qwen-Image-2.1。
六、如何运行材质推理与关键文件清单 🚀
模型准备后(python scripts/prepare_models.py),从仓库根目录运行前端流水线:
python -m supratex.frontend.pipeline --input input.png --output work \
--material-base ckpts/ready/external/qwen-base \
--material-model ckpts/ready/project/material
产物目录包含 albedo.png、mra.png、condition_rgba.png、camera.json 等交接文件。若只想单独跑材质推理,可直接调用原生入口(完整命令见 deployment/runtime/qwen/examples/qwen_image_21/pbr/README.md):
python deployment/runtime/qwen/examples/qwen_image_21/pbr/infer.py \
--checkpoint /path/to/material/adapter_model.safetensors \
--model-root /path/to/Qwen-Image-2.1 \
--input /path/to/condition_rgba.png --output-dir outputs/material
关键文件速查:
| 文件 | 作用 |
|---|---|
| deployment/runtime/qwen/examples/qwen_image_21/pbr/infer.py | 材质推理主入口(加载校验 + 单步预测) |
| deployment/runtime/qwen/examples/qwen_image_21/pbr/inference_utils.py | 固定提示词、LoRA 注入与 VAE 解码 |
| deployment/runtime/qwen/diffsynth/pipelines/qwen_image_21_pbr.py | 共享噪声目标组与模态嵌入 |
| supratex/frontend/qwen_image.py | 适配器校验与原生输出到规范 MRA 的转换 |
| docs/frontend.md / docs/method.md | 前端交接格式与流水线方法总览 |
小结
SUPRA-Tex 材质适配器用极小的代价(33.6M LoRA + 模态嵌入)把 Qwen-Image-2.1 改造成了 PBR 材质"翻译器":共享噪声流保证对齐、模态嵌入区分通道、一步端点预测保证速度。一次前向即可从单张参考图得到对齐的 albedo 与 metallic/roughness 贴图,为后续 3D 补全铺好"超级对齐"的地基。





