InsightFace 人脸检测与人脸识别完整指南：Python 库跑通本地 1:1 比对

InsightFace 人脸检测与人脸识别完整指南：Python 库跑通本地 1:1 比对

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

想让一张图告诉你"这张图里有几张脸、在哪里"，或者想回答"这两张照片是不是同一个人"，InsightFace 的 Python 库几行代码就能完成。它背后的 2D/3D 人脸分析链路（人脸检测、人脸识别、关键点对齐、性别年龄属性）被封装进一个FaceAnalysis接口：装好包、跑一次app.get(img)，每张脸就带出了边界框、关键点、属性和一根 512 维的 embedding 向量——可以理解为这张脸的"数字指纹"。全程数据不离开本机，预训练模型首次运行自动下载。

先给结论：如果你的需求是本地人脸比对、批量人脸检测或相册整理，直接用 Python 库即可；如果已经需要 Web 界面、REST API 或 1:N 人脸搜索服务，仓库里的 InsightFace Server 是一个单容器方案；如果是要训练新检测器或识别模型，仓库同时提供了 SCRFD、ArcFace 的训练代码。

安装前先看这张表：5 个模型包按体积和精度怎么选

模型包（model pack）= 检测 + 识别 + 对齐 + 属性几类 ONNX 模型打成一个 zip，解压到~/.insightface/models/就能用。默认包是buffalo_l，也是唯一能自动下载的包，其余需要手动下载 zip 再解压（完整列表见 python-package/README.md）：

识别侧精度（MegaFace MR-ALL，gallery=1e6；LFW；IJB-C(E4)）：buffalo_l 为 91.25 / 99.83 / 97.25，buffalo_s 为 71.87 / 99.70 / 95.02，buffalo_m、buffalo_sc 分别与 l、s 同精度。

选择逻辑一句话：桌面/服务端选 buffalo_l；端侧或低配机器选 buffalo_s；只要框和 embedding、不要对齐和属性的极简场景，16MB 的 buffalo_sc 足够。

安装 insightface，30 秒确认人脸检测生效

环境要求：Python 3.x。推理后端从 0.2 版本起改用 onnxruntime——只用 CPU 装onnxruntime，要 GPU 推理则手动装onnxruntime-gpu。仓库训练模块基于 PyTorch 1.6+ 和 MXNet 1.6~1.8（README.md）。

git clone https://gitcode.com/GitHub_Trending/in/insightface pip install -U insightface pip install onnxruntime # 要 GPU 改为 onnxruntime-gpu

验证脚本，用仓库自带的示例图（首次运行自动下载 buffalo_l 约 326MB）：

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

app.get返回 Face 对象列表：每个对象有bbox（边界框）、det_score（检测置信度）、kps（5 点关键点）、gender/age、embedding（512 维识别向量）。示例图里有 6 张脸，仓库人脸交换例子正是用它并断言len(faces)==6。把结果交给app.draw_on(img, faces)可画出框、关键点和属性文字。

prepare()有个值得知道的默认行为：v1.0 起检测尺寸默认 Auto，即 SCRFD 先在 128×128 和 640×640 两档分别检测，再做统一 NMS 合并（见 face_analysis.py 的DEFAULT_DET_SIZES），小脸和大图都不容易漏。

1:1 比对链路：用 embedding 向量判断是否同一人

流程固定：对每张照片取face.embedding，算余弦相似度，和阈值比大小。仓库示例 examples/face_recognition/insightface_app.py 默认阈值取 0.65，注释里明确写了要按你的业务场景调整：

import numpy as np emb1, emb2 = face1.embedding, face2.embedding score = np.dot(emb1, emb2) / (np.linalg.norm(emb1) * np.linalg.norm(emb2)) print(score, score > 0.65) # 相似度与判定结果

一图多人的坑：示例默认取faces[0]，但第一张检出的脸未必是你想比的那张。仓库 inswapper_main.py 的做法是按框左边缘排序再取：faces = sorted(faces, key=lambda x: x.bbox[0])，你可以照抄这个思路。

检测精度与推理速度：SCRFD 性能数据拆解

检测模型是 SCRFD（ICLR 2022），下表 mAP 均在 VGA（640×480）单尺度下测得，出处 detection/scrfd/README.md：

CPU 上也有参考值：SCRFD-0.5GF 在 640×480 输入下单线程约 28.3ms（AMD Ryzen 9 3950X，OMP_NUM_THREADS=1）。mAP 是"不同置信度阈值下精确率-召回率曲线下的面积"，Easy/Medium/Hard 对应人脸从清晰到小脸、遮挡的三种难度子集。

识别侧的完整榜单（含 Glint360K、WebFace600K 等数据集的 R18~R100 ONNX 模型）在 model_zoo/README.md，训练与评测代码分别在 detection/scrfd/ 和 recognition/（ArcFace 的 PyTorch/MXNet/Paddle 多实现、Partial FC）。

排查手册：漏检小脸、GPU 没生效、阈值不合适

现象：GPU 装了但没跑上 CUDA。原因：onnxruntime只含 CPU 推理。处理：pip install onnxruntime-gpu，构造时显式指定FaceAnalysis(providers=['CUDAExecutionProvider', 'CPUExecutionProvider'])——官方 Quick Example 就是这个写法。

现象：远景小脸漏检。原因：检测尺寸或置信度门槛。处理：保持prepare()默认 Auto（128×128 + 640×640 双档 + 统一 NMS），别自己传固定小尺寸；仍漏检就把门槛从默认 0.5 调低，如app.prepare(ctx_id=-1, det_thresh=0.3)。

现象：比对结果对不上，实际是同一个人。原因：0.65 只是示例起点，不是普适标准。处理：攒一批业务里的"同一人/不同人"真实样本对，打印各自相似度分布，从分布的中间空档定阈值；调低会增加误认，调高会增加漏认。

现象：首次运行卡住很久。原因：在自动下载 buffalo_l（326MB）到~/.insightface/models/。处理：看该目录体积变化确认进度；网络差就手动下载 zip 解压到同一目录再运行。

现象：想把预训练模型用到商业产品里。⚠️ 原因：代码是 MIT 协议，但 buffalo 系列等预训练模型仅限非商业研究使用（README.md License 一节）。处理：商用需按 README 中给出的联系渠道单独获取授权，或训练自有数据模型。

不止脚本：桌面 GUI、1:N 搜索服务与换脸入口

要界面不要写代码，1.0 版本附带跨平台桌面 GUI（InsightFace Evaluation Studio）：

pip install "insightface[gui]" insightface-gui

支持本地 1:1 比对、1:N 图库搜索、相册按人聚类（DBSCAN 默认余弦阈值 0.48）、换脸试验入口，用户数据默认存在~/.insightface/gui，不自动上传；注意 GUI 不自动下载模型，要在 Models > Downloads 里手动拉取（详见 python-package/README.md）。

需要团队共用的服务，看 InsightFace Server：一个 Linux x86_64 容器装下 Web UI、snake_case REST API 和 Python 客户端，覆盖检测、比对、注册和 1:N Person 搜索，向量索引支持 FP32/FP16/BF16/INT8，官方数据为单张 RTX 5090 上 INT8 存 5890 万根 512 维向量、10M 规模 Top-5 查询 p50 3.84ms：

换脸（inswapper）在 examples/in_swapper/，要求insightface版本 >= 0.7；3D 重建、视线估计等进阶方向在 reconstruction/。

下一步建议很具体：拿你自己相册里的几组"确定同人/确定不同人"照片对，把上面的 1:1 比对脚本跑一遍，把相似度分数全部打出来。你会发现同一人分布和不同人分布之间往往有一段空档——阈值就从空档中间取，0.65 只是你校准前的起点。

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