拆解sapiens2-normal-1b-bf16解码头:Pixel Shuffle上采样如何还原高分辨率人体法线

原创2026-10-19 23:20:23172 阅读

拆解sapiens2-normal-1b-bf16解码头:Pixel Shuffle上采样如何还原高分辨率人体法线

本文带你拆解 sapiens2-normal-1b-bf16 —— 它是 Meta 的 Sapiens2 人体表面法线估计模型(facebook/sapiens2-normal-1b,ICLR 2026 工作)的 bf16 精度 MLX 移植版本。给一张照片,它能输出与输入同分辨率的稠密法线场:画面中每个像素都带有一个三维单位向量,指示该处人体表面朝向。文章重点讲一件事:backbone 把分辨率压掉 16 倍之后,解码头如何用 Pixel Shuffle 上采样把高分辨率人体法线"找"回来。

先搞懂任务:什么是表面法线估计

💡 表面法线(surface normal)描述"表面在某一点朝哪个方向",是 3D 重建、渲染打光、人体姿态等任务的基础中间表示。

法线估计属于"稠密预测"任务:输入一张普通 RGB 照片,输出每个像素一个 3 通道向量。本模型的默认输入是 1024×768(高×宽,见 config.json 中的 image_size),输出也是 1024×768 的稠密法线图,且每个向量都归一化为单位长度。

仓库文件很精简,一共 5 个:

文件 作用
model.safetensors 全部权重,bf16 精度,约 3.08 GB(原始 float32 版本的一半)
model.safetensors.index.json 权重索引,列出约 540 个张量的名字
config.json 模型结构配置(backbone + decode_head)
preprocessor_config.json 图像预处理配置(缩放、归一化)
README.md 模型说明与使用方法

为什么需要上采样:patch 化让分辨率"消失"16 倍

理解解码头之前,先看 backbone 发生了什么:

  1. 输入图像 1024×768;
  2. backbone 用 16×16 的 patch(patch_size: 16)把图像切成小块,每个块变成一个 token;
  3. 于是特征图尺寸变为 64×48 —— 分辨率只剩原来的 1/16;
  4. 这 3072 个 token 经过 40 层 Transformer 块(hidden_size: 1536、24 个注意力头、中间 24 层用 GQA 分组查询注意力)逐层提炼语义。

到 backbone 出口时,每个 token 携带了非常丰富的"这里是什么"的信息,但空间细节只剩 64×48 的网格。要输出 1024×768 的法线图,就必须把特征图放大 16 倍 —— 这就是上采样的任务,也是本模型解码头存在的全部理由。

解码头全景:decode_head 的四段结构

从权重索引 model.safetensors.index.json 可以看到,decode_head 的权重只有寥寥十几个张量,结构非常干净:

backbone 输出 (1536 通道, 64×48)
    │
    ├─ input_conv      特征归一化 + 通道对齐
    │
    ├─ upsample_blocks 0~3   四个上采样块(3×3 卷积 + Pixel Shuffle)
    │                         通道逐级收窄:768 → 512 → 256 → 128
    │
    ├─ conv_layers     三组 3×3 细化卷积,通道 64 → 32 → 16
    │
    └─ conv_normal     1×1 卷积,输出 3 通道单位法线 (1024×768)

各段对应的配置(config.json 的 head_config):

  • use_pixel_shuffle: true:明确启用 Pixel Shuffle 上采样;
  • upsample_kernel_sizes: [3, 3, 3, 3]:4 个上采样块各用 3×3 卷积;
  • upsample_out_channels: [768, 512, 256, 128]:每个块之后的通道数;
  • conv_kernel_sizes: [3, 3, 3]、conv_out_channels: [64, 32, 16]:上采样完成后的细化卷积;
  • 最终由 conv_normal(1×1 卷积)把 16 通道压缩为 3 通道法线。

四个上采样块合计放大 16 倍,与 backbone 的 16×16 patch 下采样精确对消 —— 64×48 变回 1024×768,分辨率严丝合缝地回到输入尺寸。这也是 README.md 中"输出分辨率与输入一致"这一承诺的实现基础。

Pixel Shuffle 上采样原理:用"重排"代替"插值"

传统上采样靠插值(最近邻、双线性):新像素的取值是邻近旧像素的加权平均,容易发糊,且插值权重是人为规定的。

Pixel Shuffle(又称 Depth to Space)走的是另一条路:不做任何插值,只做张量重排。 分两步:

  1. 1×1 卷积扩通道:把 C 通道"翻倍式"地映射到 C×r² 通道(r 为上采样倍数)。网络自己学习每个输出位置该填什么;
  2. 空间重排:把这 r² 个通道组按规则铺到 r×r 的空间格子里,例如 r=2 时,同一输入像素产生的 4 组通道值恰好填成 2×2 的小方块。

打个比方 🏠:原来一栋楼(特征图)每层住 1 户,Pixel Shuffle 就是把每户拆成 4 间房,让家人住进楼里新盖出的 4 个格子 —— 楼变大了,但没有搬来任何"外面的人"(不引入插值误差),新住户是谁完全由网络学习决定。

这种做法的好处在法线任务上尤其明显:

  • 可学习:上采样行为是卷积学到的,比固定插值核更贴合人体表面的几何结构(衣服褶皱、发丝边缘);
  • 无插值伪影:避免双线性插值在强边缘处产生模糊,法线方向更锐利;
  • 省显存:不显式生成大图再卷积,重排操作本身零参数、零计算量。

配置里的关键数字:一条完整的分辨率账本

把 config.json 与 preprocessor_config.json 里的数字串起来,就是一条清晰的"分辨率账本":

阶段 分辨率 通道数 依据
输入图像(预处理后) 1024×768 3 size、image_size
patch 化(16×16) 64×48 1536 patch_size: 16、hidden_size: 1536
4 个上采样块(Pixel Shuffle) 64×48 → 1024×768 768→512→256→128 upsample_out_channels
细化卷积 ×3 1024×768 128→64→32→16 conv_out_channels
conv_normal 输出 1024×768 3(单位法线) 权重索引中的 decode_head.conv_normal

几个值得一提的细节:

  • 只取最后一层特征:out_features: ["stage40"]、out_indices: [40],backbone 的 40 层中只把最顶层输出交给解码头,信息提炼到底;
  • 输出前归一化:normalize_backbone_outputs: true,特征送入解码头前先做归一化,对应权重中的 decode_head.input_conv.0(LayerNorm);
  • 预处理固定:图像先缩放到 1024×768,再用 ImageNet 均值/方差([0.485, 0.456, 0.406] / [0.229, 0.224, 0.225])归一化,双线性重采样。

权重文件里能看到什么

model.safetensors.index.json 把全部张量分为两大家族:

  • backbone.blocks.0~39:40 层 Transformer 块,每层包含 wqkv(本仓库将 q/k/v 投影合并为一个张量,这是 mlx-vlm 的 Sapiens2 实现所期望的格式)、proj、门控 MLP 的 w12/w3、QK 归一化等;另有 patch_embed(16×16 切块投影)、rope_embed(RoPE 位置编码,rope_theta: 100)和 8 个 register token(storage_tokens);
  • decode_head.*:上文拆解的解码头,权重集中在 input_conv、upsample_blocks、conv_layers、conv_normal 四组。

全部参数均为 bfloat16,文件体积因此是官方 float32 检查点的一半(约 3.08 GB),且与 Sapiens2 官方混合精度推理(bf16)保持一致,精度损失可忽略。

如何在 MLX 上跑起来

仓库是模型权重,推理代码在 mlx-vlm 库中。安装后即可加载(详见 README.md):

pip install -U mlx-vlm
from mlx_vlm import load
from mlx_vlm.models.sapiens2.generate import Sapiens2Predictor, read_image

model, _ = load("mlx-community/sapiens2-normal-1b-bf16")
predictor = Sapiens2Predictor(model)
normals = predictor.infer(read_image("image.jpg"))["normals"]  # (H, W, 3),单位向量

如果你要克隆仓库到本地,地址是:https://gitcode.com/hf_mirrors/mlx-community/sapiens2-normal-1b-bf16。

小结

  • sapiens2-normal-1b-bf16 用 bf16 + MLX 在 Apple 芯片上跑 Sapiens2 逐像素法线估计,体积只有官方 float32 的一半;
  • backbone 以 16×16 patch 换取 1/16 分辨率的强语义 token,40 层 ViT 把"理解"做到极致;
  • 解码头用 4 个 Pixel Shuffle 上采样块(768→512→256→128 通道)把分辨率逐级还原 16 倍,再用三组 3×3 卷积细化、1×1 卷积输出 3 通道单位法线;
  • Pixel Shuffle"重排代替插值"的思路,让高分辨率人体法线的边缘保持锐利,是稠密几何任务上采样的经典答案。
登录后查看全文
sapiens2-normal-1b-bf16