揭秘sapiens2-normal-1b-bf16:float32到bf16的MLX模型转换与wqkv权重合并细节

原创2026-10-19 15:28:201,911 阅读

揭秘sapiens2-normal-1b-bf16:float32到bf16的MLX模型转换与wqkv权重合并细节

sapiens2-normal-1b-bf16 是 Meta 开源视觉模型 Sapiens2(ICLR 2026)的 bf16 精度 MLX 转换版,专用于逐像素表面法线估计。它通过 mlx-vlm 0.7.0 将原始 float32 检查点转为 bfloat16,文件体积直接减半,并完成了 q/k/v 权重到 wqkv 的合并,是 Apple Silicon 上快速部署人体感知任务的理想选择。🍎

它是什么:Sapiens2 法线估计模型

简单来说,sapiens2-normal-1b-bf16 是一个人体中心(human-centric)视觉模型,输入一张图片,输出每个像素的表面法线(surface normal)——即图像中每个点对着"朝哪个方向"的单位向量,形状为 (H, W, 3) 且长度为 1。

这项能力是三维人体理解的基础,广泛应用于:

  • 🧍 人体姿态与形状重建
  • 📐 三维重建与数字人
  • 🎮 游戏、XR 与虚拟试衣

该仓库是 facebook/sapiens2-normal-1b 官方模型的 MLX 移植版,模型架构为 Sapiens2ForNormalEstimation,许可证为 sapiens2-license。

为什么要从 float32 转到 bf16

这是本仓库最核心的一步转换,带来三个直接收益:

对比项 float32 原版 bf16 MLX 版
每个参数字节数 4 字节 2 字节
文件体积 约 6.16 GB 3.08 GB(减半)
推理精度损失 基准 可忽略(官方参考实现本身就是 bf16 混合精度推理)

💡 关键点:Sapiens2 的官方参考实现就在 bf16 混合精度下推理,所以这次转换几乎无损——不是"牺牲精度换体积",而是"回到模型原本的工作状态"。

转换后的 model.safetensors(3.08 GB)内所有 544 个张量全部为 bfloat16 格式,配合 MLX 框架可在 Apple M 系列芯片上获得显著的内存与带宽优势。

wqkv 权重合并细节:q/k/v 如何合而为一

打开 model.safetensors.index.json 可以看到每个 block 的注意力权重都被合并了。以第 0 层为例:

"backbone.blocks.0.attn.wqkv.weight": "model.safetensors",
"backbone.blocks.0.attn.wqkv.bias": "model.safetensors"

在原始检查点中,Query、Key、Value 分别是三块独立权重(wq / wk / wv)。mlx-vlm 的 Sapiens2 实现期望每个 block 只有一块合并后的 wqkv 大矩阵——把三块权重按行拼接成一个张量,一次矩阵乘法即可完成三种投影,减少内核调用次数、提升访存效率。

合并后的规模一览:

  • 📦 骨干网络共 40 个 Transformer block
  • 🧩 每层 1 个 wqkv.weight + 1 个 wqkv.bias,合计 80 个 wqkv 张量
  • 📊 全模型共 544 个张量(backbone 526 个 + decode_head 18 个)

同理,FFN 部分也做了合并:门控 MLP 的两路投影合成 w12,另一路为 w3。

config.json 关键参数速览

config.json 记录了模型结构,几个值得关注的参数:

参数 值 含义
hidden_size 1536 隐藏层维度
num_hidden_layers 40 Transformer 层数
num_attention_heads 24 Query 头数
num_key_value_attention_heads 12 KV 头数(GQA 分组注意力,2 个 Q 头共享 1 组 KV)
intermediate_size 6144 FFN 中间维度
patch_size 16 ViT 分块大小
rope_theta 100.0 旋转位置编码基频
use_qk_norm true 启用 Q/K 归一化(注意力更稳定)
use_gated_mlp true 门控 FFN
image_size [1024, 768] 训练输入分辨率

前 8 层与后 8 层使用全注意力头(24 KV 头),中间 24 层压缩为 12 个 KV 头,这种设计在保证精度的同时控制了显存开销。🔍

如何用 mlx-vlm 三步跑通推理

安装与使用都非常简单,完整说明见 README.md:

第一步,安装最新 mlx-vlm:

pip install -U mlx-vlm

第二步,加载模型并预测法线(约 7 行代码):

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), unit length

第三步,拿到 numpy 数组 normals,形状与输入分辨率一致(稠密任务输出原分辨率),即可用于下游三维重建。

图像预处理参数(ImageNet 均值/标准差归一化、缩放至 1024×768)由 preprocessor_config.json 定义,加载时自动生效。

仓库文件清单

本仓库结构极其简洁,只有 5 个文件:

文件 说明
README.md 模型卡:转换说明、用法示例
config.json 模型架构与超参数配置
model.safetensors bf16 权重文件(3.08 GB,wqkv 已合并)
model.safetensors.index.json 544 个张量的名称映射索引
preprocessor_config.json 图像预处理参数(Sapiens2ImageProcessor)

常见问题 FAQ

Q:bf16 会不会明显降低精度? A:不会。官方参考实现本身就运行在 bf16 混合精度下,本次转换是让 MLX 版本回归到模型的原生精度状态。

Q:wqkv 合并后会影响加载其他框架吗? A:这个合并是为 mlx-vlm 的 Sapiens2 实现定制的,请搭配 mlx-vlm 0.7.0+ 使用;PyTorch 原版应使用 facebook/sapiens2-normal-1b 原始检查点。

Q:非 Apple 设备能用吗? A:模型本身可以加载,但本仓库的目标是 MLX 生态,NVIDIA GPU 用户建议直接使用原始 float32/bf16 检查点。

Q:模型输出可以直接可视化吗? A:可以。normals 是 (H, W, 3) 的单位向量数组,乘 127.5 加 127.5 转 uint8 即可渲染成 RGB 法线图。

小结

sapiens2-normal-1b-bf16 用两个动作完成了从"研究检查点"到"Apple Silicon 可用"的跨越:float32 → bf16 让体积减半且零损失,q/k/v → wqkv 让推理更高效。如果你想在 Mac 上快速实验人体法线估计与三维重建,这就是最省事的起点。🚀

登录后查看全文
sapiens2-normal-1b-bf16