InsightFace — 人脸识别 / 检测 SOTA 工具箱

待复核

是什么

InsightFace 是一个人脸分析工具箱：它把人脸检测、关键点对齐、身份特征提取、比对、评估和部分换脸实验代码放在同一个仓库里。日常类比：像一个照相馆的后台工作台，不只负责“拍到脸”，还要负责“框出脸、摆正脸、量出特征、比较是不是同一个人”。

最小使用感受是这样：

from insightface.app import FaceAnalysis
from insightface.data import get_image

app = FaceAnalysis(providers=["CPUExecutionProvider"])
app.prepare(ctx_id=-1)
img = get_image("t1")
faces = app.get(img)
print(len(faces), faces[0].bbox, faces[0].normed_embedding.shape)

这几行不是训练模型，而是调用它内置的模型包：先用检测器找脸，再做人脸对齐和特征抽取，最后给出可以做相似度比较的向量。

它出名的原因是两条主线：ArcFace 让人脸识别的特征更容易拉开距离，RetinaFace / SCRFD 让检测在真实照片里更稳。仓库本身更像“人脸研究事实仓库”，里面有论文实现、模型包、评估工具和 Python/GUI 入口。

为什么重要

不理解 InsightFace，下面这些事会卡住你：

为什么“人脸识别”不是一个模型结束，而是检测、对齐、特征、阈值评估连成一条流水线。
为什么同一张脸换角度、戴口罩、多人同框时，比“裁一张头像丢分类器”复杂得多。
为什么 ArcFace 论文影响这么大：它把“同一个人靠近、不同人拉远”做成了角度空间里的训练目标。
为什么模型 license 和代码 license 要分开看：代码是 MIT，但官方预训练模型常常限制在非商业研究用途。

核心要点

流水线不是单点模型：InsightFace 的常用入口 FaceAnalysis 会串起检测、关键点、识别、属性等模块。类比医院体检：不是只量身高，而是一套检查表按顺序跑，最后才给出结论。
embedding 是“脸的坐标”：识别模型不会直接输出姓名，而是输出归一化向量 normed_embedding。类比给每张脸分配地图坐标，两张脸是不是同一个人，要看两个坐标的余弦相似度是否超过阈值。
模型包决定能力边界：默认 buffalo_l 这种模型包里包含检测、识别、关键点和属性模型；只换代码不换模型，能力不会凭空变强。类比工具箱里的螺丝刀：手法再熟，没带合适刀头也拧不了对应螺丝。

实践案例

案例 1：一张多人照片里检测脸、画框、算相似度

官方 examples/demo_analysis.py 做的是“检测 + 识别 + 相似度矩阵”：

import cv2
import numpy as np
from insightface.app import FaceAnalysis
from insightface.data import get_image

app = FaceAnalysis()
app.prepare(ctx_id=0, det_size=None)
img = get_image("t1")
faces = app.get(img)
cv2.imwrite("t1_output.jpg", app.draw_on(img, faces))

feats = np.array([face.normed_embedding for face in faces], dtype=np.float32)
sims = np.dot(feats, feats.T)
print(sims)

逐部分解释：

FaceAnalysis() 负责加载模型包，不需要你手动把检测器和识别器接起来。
det_size=None 表示使用新版自动检测尺寸策略，兼顾小脸和正常尺寸人脸。
app.get(img) 返回每张脸的框、关键点、属性和 embedding。
np.dot(feats, feats.T) 是所有脸两两做余弦相似度，因为 embedding 已经归一化。

案例 2：只调用检测模型或只调用识别模型

官方 Python 包 README 给了更“拆开看”的写法：

import insightface
from insightface.app import FaceAnalysis

det_app = FaceAnalysis(allowed_modules=["detection"])
det_app.prepare(ctx_id=0)

recognizer = insightface.model_zoo.get_model("your_recognition_model.onnx")
recognizer.prepare(ctx_id=0)

逐部分解释：

allowed_modules=["detection"] 只启用检测，适合你已经有别的识别模型时复用检测器。
model_zoo.get_model(...) 可以直接加载 ONNX 模型，适合把自己训练或授权的模型接进来。
prepare(ctx_id=0) 是选择运行设备；CPU 常用 ctx_id=-1，GPU 常用 0。
这说明 InsightFace 不只是黑盒 app，也能作为模型 zoo 和推理 glue code 使用。

案例 3：身份迁移 demo 的一行模型调用

官方 examples/in_swapper 演示了 0.7 版本加入的身份迁移 demo；它明确说旧 demo 不再维护，使用时必须确认授权和本人同意：

import cv2
import insightface
from insightface.app import FaceAnalysis
from insightface.data import get_image

app = FaceAnalysis(name="buffalo_l")
app.prepare(ctx_id=0)
swapper = insightface.model_zoo.get_model(
    "inswapper_128.onnx", download=True, download_zip=True
)

img = get_image("t1")
faces = sorted(app.get(img), key=lambda x: x.bbox[0])
source_face = faces[2]
result = img.copy()
for face in faces:
    result = swapper.get(result, face, source_face, paste_back=True)
cv2.imwrite("t1_swapped.jpg", result)

逐部分解释：

buffalo_l 是这里要求的识别模型包；官方说明其他 embedding 可能导致结果异常。
inswapper_128.onnx 是换脸模型，输入输出分辨率是 128×128，不适合当高清生产工具。
source_face 提供身份，循环里的 face 是目标图里要替换的位置。
paste_back=True 会把生成的人脸贴回原图；这类能力必须放在合规、授权和同意的边界里使用。

踩过的坑

把代码 MIT 误读成模型可商用：仓库代码是 MIT，但官方预训练模型和训练数据常限制非商业研究用途，原因是人脸数据和模型授权是另一层协议。
把 embedding 当姓名分类结果：normed_embedding 只是向量，必须配合阈值、库内搜索和业务规则，原因是模型不知道你的人员名单。
只调大检测尺寸期待全场景变好：大尺寸可能找出小脸，但也会变慢、占显存，原因是检测输入越大计算越多。
换脸 demo 当长期维护产品用：官方示例写明旧 demo 不再维护且分辨率低，原因是它更像研究示例，不是生产级换脸服务。

适用 vs 不适用场景

适用：

想快速搭一条本地人脸检测、对齐、识别、相似度比较流水线。
需要复现实验或理解 ArcFace、RetinaFace、SCRFD、Partial FC 这类人脸论文主线。
有合法授权的模型和数据，想做本地 1:1 验证、1:N 搜索或企业评估报告。
想用 Python 或 ONNXRuntime 把人脸模型接进已有图像处理程序。

不适用：

想直接做商业人脸识别 SaaS，却没有模型、数据、用户同意和合规授权。
只需要通用目标检测，不关心人脸关键点、身份特征和阈值评估；这时 opencv 或 YOLO 类项目更直接。
想训练任意视觉大模型；InsightFace 聚焦人脸，训练链路也围绕人脸数据设计。
想在浏览器里纯前端运行；InsightFace 主线是 Python、ONNXRuntime、PyTorch/MXNet 和桌面 GUI。

历史小故事（可跳过）

2018-2019 年：ArcFace 论文和实现让 InsightFace 在深度人脸识别社区快速出名，核心是角度间隔损失。
2020 年：RetinaFace 被 CVPR 接收，仓库的人脸检测主线从识别扩展到定位和关键点。
2021-2022 年：SCRFD、Partial FC 等工作进入仓库，检测效率和大规模身份训练成为重点。
2024 年：InspireFace C/C++ SDK 发布，说明社区需求从研究代码延伸到跨平台部署。
2026 年：InsightFace 1.0 加入 Evaluation Studio 桌面 GUI，降低本地评估和报告生成门槛；仓库约 25.6k stars。

学到什么

人脸识别是一条链，不是一个按钮：检测、对齐、embedding、阈值、评估每一步都会影响结果。
ArcFace 的关键不是“分类更多人”，而是把人脸特征放到更适合比较角度距离的空间里。
工程价值来自组合：模型 zoo、ONNXRuntime、示例、GUI、评估文档放在一起，才让研究成果能被新手真正跑起来。
生物特征项目必须先看边界：授权、同意、隐私、数据保留和部署场景，比普通图片分类更敏感。

关联

pytorch —— 训练人脸识别、检测模型时常用的深度学习框架。
opencv —— 负责读图、写图、画框等传统计算机视觉 glue code。
mediapipe —— 也做人脸和人体感知，但更偏实时端侧 pipeline。
paddle-lite —— 同样关心模型部署，只是 Paddle Lite 偏端侧推理引擎，InsightFace 偏人脸算法工具箱。
keras —— 另一个高层深度学习入口，对比能看清“框架”和“领域工具箱”的区别。
open-sora —— 都是媒体 AI 项目，但 Open-Sora 聚焦视频生成，InsightFace 聚焦人脸分析。

反向链接

（暂无反向链接）

InsightFace — 人脸识别 / 检测 SOTA 工具箱

是什么

为什么重要

核心要点

实践案例

案例 1：一张多人照片里检测脸、画框、算相似度

案例 2：只调用检测模型或只调用识别模型

案例 3：身份迁移 demo 的一行模型调用

踩过的坑

适用 vs 不适用场景

历史小故事（可跳过）

学到什么

延伸阅读

关联

反向链接