InsightFace 人脸检测与 1:1 比对实战：5 分钟跑通本地人脸分析-平芜编程栈

InsightFace 人脸检测与 1:1 比对实战：5 分钟跑通本地人脸分析

【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface

InsightFace 是一个开源的 2D/3D 人脸分析项目，核心能力就两件事：在图片里找到每张人脸的位置（人脸检测），以及判断两张照片里的人是不是同一个人（人脸识别 1:1 比对）。检测与识别都基于预训练模型，不需要你自己训练，官方 Python 库首次运行时还会自动下载模型，数据全程留在本机、不出机器。下面从安装讲到第一次出结果，再讲清楚哪些参数值得调、哪些坑要避开。

InsightFace 到底是什么：一个打包好的人脸分析工具箱

InsightFace 把检测、识别、关键点对齐、属性分析四类模型打包成"模型包"，一次FaceAnalysis调用就能跑完整条流程。各能力对应的模型如下：

能力	包内模型	作用
人脸检测	SCRFD（ICLR-2022 论文提出的高效检测器）	框出每张脸的位置
人脸识别	ArcFace 系列（默认包用 ResNet50@WebFace600K）	产出 512 维人脸向量
对齐	2D 106 点 / 3D 68 点关键点模型	标出脸部关键点坐标
属性	性别年龄模型	输出性别与年龄段

四类全齐的包叫 buffalo_l，是当前默认包；另有更轻的 buffalo_s，以及只含检测加识别的 buffalo_sc，怎么选看下文问答。

安装 InsightFace 并拿到第一次结果：环境要求与最短脚本

环境要求只有一条：Python 3.x。唯一要注意的是推理后端——0.2 版本起换成了 onnxruntime：只用 CPU 就装onnxruntime；要跑 GPU 需自行安装onnxruntime-gpu，调用时再指定 CUDA 后端。

git clone https://gitcode.com/GitHub_Trending/in/insightface pip install -U insightface pip install onnxruntime

然后是最短可运行脚本。首次执行会把约 326MB 的 buffalo_l 包自动下载到~/.insightface/models/：

import cv2 from insightface.app import FaceAnalysis app = FaceAnalysis(name='buffalo_l') app.prepare(ctx_id=-1) # -1 表示用 CPU faces = app.get(cv2.imread('python-package/insightface/data/images/t1.jpg')) print(len(faces)) # 示例图里有 6 个人

跑完打印出 6，说明仓库自带的 t1.jpg 里六张脸全部被检出。

读懂输出：一个 Face 对象里都有什么

app.get(img)返回的是 Face 对象列表，每张脸一个。每个对象里装着四类信息。

bbox是人脸外接框，即"这张脸在图里的哪个位置"，做人脸裁剪或打码就靠它。kps是关键点坐标，默认包支持 2D 106 点和 3D 68 点，可以理解为脸的"骨架定位点"，点数越多，后续做 3D 重建就越准。性别与年龄是属性模型的直接输出。最后是embedding：一个 512 维浮点向量，这是识别比对的核心，作用像银行柜台的"密语编号"——同一人的两张照片会生成两个略有差别的编号，而不同人的编号相距很远，比对的就是这个距离。

想把结果画出来，把图与 faces 一起传给app.draw_on(img, faces)即可得到带框、关键点、属性文字的图，再cv2.imwrite存盘。

人脸 1:1 身份比对：余弦相似度与阈值怎么调

比对原理很直接：两张照片分别过一遍app.get，各取一个 embedding，算余弦相似度——两个向量夹角的余弦值，越接近 1 说明方向越一致——再和阈值比较。

官方示例 examples/face_recognition/insightface_app.py 默认阈值取0.65，并明确提示要按业务调整。调参逻辑不复杂：想少"误认"（把陌生人认成目标），就调高阈值；想少"漏认"（同一人没认出来），就调低。最稳的做法是攒一批业务里的真实坏例——该拒的、该过的各来一些，来回调到两边都能接受。另外，一图多人时你得自己决定比哪张脸，示例的处理是直接取第一张检出的人脸。

人脸检测精度与速度实测：怎么选档位

检测侧全部是 SCRFD（一种高精度轻量级检测器）。下表为官方公布的 WIDERFace 单尺度 mAP，在 VGA（640×480）分辨率下测得，出处 detection/scrfd/README.md：

模型	Easy mAP	Medium mAP	Hard mAP	参数量 (M)	推理耗时 (ms)
SCRFD-0.5GF	90.57	88.12	68.51	0.57	3.6
SCRFD-2.5GF	93.78	92.16	77.87	0.67	4.2
SCRFD-10GF	95.16	93.87	83.05	3.86	4.9
SCRFD-34GF	96.06	94.92	85.29	9.80	11.7

取舍一目了然：0.5GF 到 34GF 在 Hard 档拉开 16 分以上，耗时约 3 倍。识别侧，默认的 buffalo_l（SCRFD-10GF + ResNet50）在 MR-ALL 上 91.25、LFW 99.83、IJB-C(E4) 97.25；轻量包 buffalo_s（SCRFD-500MF + MobileFaceNet）MR-ALL 为 71.87，算力受限的场景选它不亏。

常见问题：模型包怎么选、GPU 怎么开

问：buffalo_l、buffalo_s、buffalo_sc 到底选哪个？答：追求精度用默认的 buffalo_l；端侧或低配设备选 buffalo_s（159MB）；只要检测和识别、不要对齐与属性，16MB 的 buffalo_sc 最小。完整参数对照见 model_zoo/README.md 💡

问：图片里的小脸总是漏检，怎么办？答：v1.0 起prepare()默认是 Auto 模式，会先按 128×128 和 640×640 两档尺寸各跑一遍检测，再统一 NMS（合并重叠框的去重步骤）出结果，大小脸都能覆盖；追求速度时才改成固定 input_size。

问：怎么启用 GPU 加速？答：onnxruntime只含 CPU 推理。跑 CUDA 要先装onnxruntime-gpu，在FaceAnalysis里传providers=['CUDAExecutionProvider']，并把prepare的ctx_id从 -1 改成 0。

问：模型下载失败或太慢？答：也可以手动下载 zip 包，解压到~/.insightface/models/后再运行程序，效果等同。

问：可以商用吗？答：代码本身是 MIT 协议，学术商用均可；但附带的预训练模型（含 buffalo 系列）仅限非商业研究，商用需另行获取授权，README.md 里写得很清楚。