InsightFace 开源 2D/3D 人脸分析工具箱全景解析：识别、检测、对齐、换脸与自托管部署

InsightFace 是面向 2D 与 3D 深度人脸分析的开源工具箱，覆盖人脸识别、人脸检测、人脸对齐、人脸属性与换脸等完整能力。本文以仓库根目录 README.md 为主线，结合 python-package、model_zoo、detection/scrfd、recognition/arcface_torch、server 等子模块文档与核心源码，系统讲解其架构、安装、模型体系、调用方式与实战方案。读完本文，你将掌握如何用一行代码完成人脸检测/识别/对齐推理、如何选用模型包与精度、如何训练 ArcFace 系列模型，以及如何部署自托管人脸识别服务。

项目概览：一个仓库，覆盖人脸分析的完整链路

InsightFace 是一个开源的 2D 与 3D 深度人脸分析工具箱，主要由 Jia Guo 与 Jiankang Deng 维护，核心实现基于 PyTorch 和 MXNet 两大框架。master 分支要求 PyTorch 1.6+ 和/或 MXNet 1.6-1.8，Python 3.x（见 README.md）。

它高效实现了人脸识别、人脸检测、人脸对齐等多个方向中的前沿算法，并针对训练与部署两端同时优化：训练侧提供数据集、网络设置与损失设计；部署侧提供 ONNX 模型与统一的 Python 推理接口。仓库各子模块分工如下：

模块目录	职责
recognition	人脸识别：ArcFace 多框架实现、Partial FC、VPL、SubCenter ArcFace
detection	人脸检测：RetinaFace、SCRFD、blazeface_paddle
alignment	人脸对齐：SDUNets（热图法）、SimpleRegression（坐标回归法）
attribute	人脸属性：性别与年龄
reconstruction	3D 人脸重建：PBIDR、gaze、jmlr、ostec
cpp-package	跨平台 C/C++ 人脸识别 SDK（InspireFace）
server	自托管人脸识别服务（Web UI + REST API + SQLite）
examples	推理示例：换脸、检测、识别、人物检测

InsightFace 1.0 更新：轻量安装与桌面 GUI

InsightFace 1.0 的核心变化是降低本地使用门槛，聚焦更简单的本地评估与桌面体验（见 README.md）：

• 默认 Python 包不再编译可选的 C++/Cython face3d 扩展，减少对本地编译器的依赖，安装更轻量；
• 新增 InsightFace Evaluation Studio，一个跨平台（Windows、macOS、Linux）桌面 GUI Demo；
• GUI 支持本地人脸识别、企业级模型评估/报告生成，以及基础换脸试用。

安装与启动 GUI

InsightFace 1.0.1 的桌面 GUI 通过 [gui] extra 安装（详见 python-package/README.md）：

pip install "insightface[gui]"
insightface-gui

开发模式安装：

cd python-package
pip install -e ".[gui]"
insightface-gui

等效的启动命令还包括 insightface-eval-studio、insightface-desktop 以及 python -m insightface.gui。

GUI 能力与交互设计

InsightFace Evaluation Studio 提供本地 1:1 人脸比对、People Library 管理、1:N 人脸搜索、多脸照片识别、批量文件夹处理、相册人物聚类、企业评估报告导出以及换脸入口。用户图片、视频、向量、数据库和报告默认存储在本地 ~/.insightface/gui 目录下，不会自动上传。

界面采用基于模式的导航：左侧常驻 Workflows 侧栏，可选择 Face Recognition（识别）、Album Management（相册管理）、Face Swap（换脸）、Enterprise Evaluation（企业评估） 四个工作区：

• Face Recognition：上传一张 query 图与一张 gallery 图做 1:1 比对，或上传多张 gallery 图/文件夹做 1:N 搜索；
• Album Management：添加一个或多个文件夹、刷新新图片、以 DBSCAN 聚类（默认余弦相似度阈值 0.48）并按原始照片缩略图审查结果，聚类结果本地保存、下次启动沿用；
• Enterprise Evaluation：本地 1:1 与 1:N 身份文件夹评估，支持 Auto Split、指标计算与 PDF 报告导出。企业数据集必须先通过校验（检查文件夹布局、gallery/probe 规则及多脸处理策略）才能评估。

顶部栏与 Tools 菜单提供全局工具：Settings（UI 主题与语言，语言默认跟随操作系统，支持英文、中文、日文、韩文、西、法、德、葡、俄九种；主题包括 System、Precision Light、Studio Dark、Graphite Pro、Azure Lab、Emerald Focus、Crimson Audit）、Models 与 License。

模型不会自动下载：在 Models > Downloads 中点击 Refresh Download URLs 读取最新发布资产地址后手动下载；zip 缓存在 ~/.insightface/gui/cache/models，解压至 ~/.insightface/models/<model_name>/。下载列表还包含第三方人脸修复模型 GFPGANv1.4，下载后可在 Models > Runtime 开启 GFPGAN post-processing，在换脸后进行 512x512 人脸修复。检测尺寸默认 Auto，即联合执行 128x128 与 640x640 检测后再统一 NMS。

可选 face3d 扩展

需要传统 mask renderer / face3d 路径的用户可显式开启（见 python-package/README.md）：

pip install -e ".[face3d]" --no-build-isolation --config-settings editable_mode=compat
python setup.py build_ext --inplace --with-face3d

或使用环境变量：

INSIGHTFACE_WITH_FACE3D=1 python setup.py build_ext --inplace

更多细节可参考 python-package/docs/gui.md 与 python-package/docs/commercial_evaluation.md。

InsightFace Server：自托管的人脸识别服务

server/README.md 描述的 InsightFace Server 是一个自托管的 Web UI + snake_case REST API + Python 客户端方案，在单个 Linux x86_64 CPU 或 NVIDIA GPU 容器内完成本地 ONNX Runtime 推理与 SQLite 存储，使用运营方提供、manifest 校验通过的模型。官方将其定位为 AWS Rekognition 的简单替代方案，但不是 AWS 兼容实现（不实现 SigV4、IAM、Region 等语义），且强调隐私：图片、向量、模型与索引都可以留在自有网络内。

其功能亮点（见 server/README.md）：

• SCRFD 人脸检测、五点关键点、对齐、ArcFace 向量、L2 归一化、原始余弦相似度与精确 1:N Person 搜索；
• 多分辨率检测 + 统一 NMS，支持 largest / center_largest 单脸选择策略；
• Collection -> Person -> FaceSample 三级存储，Collection 与模型绑定，支持多图注册、部分成功、元数据与显式拒绝原因；
• 注册 review_mode：off / standard / strict，可选 external_trusted 预计算向量；
• 精确 GPU 搜索支持 FP32 / FP16 / BF16 / INT8 四种向量存储格式；
• 多语言 Web UI：Dashboard、Collections、People、Detect、Compare、Search、RTSP 监控、系统诊断、Help；
• /v1 下 29 个 snake_case REST 操作（含需认证的 /v1/embeddings）与类型化的轻量 Python SDK；
• 持久化服务端 RTSP 监控（内存事件有界、客户端独立、支持 preview.mjpeg，关闭浏览器不停止监控）；
• SQLite 作为持久化真相源、一次性内存精确索引、只读 /models、持久 /data、健康检查、严格 CUDA 启动校验（无静默 CPU 回退）；
• 输入支持 JPEG/PNG/WebP，原始上传默认不保留。

INT8 量化与大规模搜索性能

Server 内置的原生 CUDA 精确 flat 索引在单张 RTX 5090（32,607 MiB）上，INT8 格式可存储最多 58.9M 个 512 维图像向量。GPU-only 实测数据如下：

GPU 数据类型	最大图像向量数	10M Top-5 p50	10M 串行 QPS
FP32	15.8M	12.84 ms	77.85
FP16	30.7M	6.83 ms	146.32
BF16	30.7M	6.83 ms	146.33
INT8	58.9M	3.84 ms	260.81

INT8 相比 FP32 实现了 3.73 倍的容量与 3.35 倍的 10M Top-5 吞吐提升。同时在 ICCV21-MFR 多民族 MR-ALL（FAR 1e-6）基准上，FP32 与 INT8 均为 91.25%（未取整差异仅 0.0011 个百分点），即 INT8 无明显精度损失，且此对比衡量的是向量存储/搜索精度而非 INT8 模型推理。

Server 快速启动

在完整仓库检出后，将模型安装到 server/.models（见 server/README.md）：

mkdir -p server/.models
docker compose -f server/deploy/compose.cpu.yml pull
docker compose -f server/deploy/compose.cpu.yml \
  run --rm models install buffalo_l --accept-license

模型工具支持 buffalo_m、buffalo_sc、antelopev2，会写入 manifest.json 与签名 MODEL.LICENSE，可用 models verify 校验。随后启动 CPU 版：

docker compose -f server/deploy/compose.cpu.yml up -d
curl -fsS http://127.0.0.1:18097/v1/health

CUDA 12 版使用 server/deploy/compose.cuda12.yml，健康检查端口为 18098。相关容器定义见 server/deploy/compose.cpu.yml 与 server/deploy/compose.cuda12.yml。

快速上手：Python 包安装与一行代码推理

推理后端

insightface<=0.1.5 使用 MXNet 作为推理后端；从 insightface>=0.2 起使用 onnxruntime（见 python-package/README.md）。要启用 GPU 推理需自行安装 onnxruntime-gpu，仅 CPU 则安装 onnxruntime 即可。

快速示例

仓库 Quick Start 推荐从 python-package 开始，官方 quick example 如下（见 python-package/README.md）：

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

app = FaceAnalysis(providers=['CUDAExecutionProvider', 'CPUExecutionProvider'])
app.prepare(ctx_id=0)  # Auto detection size: 128x128 + 640x640
img = ins_get_image('t1')
faces = app.get(img)
rimg = app.draw_on(img, faces)
cv2.imwrite("./t1_output.jpg", rimg)

该示例从 t1.jpg 检测人脸并绘制结果。从源码看，face_analysis.py 中定义了 DEFAULT_DET_SIZES = [(128, 128), (640, 640)]，prepare() 在 det_size=None 时自动切换为双尺度检测；get() 先调用检测模型得到 bbox 与关键点 kpss，再逐个人脸串行执行其余模型（识别/对齐/属性）并把结果写入 Face 对象；draw_on() 则绘制检测框、关键点（0/3 号点为绿色）以及性别年龄文本。

底层模型加载原理

FaceAnalysis.__init__（face_analysis.py）会扫描模型目录下的全部 *.onnx 文件，通过 model_zoo.get_model() 加载，并依据 allowed_modules 过滤任务类型。而 model_zoo.py 的 ModelRouter 根据 ONNX 输入输出特征自动路由：输出数 >=5 判定为 SCRFD 检测器；输入 192x192 判定为 Landmark；96x96 判定为 Attribute；双输入 128x128 判定为 INSwapper；方形且边长 >=112 且为 16 的倍数判定为 ArcFaceONNX 识别模型。默认 providers 为 ['CUDAExecutionProvider', 'CPUExecutionProvider']。

模型体系：Model Zoo 与精度对照

InsightFace 的 Python 库提供多个模型包（model pack），加粗名为默认包，Auto 列表示可由库自动下载（见 python-package/README.md）：

Name	Detection Model	Recognition Model	Alignment	Attributes	Model-Size	Auto
antelopev2	SCRFD-10GF	ResNet100@Glint360K	2d106 & 3d68	Gender&Age	407MB	N
buffalo_l	SCRFD-10GF	ResNet50@WebFace600K	2d106 & 3d68	Gender&Age	326MB	Y
buffalo_m	SCRFD-2.5GF	ResNet50@WebFace600K	2d106 & 3d68	Gender&Age	313MB	N
buffalo_s	SCRFD-500MF	MBF@WebFace600K	2d106 & 3d68	Gender&Age	159MB	N
buffalo_sc	SCRFD-500MF	MBF@WebFace600K	-	-	16MB	N

手动下载 zip 模型包后，需先解压到 ~/.insightface/models/ 再调用程序。识别精度对照如下：

Name	MR-ALL	African	Caucasian	South Asian	East Asian	LFW	CFP-FP	AgeDB-30	IJB-C(E4)
buffalo_l	91.25	90.29	94.70	93.16	74.96	99.83	99.33	98.23	97.25
buffalo_s	71.87	69.45	80.45	73.39	51.03	99.70	98.00	96.58	95.02

注：buffalo_m 与 buffalo_l 精度相同，buffalo_sc 与 buffalo_s 精度相同（见 model_zoo/README.md）。MR-ALL 为多民族全对全 1:1 协议（FAR 1e-6）指标。

模型下载与自定义模型

• 对于 insightface>=0.3.3，初始化 app = FaceAnalysis() 时模型会自动下载；
• 对于 insightface==0.3.2，需先执行 insightface-cli model.download buffalo_l；
• 使用自有授权模型：在 ~/.insightface/models/ 下新建目录放入自己的 ONNX 模型，然后以 app = FaceAnalysis(name='your_model_zoo') 加载（见 python-package/README.md）。

最新版库只支持 ONNX 模型：无论用 PyTorch、MXNet 还是其他框架训练，转成 ONNX 后即可被库调用（转换示例见 examples/mxnet_to_onnx.py 与 recognition/arcface_torch/torch2onnx.py）。

调用检测与识别模型

调用检测模型

两种方式（见 python-package/README.md）：

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

# Method-1, use FaceAnalysis
app = FaceAnalysis(allowed_modules=['detection'])  # enable detection model only
app.prepare(ctx_id=0)  # Auto detection size: 128x128 + 640x640

# Method-2, load model directly
detector = insightface.model_zoo.get_model('your_detection_model.onnx')
detector.prepare(ctx_id=0)  # SCRFD defaults to Auto: 128x128 + 640x640

调用识别模型

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

handler = insightface.model_zoo.get_model('your_recognition_model.onnx')
handler.prepare(ctx_id=0)

人脸识别模块：ArcFace 家族与 Partial FC

recognition 模块提供训练数据、网络设置与人脸识别损失设计，支持方法包括：

• ArcFace_mxnet (CVPR'2019)
• ArcFace_torch (CVPR'2019)
• SubCenter ArcFace (ECCV'2020)
• PartialFC_mxnet (CVPR'2022)
• PartialFC_torch (CVPR'2022)
• VPL (CVPR'2021)
• Arcface_oneflow
• ArcFace_Paddle (CVPR'2019)

常用骨干网络包括 IResNet、MobileFaceNet、MobileNet、InceptionResNet_v2、DenseNet 等。训练数据包含清洗后的 MS1M、VGG2、CASIA-Webface（已打包为 MXNet 二进制格式，见 recognition/datasets），评估管线见 recognition/evaluation（含 IJB 与 Megaface）。第三方的 ArcFace 复现覆盖 TensorFlow、PyTorch、Caffe、TensorRT、ONNXRuntime（C++/Go）、MNN、TNN、NCNN 等生态。

ArcFace_torch 训练实战

recognition/arcface_torch/README.md 是 ArcFace 的官方 PyTorch 实现，支持分布式与稀疏训练、混合精度、梯度检查点等省显存技巧，并支持 ViT 模型与 WebFace42M、Glint360K 两个最大开源数据集。要求 torch>=1.12.0。

单卡（不推荐，训练慢且效果欠佳）：

python train_v2.py configs/ms1mv3_r50_onegpu

单机 8 卡：

torchrun --nproc_per_node=8 train_v2.py configs/ms1mv3_r50

双机各 8 卡（16 GPU）：

# Node 0
torchrun --nproc_per_node=8 --nnodes=2 --node_rank=0 --master_addr="ip1" --master_port=12581 train_v2.py configs/wf42m_pfc02_16gpus_r100
# Node 1
torchrun --nproc_per_node=8 --nnodes=2 --node_rank=1 --master_addr="ip1" --master_port=12581 train_v2.py configs/wf42m_pfc02_16gpus_r100

ViT-B（24k batchsize）：

torchrun --nproc_per_node=8 train_v2.py configs/wf42m_pfc03_40epoch_8gpu_vit_b

数据侧，MS1MV2（87k IDs / 5.8M 图）、MS1MV3（93k IDs / 5.2M 图）、Glint360K（360k IDs / 17.1M 图）、WebFace42M（2M IDs / 42.5M 图）均可用；若使用 DALI 读取，需先用 scripts/shuffle_rec.py 打乱 rec 文件。其余框架实现（OneFlow、Paddle）的配置与训练入口见 recognition/arcface_oneflow 与 recognition/arcface_paddle。

人脸检测模块：RetinaFace 与 SCRFD

detection 模块提供带标注的训练数据、网络设置与损失设计，支持方法：

• RetinaFace (CVPR'2020)：单阶段多层级人脸检测器，提供训练代码、训练数据集、预训练模型与评估脚本；
• SCRFD (Arxiv'2021)：高效高精度检测方法（ICLR-2022），提供带 NAS 支持的训练管线；
• blazeface_paddle：Paddle 实现。

SCRFD 性能对照

SCRFD 精度、FLOPs 与推理时间均在 VGA 分辨率下评测（见 detection/scrfd/README.md）：

Method	Backbone	Easy	Medium	Hard	#Params(M)	#Flops(G)	Infer(ms)
RetinaFace (CVPR20)	ResNet50	94.92	91.90	64.17	29.50	37.59	21.7
SCRFD-34GF	Bottleneck Res	96.06	94.92	85.29	9.80	34.13	11.7
SCRFD-10GF	Basic Res	95.16	93.87	83.05	3.86	9.98	4.9
SCRFD-2.5GF	Basic Res	93.78	92.16	77.87	0.67	2.53	4.2
SCRFD-0.5GF	Depth-wise Conv	90.57	88.12	68.51	0.57	0.508	3.6

其中 SCRFD-0.5GF 在 X64 CPU 单线程（AMD Ryzen 9 3950X，OMP_NUM_THREADS=1）下，640x480 输入约 28.3ms，320x240 约 11.4ms。

SCRFD 训练与评估

训练（4 卡示例，见 detection/scrfd/README.md）：

CUDA_VISIBLE_DEVICES="0,1,2,3" PORT=29701 bash ./tools/dist_train.sh ./configs/scrfd/scrfd_1g.py 4

WIDERFace 纯 Python 评估（无需 Matlab）：

GPU=0
GROUP=scrfd
TASK=scrfd_2.5g
CUDA_VISIBLE_DEVICES="$GPU" python -u tools/test_widerface.py ./configs/"$GROUP"/"$TASK".py ./work_dirs/"$TASK"/model.pth --mode 0 --out wouts

训练数据按 WIDERFace 的 data/retinaface/{train,val} 目录布局准备，标注格式为每图一行 bbox_x1 bbox_y1 bbox_x2 bbox_y2 (<keypoint,3>*N)，关键点可省略（仅框标注也可训练）。模型转 ONNX 可用 detection/scrfd/tools/scrfd2onnx.py。

人脸对齐模块：SDUNets 与 SimpleRegression

alignment 模块提供数据集与训练/推理管线：

• SDUNets (BMVC'2018)：基于热图的方法，训练/推理代码见 alignment/heatmap/train.py 与 alignment/heatmap/test.py；
• SimpleRegression：轻量坐标回归模型，输入为松裁剪人脸图，直接输出关键点坐标，推理示例见 alignment/coordinate_reg/image_infer.py。

模型 Zoo 中对齐模型包括 2D 106 点（MobileNet-0.5，1.2M 参数）与 3D 68 点（ResNet-50，34.2M 参数）两类（见 model_zoo/README.md）。

换脸示例：inswapper

examples/in_swapper 提供单行代码的与身份无关（subject agnostic）换脸——把源人脸身份迁移到目标人脸，输入输出分辨率为 128x128：

1. 安装 insightface>=0.7：pip install -U insightface；
2. 下载 inswapper_128.onnx 换脸模型放到 ~/.insightface/models/；
3. 使用 buffalo_l 包中的识别模型初始化 INSwapper 类。

注意：目前仅接受 buffalo_l arcface 模型产出的潜在编码，否则换脸结果不正常。完整代码见 examples/in_swapper/inswapper_main.py。官方提示该 demo 已不再维护，更高分辨率换脸请使用 Picsi.Ai 产品。

许可证与使用边界

InsightFace 的代码基于 MIT License 发布，学术与商业使用均无限制；但包含标注的训练数据（以及基于这些数据训练的模型）仅可用于非商业研究用途（见 README.md）。无论是从仓库手动下载模型，还是通过 Python 库自动下载模型，均遵循非商业研究许可。

2025-11-24 更新明确了三类授权联系渠道：换脸系列模型（如 inswapper_128.onnx）联系 [e-mail]；开源人脸识别模型（如 buffalo_l 包）联系 [e-mail]；高级识别 SDK 与模型（如 InspireFace SDK）联系 [e-mail]。模型许可与 Server 源码许可相互独立，部署 Server 前需确认所用模型的授权状态。

引用

若 InsightFace 对你的研究有帮助，可参考 README.md 中的引用列表，核心论文包括：ArcFace（CVPR'2019）、RetinaFace（CVPR'2020）、Sub-center ArcFace（ECCV'2020）、Partial FC（CVPR'2022 及 ICCVW'2021）、Stacked Dense U-Nets（BMVC'2018）、SCRFD 的 Sample and Computation Redistribution（arXiv:2105.04714）、OSTeC（CVPR'2021）与 PBIDR（FG'2023）等。

总结

InsightFace 以"训练 + 部署"双优化的思路，将人脸识别（ArcFace 多框架实现与 Partial FC 大规模训练）、检测（SCRFD 轻量高精度）、对齐（热图与坐标回归）乃至换脸、Server 部署整合进同一套 ONNX 推理生态：训练侧从 recognition 与 detection 出发复现 SOTA 方法，部署侧通过 FaceAnalysis 与 model_zoo.get_model() 一行接入。配合 InsightFace 1.0 的桌面 Evaluation Studio 与自托管 Server，从本地评估到企业级 1:N 搜索的完整链路均可在自有基础设施上闭环，是构建人脸分析应用的可靠开源基座。