PersonAnalysis 入门：人脸识别与身体 ReID
安装 InsightFace 2.1、选择 Cheetah 模型、登记参考照片，并通过 Python API 在图片或本地视频中匹配人员。
你将完成什么
PersonAnalysis 结合人体检测、人脸识别与身体重识别（ReID），将当前画面中的人员与您按姓名或编号登记的参考样本进行比较。
本指南从 CPU 推理开始，分别介绍特征提取、匹配和可选的身体参考更新。处理视频时应复用同一实例，让参考样本在各帧之间保持可用。
开始之前
- Python 3.10 或更新版本，建议使用虚拟环境。
- 仅含一张清晰人脸的 reference.jpg、场景图片 scene.jpg，以及您有权处理的短恒定帧率视频 clip.mp4。
- 首次下载模型所需的网络连接，或已在本地安装完整的 Cheetah 模型包。
1. 安装 InsightFace 2.1
在准备使用的 Python 环境中运行以下命令。基础包已包含 NumPy、OpenCV 和 CPU 版 ONNX Runtime；PersonAnalysis 无需安装 GUI 或 PrivateFrame 扩展。
如使用 NVIDIA CUDA，先安装 InsightFace，再将 onnxruntime 替换为 onnxruntime-gpu，并显式选择 CUDAExecutionProvider。具体步骤见运行环境指南。PersonAnalysis 支持 CPU 和 CUDA；Cheetah 不使用 CoreML。
python -m pip install --upgrade "insightface==2.1"
python -c "from insightface.app import PersonAnalysis; print(PersonAnalysis.__name__)"2. 选择 Cheetah 并准备模型文件
建议从 cheetah_s 开始：人体检测输入为 320×320，内置与 Buffalo S 相同的人脸检测和识别模型。cheetah_l 的人体检测输入为 640×640，使用 Buffalo L 的人脸模型。两者使用相同的身体 ReID 模型，人脸检测默认输入均为 640×640。
首次准备时会下载缺失的官方 Cheetah 包。离线使用时，从模型发布页下载完整压缩包，解压到 ~/.insightface/models/cheetah_s/ 或 cheetah_l/。manifest.json、MODEL.LICENSE 和四个 ONNX 文件必须放在同一层级，避免多套一层模型包目录。
- 本教程显式设置 name="cheetah_s"；Python 构造函数默认使用 cheetah_l。
- 已有模型包不完整或校验失败时会报错，不会自动覆盖；请使用完整压缩包修复。
3. 登记参考、提取特征并匹配
将图片示例保存为 person_image.py，与 reference.jpg 和 scene.jpg 放在同一目录，然后运行 python person_image.py。参考照片必须仅含一张可用人脸；继续前检查 accepted 与 rejected。person_001 是您指定的身份标签。
get() 接收已解码的 OpenCV BGR uint8 图片，返回当前画面的观测结果。match() 与参考样本比较，优先采用合格的人脸匹配，再尝试身体参考。两者都不改变参考库。
示例默认关闭 auto_update。启用后，update() 仅在可靠的人脸匹配及明确的人脸与身体关联成立时增加身体参考。仅靠身体匹配不会扩充参考，也不会自动创建新身份。请先匹配整帧，再统一更新。
import cv2
from insightface.app import PersonAnalysis
image = cv2.imread("scene.jpg")
if image is None:
raise FileNotFoundError("scene.jpg")
with PersonAnalysis(name="cheetah_s") as app:
registration = app.register("person_001", "reference.jpg")
if registration.accepted == 0:
raise ValueError(registration.rejected)
observations = app.get(image)
matches = app.match(observations)
for result in matches:
print(result.person_id, result.matched_by, result.similarity)
auto_update = False
if auto_update:
changes = app.update(matches)
print(changes.added, changes.replaced, changes.skipped)4. 处理视频时复用同一实例
将以下示例保存为 person_video.py，与 reference.jpg 和 clip.mp4 放在同一目录，运行 python person_video.py。本例启用可选的身体参考更新；将 auto_update 改为 False 即可关闭。
对于 30 FPS 的恒定帧率视频，analysis_fps=2 会每十五帧分析一次。所有帧仍会解码，只有采样帧进入模型。这是按视频时间设置的分析上限，不是处理速度承诺，也不会等待实际播放。可变帧率文件应使用真实时间戳。
本例按顺序读取。摄像头与 RTSP 可使用桌面工作流，保留最新待处理帧，并按经过的实际时间限制分析频率。
import math
import cv2
from insightface.app import PersonAnalysis
analysis_fps = 2
auto_update = True
capture = cv2.VideoCapture("clip.mp4")
try:
if not capture.isOpened():
raise OSError("clip.mp4")
source_fps = capture.get(cv2.CAP_PROP_FPS)
if not math.isfinite(source_fps) or source_fps <= 0:
raise ValueError("CAP_PROP_FPS")
frame_step = max(1, math.ceil(source_fps / analysis_fps))
with PersonAnalysis(name="cheetah_s") as app:
registration = app.register("person_001", "reference.jpg")
if registration.accepted == 0:
raise ValueError(registration.rejected)
frame_index = -1
while True:
ok, frame = capture.read()
if not ok:
if frame_index < 0:
raise OSError("clip.mp4")
break
frame_index += 1
if frame_index % frame_step:
continue
matches = app.match(app.get(frame))
if auto_update:
app.update(matches)
for result in matches:
print(frame_index / source_fps, result.to_dict())
finally:
capture.release()5. 理解结果并调整匹配
person_id 为登记的身份编号，未匹配时为 None。matched_by 为 face、body 或 None；similarity 是被接受匹配的余弦相似度，不是正确率。可从 result.observation 读取 body_bbox、reid_feature 和 face，使用前检查是否缺失。
仅登记人脸照片并不能提供衣着信息。可通过 body_images 登记身份已知的身体裁剪图，或让合格的人脸匹配增加身体参考。身体匹配会受衣着、姿态、遮挡和画质影响。
默认参数包括 face_similarity_threshold=0.45、reid_similarity_threshold=0.85、max_body_samples=4。创建新实例时通过 PersonConfig 修改，并用代表性素材评估；详见参数参考。默认值并不代表经过校准的准确率保证。
- 参考样本仅保存在当前实例内存中，关闭实例后释放；没有自动参考库导出、数据库或重启恢复。
- 结果描述当前帧。SDK 不维护连续轨迹、匿名身份、出现时长或事件历史。
- to_dict() 便于应用保存当前输出，但不是参考库备份，也不能作为 update() 的输入。
6. 体验桌面工作流
支持多语言的 Evaluation Studio 提供本地视频、摄像头和 RTSP 的人员分析，可添加参考照片并控制分析频率。安装下方 GUI 扩展，选择 Cheetah S 或 L，再按GUI 指南操作。
python -m pip install --upgrade "insightface[gui]==2.1"
insightface-gui7. 评估场景并确认模型许可
请覆盖清晰正脸、背影、相似衣着、遮挡和未登记者等情况。选择阈值前检查误匹配与漏匹配，并在计划使用的硬件和素材上测量处理速度。
SDK 代码使用 MIT 许可。公开的 Cheetah 预训练包为非商业授权；代码可商用不等于模型可直接商用。
进一步阅读完整 API 指南及模型许可说明。部署与模型授权请联系 InsightFace；功能与模型选择可查看人员分析概览。