揭秘sapiens2-normal-1b-bf16:float32到bf16的MLX模型转换与wqkv权重合并细节
揭秘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 上快速实验人体法线估计与三维重建,这就是最省事的起点。🚀