揭秘SUPRA-Tex材质适配器:Qwen-Image-2.1如何联合预测PBR材质

原创2026-11-12 10:27:541,652 阅读

揭秘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。

SUPRA-Tex 单图生成 3D 资产效果预览:材质适配器与补全模型协作输出带 PBR 贴图的 3D 模型

二、如何从一张图联合预测 PBR 材质:输入与输出 🖼️

以仓库内置的捕蝇草示例(assets/examples/pitcher_plant/)为例,输入是一张带前景 alpha 的参考图:

SUPRA-Tex 材质适配器输入:捕蝇草参考图 condition_rgba,Qwen-Image-2.1 据此联合预测 PBR 材质

输出永远是一对 1024×1024 的贴图:

  • albedo.png:反照率贴图(sRGB),前景保留物体固有色,无覆盖的背景区域用品红色占位;
  • mra.png:MRA 打包贴图,R 通道=金属度、G 通道=粗糙度(均为线性 0–255),B 通道=前景覆盖。

Qwen-Image-2.1 材质适配器联合预测输出的反照率贴图 albedo.png:捕蝇草 PBR 材质的固有色

Qwen-Image-2.1 联合预测输出的 MRA 贴图:金属度/粗糙度/覆盖打包,植物低金属度高粗糙区域呈青色

注意:适配器不预测法线和 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 资产 🧊

金属度与粗糙度决定了资产在新光照下的表现:

SUPRA-Tex 材质预测示例:锤纹铜罐的高金属度 PBR 材质在新光照下呈现真实金属反射

SUPRA-Tex 材质预测示例:青瓷笔洗的低金属度与釉面粗糙度共同决定高光形状

适配器输出的两张贴图会进入"原生观察编码":可见像素被投影到表面,每个观察携带 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 补全铺好"超级对齐"的地基。

登录后查看全文
SUPRA-Tex