企业官网建设流程全解析

InsightFace 人脸检测识别工具箱：8 行代码跑通本地人脸分析

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

想判断两张照片是否同一人、又想批量框出图里所有人脸，但数据不能离开本机？InsightFace 把人脸检测、识别、对齐、属性分析打包成可直接安装的 Python 库，预训练模型首次运行自动下载，无需自己训练。

一次配置跑完检测、对齐、识别、属性的完整链路

InsightFace 官方模型包（buffalo 系列）按任务把四个模型捆在一起，FaceAnalysis一次配置即可串起整条链路：

• 人脸检测：内置 SCRFD 检测器，输出边界框、5 点关键点与置信度；
• 人脸对齐：2D 106 点与 3D 68 点关键点标定，供裁剪、打码、3D 重建使用；
• 人脸识别：输出 512 维 embedding 向量，支持 1:1 比对与 1:N 搜索；
• 属性分析：性别、年龄（部分模型包还有表情、姿态）。

检测 → 对齐 → embedding → 属性在app.get(img)一次调用内自动完成，不需要逐模型手写流水线。下图是人脸检测、关键点、属性与活体判断等能力的组合效果：

从零到首次人脸检测识别的三步安装

环境要求 Python 3.x；推理后端为 onnxruntime——CPU 装onnxruntime即可，要 GPU 推理则需手动安装onnxruntime-gpu。

pip install -U insightface

下面这段脚本把FaceAnalysis的初始化、检测、绘制三步串起来，图片用的是仓库自带的六人示例图：

import cv2 from insightface.app import FaceAnalysis app = FaceAnalysis(name='buffalo_l') # 默认模型包 app.prepare(ctx_id=-1) # -1 用 CPU，0 用 GPU img = cv2.imread('python-package/insightface/data/images/t1.jpg') faces = app.get(img) cv2.imwrite('t1_output.jpg', app.draw_on(img, faces))

跑完之后会看到两件事：首次运行自动把约 326MB 的 buffalo_l 模型包下载到~/.insightface/models/（之后离线可用）；t1_output.jpg上画出人脸框、关键点与性别年龄文字。faces是 Face 对象列表，每个对象含bbox（边界框）、kps（5 点关键点）、det_score（置信度）、gender/age，以及 512 维embedding——可理解为这张脸的"数字指纹"。

核心能力实操：检测绘制与 1:1 身份比对

批量人脸检测：一张图框出所有脸

场景：一张合照或监控截图里有几十张脸，需要自动框出并拿到关键点。关键 API 是app.get(img)，返回图中全部人脸的 Face 对象；app.draw_on(img, faces)负责画框、标点和属性文字。示例图t1.jpg里有 6 张脸，len(faces)即为 6；需要限制返回数量或按置信度排序时，get()支持max_num与det_metric参数。

1:1 身份比对：两张照片是不是同一个人

场景：身份核验、相册整理、照片查重。核心逻辑是取两张照片各自的face.embedding，算余弦相似度再和阈值比较：

sim = emb1 @ emb2 / (np.linalg.norm(emb1) * np.linalg.norm(emb2)) is_same = sim > 0.65

参考实现 examples/face_recognition/insightface_app.py 中 512 维向量已做 L2 归一化，点积即余弦相似度，相似度越高越可能是同一人，默认阈值取 0.65。这个阈值不是万能的：调低会增加误认（不同人被判成同一人），调高会增加漏认（同一人被拆开）。正确做法是收集业务里的真实正、反例对，回看相似度分布，在可接受的误认率处切阈值。一图多人时要自己选定要比较的那张脸——参考实现取第一张检出的人脸并打印警告。

检测精度与识别包怎么选型

检测侧是 SCRFD 不同 FLOPs 档位（mAP 为 VGA 640×480 单尺度测试，数据出自 model_zoo/README.md 与 detection/scrfd/README.md）：

识别侧是 buffalo 系列模型包（数据出自 python-package/README.md）：

默认推荐buffalo_l：精度最高且支持自动下载。端侧或低算力场景换buffalo_s，只跑检测和识别、不要对齐与属性时用 16MB 的buffalo_sc。注意各包的 East Asian 分数明显偏低（buffalo_l 为 74.96），业务以东亚人脸为主时建议用自有数据验证后再定阈值。

用之前必须知道的五条限制

• License 边界：代码是 MIT 协议，学术与商用均无限制；但 buffalo 系列预训练模型（自动下载或手动下载都一样）仅限非商业研究用途，商用需另行获取授权，详见 README.md。
• GPU 后端别装错：onnxruntime只含 CPU 推理。要跑 CUDA 必须手动安装onnxruntime-gpu，并在FaceAnalysis(providers=['CUDAExecutionProvider', ...])里显式指定，否则 GPU 白装。
• 首次运行会下载：约 326MB 的 buffalo_l 包下载到~/.insightface/models/。纯离线环境需先手动下载 zip 包解压到该目录再运行，详见 python-package/README.md。
• 小脸召回依赖 Auto 检测尺寸：v1.0 起prepare()默认用 128×128 与 640×640 双档检测、统一 NMS 合并；追求速度改成固定input_size会牺牲小脸召回。
• 阈值是双向的：det_thresh默认 0.5，调高减少误检但漏检更多，调低反之；比对阈值 0.65 同理，都要用业务里的真实坏例来回调。

进阶路径与资源索引

• 识别训练：ArcFace 的 PyTorch/MXNet/OneFlow/Paddle 多框架实现与 Partial FC 大规模身份训练，recognition/；
• 检测训练与 NAS：SCRFD 训练代码、WIDERFace 数据准备与自动搜索脚本，detection/scrfd/；
• 人脸搜索服务：容器化的 Web UI + REST API + Python SDK，单机支持千万级向量检索，server/；
• 桌面 GUI：InsightFace Evaluation Studio，跨平台的本地比对、相册聚类与企业级评测报告，python-package/docs/gui.md；
• 人脸交换：inswapper 单行调用示例，examples/in_swapper/；
• 3D 重建与视线估计：单目 3D 重建、纹理补全、视线估计等进阶方向，reconstruction/。

回到开头的问题——数据留在本机、模型开箱即用，从 buffalo_l 跑通第一张图开始，就可以顺着 SCRFD 训练代码或 InsightFace Server 往生产方向深挖了 🚀

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