InsightFace 人脸检测与识别上手指南：3 步装好，一图 6 张脸全框出，本地比对手把手跑通-编程实验室

InsightFace 人脸检测与识别上手指南：3 步装好，一图 6 张脸全框出，本地比对手把手跑通

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

InsightFace 是开源社区做 2D/3D 人脸分析的标杆工具箱：人脸检测与人脸识别一次调用出结果，顺带把关键点、性别年龄属性一并给到。它最擅长两类活儿——判断两张照片是否同一人（数据全程留在本机不上传），以及把一张大图里几十上百张脸自动框出、交给下游做裁剪或打码。下文用官方 Python 库，几分钟搭出一个本地比对 Demo，预训练权重自动下载，无需自己训练模型。

能力总览：检测、识别、对齐、属性一次调用

人脸检测：SCRFD 系列（0.5GF~34GF 多档），框出人脸并给 5 点 / 106 点关键点；
人脸识别：ArcFace 系列，输出 512 维 embedding；
对齐与属性：106/68 点标定，性别、年龄；
以上能力打包成buffalo_l等模型包，调一次FaceAnalysis全流程跑完。

安装与首次运行：两条命令加七行脚本

环境要求：Python 3.x 起步；仓库里的训练代码对应 PyTorch 1.6+ 或 MXNet 1.6~1.8。Python 库 0.2 之后推理后端换成 onnxruntime，CPU 场景装 onnxruntime 本体即可，GPU 需手动装 onnxruntime-gpu。

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

再跑一段 7 行最小脚本，用的是仓库自带示例图 t1.jpg：

import cv2 from insightface.app import FaceAnalysis app = FaceAnalysis(name='buffalo_l') app.prepare(ctx_id=-1) # -1 表示用 CPU img = cv2.imread('python-package/insightface/data/images/t1.jpg') faces = app.get(img) print(len(faces), faces[0].embedding.shape)

第一次运行时，库会自动拉取 buffalo_l 全套权重（约 326MB），缓存在~/.insightface/models/下，之后再跑就是本地加载。返回值是一个人脸对象列表，每个对象带边界框、5 点或 106 点关键点、性别年龄，外加一段 512 维的 embedding——相当于给每张脸发一个"脸部身份证号"，两张照片的号越接近，越可能是同一个人。

两个最常用的用法：批量框脸与 1:1 比对

批量框脸并绘制：app.get(img)返回图里全部人脸对象，继续传给app.draw_on(img, faces)，框线、关键点、属性文字即刻画好，cv2.imwrite存盘即可。示例图 t1.jpg 里正好 6 张脸，仓库里的 inswapper 交换 Demo 也拿它当输入，直接断言len(faces)==6。

1:1 同一人比对：两张图各取face.embedding，算一次余弦相似度，和阈值比大小即可定夺。仓库示例 examples/face_recognition/insightface_app.py 里默认阈值0.65：取低了容易误认、取高了容易漏认，请按自己的业务场景回测。一图多人时记得自己挑要比的那张脸，示例代码取的是第一张检出的人脸。

官方性能基准数据：SCRFD 检测指标与识别得分

下表是仓库公布的 SCRFD 各档检测数据，mAP 均在 640×480 的 VGA 档单尺度下测得：

检测模型	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

识别侧，默认包buffalo_l（配 SCRFD-10GF 检测 + ResNet50@WebFace600K 识别）在 MR-ALL 拿 91.25，LFW 99.83，IJB-C（E4）97.25；轻量包buffalo_s（SCRFD-500MF + MobileFaceNet）MR-ALL 只有 71.87，留给算力吃紧的设备。数据出处：detection/scrfd/README.md 与 model_zoo/README.md。

🎯 模型包怎么选：buffalo_l / buffalo_s / buffalo_sc

场景	推荐模型包	说明
精度优先（默认）	buffalo_l	326MB，检测+识别+对齐+属性全开
端侧 / 低配设备	buffalo_s	159MB，识别走 MobileFaceNet
只要检测 + 识别	buffalo_sc	16MB 最小，无对齐与属性

开工前必看的 4 件事

小脸怕漏检？prepare()默认按 128×128、640×640 双档输入分别检测，再统一走 NMS 合并去重；只有极致追速度时才把 input_size 写死。
GPU 别装错后端：onnxruntime 本体只带 CPU 推理；要跑 CUDA，需另装 onnxruntime-gpu，并给FaceAnalysis的 providers 参数填CUDAExecutionProvider。
阈值不是万能的：0.65只是示例默认值，建议拿业务里的真实坏例反复回测再定。
License 边界心里有数：代码走 MIT 协议，但 buffalo 系列预训练权重仅限非商业研究，商用必须另行授权，README.md 中交代得很清楚。