sapiens2-pose-1b-bf16输入输出详解:boxes、flip_test与keypoints完整参考
sapiens2-pose-1b-bf16输入输出详解:boxes、flip_test与keypoints完整参考
sapiens2-pose-1b-bf16 是 Meta 公司 Sapiens2 人体姿态估计模型(1B 参数)的 MLX bf16 量化版本,可输出 308 个人体关键点。本文面向新手,完整讲解它的输入参数 boxes 与 flip_test、以及输出 keypoints 和 scores 的格式、形状与坐标含义,帮助你快速跑通推理。
🧭 先认识这个项目:它是什么?
这个项目是 mlx-community 对 facebook/sapiens2-pose-1b 的 MLX 格式转换,用于在 Apple Silicon 的 Metal 后端上高效推理。核心特性:
- bf16 混合精度:所有参数以 bfloat16 存储,文件体积约为原始 float32 检查点的一半,model.safetensors 约 3.04 GB;
- 308 关键点:覆盖人体全身的密集关键点(head、body、hands、face 等部位),属于 top-down(自顶向下)姿态估计,需要先用检测器框出人体;
- 权重已合并优化:每个 Transformer block 的 q/k/v 投影被合并为一个
wqkv张量,符合 mlx-vlm 的加载要求(详见 model.safetensors.index.json,共 536 个张量,分为backbone与decode_head两大部分)。
模型架构配置定义在 config.json 中:40 层 hidden、1536 维、24 个注意力头(部分层 12 个 KV 头,即 GQA),id2label 中的 LABEL_0 ~ LABEL_307 正好对应 308 个关键点的索引。
📥 输入详解(一):boxes 参数——告诉模型"人在哪里"
Sapiens2 是 top-down 姿态模型,它自己不检测人体,而是接收现成的人体框。boxes 参数用于指定每张图中各个人体区域:
| 项目 | 说明 |
|---|---|
| 形状 | (N, 4),N 为图中人体数量 |
| 格式 | xyxy,即每个框为 [左上角 x, 左上角 y, 右下角 x, 右下角 y] |
| 来源 | 由任意人体检测器(如 YOLO 等)输出的检测结果 |
| 默认值 | 不传时,默认把整张图当作一个人来估计 |
💡 新手提示:如果你的图片里只有一个人,完全可以不传 boxes;多人场景下则必须为每个人传一个框,模型会按顺序逐个输出姿态结果。
📥 输入详解(二):flip_test 参数——左右镜像测试开关
flip_test 是一个布尔值(True / False),用于水平翻转测试(flip testing):
- 开启后,推理时会把裁剪出的人体区域水平镜像一次,再额外推理一遍,然后取两次结果的对应关键点求平均;
- 它能提升关键点定位的稳定性,因为镜像后"左手/右手"会互换,平均可抵消单次预测的左右偏置;
- 对应的左右对称关键点索引映射定义在 config.json 的
flip_pairs字段中:共 146 组索引对,覆盖关键点 1 ~ 307(例如[1, 2]、[21, 42]),而 0 号关键点没有镜像对——它是位于身体中轴线上、镜像后位置不变的点(如头顶中点)。
一般用途是:追求最高精度时开启,追求速度或做批量筛查时关闭(False 省一次前向计算)。
📤 输出详解:keypoints 与 scores 的完整格式
调用 predictor.infer(...) 后返回一个字典,其中与姿态任务相关的两个核心输出:
| 输出键 | 形状 | 含义 |
|---|---|---|
keypoints |
(N, 308, 2) |
N 个人,每人 308 个关键点,每个关键点为 (x, y) 坐标 |
scores |
(N, 308) |
每个关键点的置信度,取值越高表示模型越确定 |
关于坐标的两个重要细节:
- 姿态输出位于"原图像素坐标系":即使内部预处理把图像缩放到了 1024×768(见 preprocessor_config.json 的
size字段),最终返回的 keypoints 已经映射回你输入原图的像素坐标,可直接用于绘制; - 按置信度过滤:实际使用时通常用
scores做阈值过滤(例如只保留 0.3 以上的点),再叠加到原图上,低分点往往对应被遮挡的部位。
🚀 快速上手:5 行代码跑通推理
完整用法见 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-pose-1b-bf16")
predictor = Sapiens2Predictor(model)
# boxes: (N, 4) 的 xyxy 人体框,来自检测器;不传则默认整张图
output = predictor.infer(read_image("image.jpg"), boxes=boxes, flip_test=False)
keypoints, scores = output["keypoints"], output["scores"] # (N, 308, 2), (N, 308)
📁 仓库文件结构速览
| 文件 | 作用 |
|---|---|
| README.md | 项目说明与使用示例 |
| config.json | 模型架构配置(40 层、308 关键点 id2label、146 组 flip_pairs) |
| preprocessor_config.json | 图像预处理:缩放到 1024×768、ImageNet 均值/方差归一化 |
| model.safetensors | bf16 权重,约 3.04 GB |
| model.safetensors.index.json | 536 个张量的名称→文件映射(backbone + decode_head) |
❓ 常见问题(FAQ)
Q1:不传 boxes 可以吗?
可以。默认对整个图像做姿态估计,适合"单人照片"场景;多人请传检测器给出的 (N, 4) 框。
Q2:输出的坐标需要我自己换算吗? 不需要。keypoints 已是原图像素坐标,可直接画在原图上。
Q3:为什么选 bf16 而不是 float32? bf16 与参考实现的混合精度推理一致,体积减半、Metal 后端效率更高,精度损失可忽略。
Q4:flip_test 会翻倍耗时吗?
开启后每个框需要多一次前向计算(镜像图再推理一遍),追求低延迟时可传 False。
Q5:308 个关键点都代表什么?
索引 0 ~ 307 由 config.json 的 id2label 一一对应,覆盖头部、躯干、四肢、手部与面部等密集点位;具体部位命名可参考原始模型卡片与 mlx-vlm 的 Sapiens2 文档。