InsightFace：2D/3D 人脸分析开源工具箱｜部署与使用全指南
项目仓库： https://github.com/deepinsight/insightface
官网：insightface.ai · 许可证：MIT（代码）；训练数据与模型权重仅限非商业研究 · 最新版本：InsightFace 2.1 · 形态：Python SDK + C++ SDK + 自托管 Server · 维护方：贾国、邓健康等
1 项目简介
InsightFace 是一套覆盖检测、识别、对齐、属性、活体、换脸的人脸分析开源工具箱。它提供 SCRFD 检测器、ArcFace/PartialFC 识别模型、inswapper 换脸模型，并在 NIST-FRVT 1:1 上取得过第一。最新 2.0/2.1 加入 PrivateFrame（视频人脸打码/马赛克）、RGB 活体检测、PersonAnalysis（人检测+人脸识别+人体 ReID）、以及自托管 InsightFace Server（AWS Rekognition 替代）。
1.1 核心信息一览
| 项目项 | 内容 |
|---|---|
| 项目名称 | InsightFace |
| 仓库地址 | github.com/deepinsight/insightface |
| 官网 | insightface.ai |
| 代码许可证 | MIT |
| 模型权重 | 非商业研究（inswapper 与开源识别模型需联系作者授权商用） |
| 最新版本 | 2.1（PersonAnalysis） |
| 形态 | Python SDK + C++ SDK + Server |
1.2 适用场景
- 人脸检测、识别、比对、入库搜索。
- 视频人脸打码/马赛克（PrivateFrame）。
- RGB 活体检测。
- 自托管人脸检索服务（替代 AWS Rekognition）。
1.3 能力边界（官方口径）
- 代码 MIT 可商用；但训练数据与预训练模型权重仅限非商业研究。
- inswapper 系列换脸模型、开源识别模型的商用授权需邮件联系作者。
- 2.0 起默认 Python 安装不再需要 C++ 编译。
2 功能特性
- SCRFD 检测器：ICLR 2022，轻量高精度。
- ArcFace / PartialFC：NIST-FRVT 1:1 第一。
- inswapper 换脸：inswapper_128.onnx 等。
- PrivateFrame：视频人脸打码/马赛克，桌面/CLI/Python 三端。
- RGB 活体检测：可选
addon，
normal/observe模式。 - PersonAnalysis：人检测 + 人脸识别 + 人体 ReID。
- InsightFace Server：自托管 Web UI + REST API + Python 客户端，INT8 量化，单 RTX 5090 可搜 5000 万图库。
- CoreML/CUDA/CPU 自动选择：跨平台推理。
3 官方界面预览
官方 Web Demo：人脸定位 demo.insightface.ai:7007、识别 7008、换脸 7009。
4 官方跳转链接汇总
| 类别 | 链接 | 说明 |
|---|---|---|
| 仓库 | github.com/deepinsight/insightface | 源码 |
| Python SDK 文档 | python-package/README.md | 安装与 API |
| Server 文档 | server/docs/user-guide.md | 自托管服务 |
| 商用授权 | contact@insightface.ai | inswapper/识别模型商用 |
5 前置要求与服务器配置
5.1 软件前提
- Python 3.7+。
- 2.0 起默认安装不再需要 C++ 编译。
- 可选：CUDA、CoreML、ONNX Runtime。
5.2 硬件建议
| 场景 | 建议 |
|---|---|
| 单图推理 | CPU 即可 |
| 视频实时 | GPU 加速 |
| Server 5000 万库搜索 | 单 RTX 5090 |
6 方式一：Python SDK 安装与使用
pip install insightface首次使用会自动下载模型包（如 buffalo_l）。
from insightface.app import FaceAnalysis
app = FaceAnalysis(providers=['CUDAExecutionProvider', 'CPUExecutionProvider'])
app.prepare(ctx_id=0, det_size=(640, 640))
faces = app.get(img)7 方式二：自托管 Server
cd server
# 按 server/docs/user-guide.md 启动容器
# 提供 Web UI + REST API + Python 客户端8 模型包
| 包 | 说明 |
|---|---|
| buffalo_l | 默认识别包 |
| raccoon_s / raccoon_l | 2.0 新增 |
| cheetah_s / cheetah_l | 2.1 PersonAnalysis |
9 常用运维命令
nvidia-smi10 常见故障排查
- 模型下载失败：手动从 release 下载到
~/.insightface/models/。 - 商用授权：邮件 contact@insightface.ai。
- CPU 慢：换 CUDAExecutionProvider。
11 风险与合规说明
- 模型权重非商业：代码 MIT，但预训练模型仅限非商业研究；商用必须联系作者授权。
- 人脸数据涉及个人信息保护法，部署需合规。
- inswapper 换脸模型滥用风险高，仅用于本人或已授权素材。
本文基于官方 README 整理，仅供学习与部署参考；以仓库最新说明为准。