InsightFace 人脸分析三步跑通本地人脸检测与 1:1 比对完整指南【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightfaceInsightFace 是一个开源的 2D/3D 人脸分析工具箱人脸检测、人脸识别、关键点对齐、属性估计全部可在本地完成数据不离开你的机器。装上 Python 包和预训练模型包后几分钟内就能跑通一个离线的人脸比对 Demo——这篇指南带你完成环境安装、最小示例、模型包选型和常见坑的排查。一张图看懂 InsightFace 的能力边界InsightFace 把检测 → 对齐 → 识别 → 属性整条链路打包成了可直接安装的 Python 包一次调用即可跑完全部环节。下图展示了它覆盖的典型能力人脸框与关键点标注、性别年龄属性、闭眼/活体状态判断、多人合影识别与口罩场景检测。默认能力包是buffalo_l约 326MB内含 SCRFD-10GF 检测模型、ResNet50WebFace600K 识别模型、2D 106 点 3D 68 点关键点模型和性别年龄属性模型首次运行会自动下载到~/.insightface/models/。如果你不需要对齐和属性最小的buffalo_sc只有 16MB。环境要求与安装两条命令装好依赖推理只需 onnxruntime不需要装 PyTorch 或 MXNet那是仓库内训练模块的需求master 分支基于 PyTorch 1.6 或 MXNet 1.6~1.8。CPU 推理装onnxruntime即可想用 GPU 需自行安装onnxruntime-gpu。pip install -U insightface pip install onnxruntime装好后用下面这段最小脚本就能完成第一次人脸分析——图片用的是仓库自带的示例图t1.jpg里面有 6 个人import cv2 from insightface.app import FaceAnalysis app FaceAnalysis(namebuffalo_l) app.prepare(ctx_id-1) # -1 表示 CPU img cv2.imread(python-package/insightface/data/images/t1.jpg) faces app.get(img)跑通后faces是一个 Face 对象列表图里有几张脸就有几个对象。每个对象里装着四样东西bbox人脸框左上角 x/y 右下角 x/y、kps双眼、鼻尖、双嘴角共 5 个关键点坐标、det_score检测置信度、embedding512 维识别向量可以理解为这张脸的数字指纹此外还有gender/age属性字段。模型包下载位置在~/.insightface/models/第二次运行就不再重复下载。核心功能拆解人脸检测框出每一张脸和它的 5 个关键点检测就是app.get(img)这一步内部由 SCRFD 模型完成v1.0 起prepare()默认用 128×128 和 640×640 两档尺寸做检测、再统一 NMS 合并小脸不容易漏。上面示例图t1.jpg会被检出 6 个人仓库的人脸交换示例 examples/in_swapper/ 正是用它并断言len(faces)6。如果不想手动处理坐标直接调app.draw_on(img, faces)就能在原图上画出红色人脸框、关键点圆点并在框旁标注性别年龄文字如M,23配合cv2.imwrite即可存盘。1:1 比对用 embedding 余弦相似度判断是否同一人判断两张照片是不是同一个人只需用各自face.embedding算余弦相似度再和阈值比较。官方示例 examples/face_recognition/insightface_app.py 默认阈值取 0.65并明确提醒要按你的业务场景调整import numpy as np emb1, emb2 faces1[0].embedding, faces2[0].embedding sim float(emb1 emb2 / (np.linalg.norm(emb1) * np.linalg.norm(emb2))) print(同一人 if sim 0.65 else 不是同一人)输出的sim取值在 -1 到 1 之间越接近 1 越像同一人。一图多人时注意自己选定要比的那张脸官方示例取检出的第一张否则会拿错人。性能数据与模型包怎么选下表是仓库公布的 SCRFD 检测模型在 WIDERFace 上的 mAPVGA 分辨率、单尺度测试出处为 detection/scrfd/README.md模型Easy (mAP)Medium (mAP)Hard (mAP)参数量 (M)推理耗时 (ms)SCRFD-0.5GF90.5788.1268.510.573.6SCRFD-2.5GF93.7892.1677.870.674.2SCRFD-10GF95.1693.8783.053.864.9SCRFD-34GF96.0694.9285.299.8011.7识别侧各模型包的精度出处为 python-package/README.md模型包体积MR-ALLLFWCFP-FPAgeDB-30IJB-C(E4)buffalo_l默认326MB91.2599.8399.3398.2397.25buffalo_s159MB71.8799.7098.0096.5895.02选型一句话追求精度用默认的buffalo_l端侧或低配设备选buffalo_s只想要检测和识别、不要对齐和属性就选最小的buffalo_sc16MB精度与buffalo_s相同antelopev2407MB用 ResNet100Glint360K是仓库中识别配置最重的一档。5 条避坑指南 首次运行报模型缺失或卡在下载→ 原因是 pip 安装的包里不含预训练模型自动下载需要网络且首次较慢 → 保持网络通畅等它下载完缓存在~/.insightface/models/离线环境则手动下载 zip 解压到该目录后再运行。远处小脸漏检→ 原因是把prepare()改成了固定的小det_size小脸在缩图上被压没了 → 保持默认的 Auto 检测128×128 640×640 双尺度 统一 NMS只在追求极致速度时才改固定尺寸。GPU 没生效、CPU 占用 100%→ 原因有两个只装了 CPU 版onnxruntime或没指定 CUDA 执行器 → 安装onnxruntime-gpu并在FaceAnalysis(providers[CUDAExecutionProvider, CPUExecutionProvider])中声明后端、ctx_id0指定显卡。比对结果时准时不准→ 原因是拿 0.65 这个示例默认值当万能阈值 → 调低会增加误认、调高会增加漏认建议收集你业务里的真实坏例该同判不同、该不同判同来回调阈值。⚠️ 商用时发现授权边界问题→ 原因是代码是 MIT 协议、学术和商用都不受限但附带的预训练模型buffalo 系列等仅限非商业研究使用 → 商用含inswapper换脸系列、buffalo_l等识别模型包需按 README.md 中的说明联系官方获取授权不要直接搬进商业产品。延伸阅读 Python 库安装、模型包列表、调用自定义 ONNX 模型python-package/README.md人脸检测训练与 WIDERFace 评测SCRFDdetection/scrfd/人脸识别训练ArcFace 的 PyTorch/MXNet/Paddle 多实现、Partial FCrecognition/模型仓库与精度榜单model_zoo/README.md1:1 比对示例脚本examples/face_recognition/人脸交换示例inswapper需 v0.7examples/in_swapper/自建人脸搜索服务容器化 Web UI REST APIserver/README.md桌面 GUIInsightFace Evaluation Studiopip install insightface[gui]python-package/docs/gui.md3D 人脸重建、视线估计等进阶方向reconstruction/写在最后整个最小闭环其实只有三步pip install装好库和 onnxruntimeFaceAnalysis().prepare()拉起模型app.get(img)读回每张脸的 bbox、关键点和 embedding——本地离线的人脸检测与比对就通了。之后可以顺着两个方向继续深挖想训练自己的检测器看 detection/scrfd/ 的训练与 NAS 搜索流程想做大规模人脸搜索或 3D 重建则看 server/ 和 reconstruction/ 两个模块 ✨【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考