如何读懂Sapiens2-pose-0.4b-bf16的输出?keypoints、scores与flip_test技巧详解
如何读懂Sapiens2-pose-0.4b-bf16的输出?keypoints、scores与flip_test技巧详解
sapiens2-pose-0.4b-bf16 是 Meta Sapiens2 人体姿态估计模型的 MLX bf16 转换版,可对图中每个人输出 keypoints(308 个关键点坐标)与 scores(关键点置信度)。本文带你快速读懂这两个核心输出,并讲清 flip_test 在什么场景下值得开启。
1. 这个模型是做什么的?一分钟了解
Sapiens2-pose-0.4b-bf16 是一个 top-down(自顶向下)人体姿态估计模型,为 MLX 框架转换,权重文件约 0.85 GB(bfloat16,体积约为原版 float32 的一半)。
- 输入:人物检测框
boxes(xyxy 格式),不传则默认整张图 - 输出:每人 308 个关键点及其置信度,覆盖头面、手部、躯干等部位,比传统 17 关键点骨架更细粒度
- 运行方式:通过
mlx-vlm在 Apple Silicon 上推理,支持flip_test测试时增强
仓库文件速览:
| 文件 | 作用 |
|---|---|
| README.md | 模型说明与最小用法示例 |
| config.json | 模型配置,含 308 关键点左右镜像对 flip_pairs |
| preprocessor_config.json | 预处理参数:输入分辨率 1024×768、归一化均值/标准差 |
| model.safetensors | bf16 模型权重(约 0.85 GB) |
| model.safetensors.index.json | 权重索引,共 328 个张量及其归属文件 |
2. keypoints:一组 (N, 308, 2) 的像素坐标
调用 predictor.infer() 会返回一个字典,keypoints 是其中最常用的输出:
- 形状为
(N, 308, 2):N 个人、每人 308 个关键点、每个关键点是一对(x, y) - 坐标已是原图像素坐标系:框架内部把裁剪图缩放到 1024×768 推理(见 preprocessor_config.json 的
Sapiens2ImageProcessor),但 pose 任务的结果会自动映射回源图像素坐标,无需手动换算,可直接用于绘制
实用技巧:308 个点属于密集关键点(dense keypoints),如果只需要展示粗略骨架,可按索引挑选你关心的子集来画,视觉上更干净。完整示例见 README.md。
3. scores:逐点置信度,用来过滤"不可靠的点"
scores 形状为 (N, 308),与 keypoints 一一对应,表示模型对每个关键点定位正确的把握程度(数值越高越可靠)。
常见用法:
- 阈值过滤:只绘制
scores > 0.3(或 0.5)的关键点,骨架更清爽 - 质量粗判:某人所有点的分数整体偏低时,通常是遮挡严重、框不准或模糊,可据此降低对该结果的信任
- 加权可视化:把 score 映射为点的大小或透明度,一眼看出哪些点可信
💡 遮挡、出框、模糊部位是低分高发区,不建议不加筛选地渲染全部 308 个点。
4. boxes 参数:怎么传人物框
boxes 为 (N, 4) 的 xyxy 人物框(左上 x、y,右下 x、y),一般由上游行人检测器提供:
- 传入 boxes:逐框裁剪并推理,得到 N 组输出
- 不传(默认):整张图当作一个人裁剪处理,输出
(1, 308, 2)
注意:top-down 模型对裁剪质量敏感,框太小或一个框里套了两个人,都会拉低 scores。
5. flip_test 技巧:水平翻转为什么让结果更稳
flip_test 是一个经典的测试时增强(TTA):把图像左右翻转 → 再推理一次 → 将结果翻回原坐标系 → 与原图结果合并(通常取平均)。
它的价值在于:
- 人体大体左右对称,模型对某一侧的判断常更有把握;两次结果平均后,对称部位的关键点更居中、更稳定
- 关键点的镜像映射由 config.json 中的
flip_pairs定义,例如[1, 2]表示关键点 1 与 2 互为左右镜像对,翻转后两点的结果会相应交换;位于身体中线的点(如索引 0)没有镜像对,保持原位 - 代价是约 2 倍计算量,README 示例默认传
flip_test=False(见 README.md)
推荐策略:离线精修、单图分析时开启,追求速度(视频流、批处理)时关闭。
6. 最小可运行示例
安装依赖并运行(完整说明见 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-0.4b-bf16")
predictor = Sapiens2Predictor(model)
# boxes: (N, 4) xyxy 人物框;不传则默认整张图
output = predictor.infer(read_image("image.jpg"), boxes=boxes, flip_test=True)
keypoints, scores = output["keypoints"], output["scores"] # (N, 308, 2), (N, 308)
如需获取仓库内容,可执行 git clone https://gitcode.com/hf_mirrors/mlx-community/sapiens2-pose-0.4b-bf16。
7. 常见问题
Q:为什么 keypoints 不是 1024×768 坐标系? A:1024×768 只是内部预处理输入分辨率(preprocessor_config.json),pose 任务的输出已自动映射回原图像素坐标。
Q:308 个关键点有什么用? A:相比传统 17 点骨架,308 点覆盖更细的身体部位,适合精细分析;展示时只取需要的子集即可。
Q:flip_test 什么时候开? A:单图精细分析建议开启以提升稳定性;批量实时场景关闭以省一半推理时间。