# models

**Repository Path**: remindA/models

## Basic Information

- **Project Name**: models
- **Description**: 各种模型介绍说明
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 模型仓库文档

本仓库收录了用于人脸相关任务的预训练模型，分为 **InsightFace**（ONNX 格式，检测/识别/关键点/属性/换脸）与 **MediaPipe**（TFLite 格式，轻量检测）两大类别。

> 详细的检测类（detect）说明见 [`insightface/detect/说明.md`](insightface/detect/说明.md)，本文档在其基础上补全全量模型，并对比各类别下模型的异同。

---

## 目录

- [一、模型总览](#一模型总览)
- [二、InsightFace 各模型详解](#二insightface-各模型详解)
  - [2.1 人脸检测（detect）](#21-人脸检测detect)
  - [2.2 人脸识别 / 特征向量（embed）](#22-人脸识别--特征向量embed)
  - [2.3 关键点（key_point）](#23-关键点key_point)
  - [2.4 属性与换脸（根目录）](#24-属性与换脸根目录)
- [三、MediaPipe 模型详解](#三mediapipe-模型详解)
- [四、同类别下模型的异同对比](#四同类别下模型的异同对比)
  - [4.1 三组人脸检测模型对比](#41-三组人脸检测模型对比)
  - [4.2 三组识别（embed）模型对比](#42-三组识别embed模型对比)
  - [4.3 两组关键点模型对比](#43-两组关键点模型对比)
  - [4.4 InsightFace vs MediaPipe 检测对比](#44-insightface-vs-mediapipe-检测对比)
- [五、典型组合与选型建议](#五典型组合与选型建议)

---

## 一、模型总览

| 模型文件 | 类别 | 框架/格式 | 主要作用 |
| --- | --- | --- | --- |
| `det_500m.onnx` | 检测 | InsightFace / ONNX | 超轻量人脸检测（SCRFD_500M） |
| `det_2.5g.onnx` | 检测 | InsightFace / ONNX | 均衡人脸检测（SCRFD_2.5G），buffalo_m 默认 |
| `det_10g.onnx` | 检测 | InsightFace / ONNX | 高精度人脸检测（SCRFD_10G），buffalo_l 默认 |
| `scrfd_10g_bnkps.onnx` | 检测 | InsightFace / ONNX | 高精度 + 5 点关键点（SCRFD_10G_KPS），antelopev2 |
| `scrfd_person_2.5g.onnx` | 检测 | InsightFace / ONNX | 人体（行人）检测，非人脸 |
| `glintr100.onnx` | 识别 | InsightFace / ONNX | 人脸识别特征提取（ArcFace, R100, 高精） |
| `w600k_r50.onnx` | 识别 | InsightFace / ONNX | 人脸识别特征提取（ResNet50） |
| `w600k_mbf.onnx` | 识别 | InsightFace / ONNX | 人脸识别特征提取（MobileFaceNet，轻量） |
| `1k3d68.onnx` | 关键点 | InsightFace / ONNX | 3D 68 点人脸关键点 |
| `2d106det.onnx` | 关键点 | InsightFace / ONNX | 2D 106 点人脸关键点 |
| `genderage.onnx` | 属性 | InsightFace / ONNX | 性别 + 年龄估计 |
| `inswapper_128.onnx` | 换脸 | InsightFace / ONNX | 人脸交换（Face Swapping） |
| `blaze_face_short_range.tflite` | 检测 | MediaPipe / TFLite | 短距离人脸检测（移动端/实时） |

---

## 二、InsightFace 各模型详解

### 2.1 人脸检测（detect）

基于 **SCRFD**（Sample and Cascade Relevance Filtering Detector）系列，统一输出人脸框 `[x1,y1,x2,y2,score]` 与 5 点关键点（部分版本）。

详细精度、架构、速度对比见 [`insightface/detect/说明.md`](insightface/detect/说明.md)，要点如下：

- **`det_500m.onnx`** — 超轻量首选。FLOPs 仅 500M，体积 ~2.4MB，适合 ARM/NPU/移动端。缺点：小脸、侧脸、遮挡场景能力弱。
- **`det_2.5g.onnx`** — 均衡之选。FLOPs 2.5G，体积 ~3.3MB，速度精度兼顾，是 `buffalo_m` 模型包的默认检测器。
- **`det_10g.onnx`** — 高精度标准版。FLOPs 10G，体积 ~16.9MB，WIDERFace Hard 达 83.05%，是 `buffalo_l` 默认检测器。
- **`scrfd_10g_bnkps.onnx`** — 增强关键点版。与 `det_10g` 同属 10G 级别，但额外输出 5 点关键点用于人脸对齐，属 `antelopev2` 包，Easy/Medium 精度略高（95.40 vs 95.16）。`bnkps` = Backbone + KeyPoints。
  > 注意：原始 SCRFD 存在大人脸（占图 >40%）置信度骤降的 bug，社区有 `gnkps`（GroupNorm 修复）版本。
- **`scrfd_person_2.5g.onnx`** — 特殊检测模型，**不是人脸检测**，而是 **行人/人体检测**（person detection），用于需要区分人/脸或对全身做检测的场景。

### 2.2 人脸识别 / 特征向量（embed）

将人脸对齐后裁剪的图像映射为固定维度向量（embedding），通过余弦相似度比对身份。均基于 **ArcFace** 损失训练。

- **`glintr100.onnx`** — 基于 **ResNet100（R100）** 骨干，训练于大规模数据集（如 Glint360K），精度最高，用于追求最强识别性能的服务端，常配合 `scrfd_10g_bnkps` 或 `det_10g` 使用。
- **`w600k_r50.onnx`** — 基于 **ResNet50（R50）** 骨干，训练于 WebFace600K（w600k）。精度略低于 R100，但体积与耗时明显更小，是 `buffalo_l` / `buffalo_m` 的常用识别头。
- **`w600k_mbf.onnx`** — 基于 **MobileFaceNet（MBF）** 骨干，轻量模型。精度最低但体积极小、推理最快，适合移动端/实时识别。

> 三者输出均为 512 维（R100/R50）或相近维度向量，需与检测 + 对齐（5 点关键点）配合形成完整识别 pipeline。

### 2.3 关键点（key_point）

用于人脸对齐与精细面部几何定位，需在已检测到人脸的基础上运行。

- **`1k3d68.onnx`** — 输出 **3D 68 点** 关键点（含深度信息），适合 3D 人脸重建、姿态估计、3D 对齐。
- **`2d106det.onnx`** — 输出 **2D 106 点** 关键点（平面坐标，密点），适合美颜、妆容、精细 2D 对齐。

### 2.4 属性与换脸（根目录）

- **`genderage.onnx`** — 输入对齐后的人脸，输出 **性别**（男/女）与 **年龄** 估计，用于人脸属性分析，常与检测 + 识别串联。
- **`inswapper_128.onnx`** — **人脸交换（Face Swapping）** 模型，输入源人脸 + 目标人脸，输出将源人脸身份迁移到目标姿态/表情上的图像。本质是生成式模型，与前几类判别式模型用途不同。

---

## 三、MediaPipe 模型详解

- **`blaze_face_short_range.tflite`** — Google MediaPipe 的 **BlazeFace** 短距离人脸检测器，TFLite 格式。专为 **近距离、自拍、前置摄像头** 场景优化，检测范围小但速度快、体积小，可在手机/浏览器实时运行。
  - 输出人脸框 + 6 个关键点（双眼、双耳、鼻、嘴）。
  - 局限：远距离/小脸场景表现差（short_range 设计所致），通用性弱于 SCRFD 系列。

---

## 四、同类别下模型的异同对比

### 4.1 三组人脸检测模型对比

| 维度 | det_500m | det_2.5g | det_10g / scrfd_10g_bnkps |
| --- | --- | --- | --- |
| FLOPs | 500M | 2.5G | 10G |
| 骨干 | MobileNetV1 | ResNetV1e[3,5,3,2] | ResNetV1e[3,4,2,3] |
| 精度(Hard mAP) | 68.51 | 77.87 | 83.05 / 82.80 |
| 速度 | 最快 | 中等 | 较慢 |
| 关键点 | 5点(部分) | 5点 | 5点(bnkps) |
| 适用 | 移动/边缘 | 均衡 | 服务端高精 |
| 异同 | 同属 SCRFD 单阶段检测器，架构一致，仅**骨干容量/FLOPs**不同；精度随容量递增，速度随容量递减。`scrfd_10g_bnkps` 与 `det_10g` 几乎同构，区别仅在是否显式输出关键点与略高 Easy/Medium 精度。 | | |

**返回数据格式异同与通用性：**

- **统一格式**：四个模型均输出同一套结构，下游解析代码完全通用：
  - **输出 1（人脸框）**：`[x1, y1, x2, y2, score]`，坐标基于**输入原图尺寸**（非归一化），score 为置信度。
  - **输出 2（5 点关键点）**：`[左眼, 右眼, 鼻尖, 左嘴角, 右嘴角]`，顺序固定，用于人脸对齐。
  - 后处理一致：置信度过滤 + IoU NMS 去重。
- **细微差异**：
  - `det_500m` / `det_2.5g` 在 InsightFace 标准包中通过 **app 层（如 `FaceAnalysis`）** 一并给出 5 点；原始裸 ONNX 输出排布可能因导出版本略有不同，但经官方 app 封装后格式一致。
  - `scrfd_10g_bnkps` 的 `bnkps` 后缀即"Backbone + KeyPoints"，**原生就带关键点输出分支**，与 `det_10g` 相比无需额外关键点模型即可对齐。
  - 原始 SCRFD 存在**大人脸（占图 >40%）置信度骤降**的已知 bug（所有检测模型共有），需在预处理（控制输入尺寸）或后处理规避。
- **是否通用**：
  - **完全通用**。四者输出语义、坐标空间、关键点顺序、后处理逻辑完全相同，切换检测模型只换文件、下游（对齐/识别/属性）代码零改动。
  - 唯一例外：`scrfd_person_2.5g` 是**人体检测**，输出为人/行人框，格式/用途与人脸检测不同，**不可直接接入人脸识别链路**（见下方差异点）。

**关键差异点**：`scrfd_person_2.5g` 是**人体检测**而非人脸检测，不属于上述对比，用于人/脸分离或全身检测需求。

### 4.2 三组识别（embed）模型对比

| 维度 | glintr100 | w600k_r50 | w600k_mbf |
| --- | --- | --- | --- |
| 骨干 | ResNet100 | ResNet50 | MobileFaceNet |
| 容量/精度 | 最高 | 中高 | 较低（轻量） |
| 速度/体积 | 最慢/最大 | 中等 | 最快/最小 |
| 训练集 | Glint360K | WebFace600K | WebFace600K |
| 输出维度 | 512 维 | 512 维 | 512 维 |
| 异同 | 三者均为 ArcFace 风格识别头，输出人脸 embedding，用法完全一致（检测→对齐→embed→余弦比对）。差异仅在**骨干深度**带来的精度/效率权衡。 | | |

**特征向量通用性与 FAISS 支持：**

- **输出向量一致性**：三者都输出 **512 维** 浮点特征向量（L2 归一化后的单位向量），且同属 ArcFace 度量空间，向量语义一致——同一张脸在三者下得到的向量都指向同一身份方向，仅精度不同。
- **是否通用 / 可混用**：
  - 三者**不能跨模型直接比较相似度**。由于训练集（Glint360K vs WebFace600K）、骨干（R100/R50/MBF）不同，向量落在不同的子空间，**同一对脸在 glintr100 与 w600k_r50 下的余弦相似度不可直接对比**，检索库必须用同一个模型构建和查询。
  - 但**工程层面完全通用**：输入格式（对齐后 112×112 BGR）、预处理、后处理（L2 归一化）、向量维度都一致，切换模型只需替换 ONNX 文件，上下游代码无需改动。
- **是否都支持 FAISS**：
  - **都支持**。FAISS 只关心"定长浮点向量 + 距离度量"，与具体模型无关。512 维向量可直接建库：
    - 精确检索：`IndexFlatIP`（内积 = 余弦相似度，因已 L2 归一化）；
    - 大规模近似：`IndexIVFFlat` / `IndexHNSWFlat`，用内积（IP）距离。
  - 选型建议：移动端/实时（w600k_mbf）库小可用 `IndexFlatIP`；服务端高精（glintr100/w600k_r50）大库用 `IndexIVFFlat` 平衡速度与召回。
  - 注意：换模型必须**重建索引**，不能把不同模型产出的向量混进同一个 FAISS 索引。

### 4.3 两组关键点模型对比

| 维度 | 1k3d68 | 2d106det |
| --- | --- | --- |
| 点数 | 68 | 106 |
| 维度 | 3D（含深度） | 2D（平面） |
| 用途 | 3D 重建/姿态/3D 对齐 | 美颜/妆容/2D 对齐 |
| 异同 | 都属于"已裁剪人脸上的关键点定位"模型，输入为人脸 ROI，输出密集/稀疏关键点；区别在**点数与是否有深度通道**，决定 2D 还是 3D 应用。 | |

### 4.4 InsightFace vs MediaPipe 检测对比

| 维度 | InsightFace (SCRFD) | MediaPipe (BlazeFace) |
| --- | --- | --- |
| 格式 | ONNX | TFLite |
| 通用性 | 强（远/近/小/大脸） | 弱（仅短距离/近距） |
| 精度 | 高（WIDERFace 基准强） | 中（近距离够用） |
| 部署 | 服务端/桌面为主 | 移动/浏览器/嵌入式为主 |
| 关键点 | 5 点 | 6 点 |
| 异同 | 两者都是轻量化单阶段人脸检测器，目标一致；差异在**生态与适用距离**——InsightFace 偏通用高精、可对接完整识别 pipeline，MediaPipe 偏超轻量、限定短距离实时预览。 | |

---

## 五、典型组合与选型建议

| 需求 | 推荐组合 |
| --- | --- |
| 移动端实时人脸检测预览 | `det_500m` 或 `blaze_face_short_range.tflite` |
| 移动端人脸识别（轻量） | `det_2.5g` + `w600k_mbf` + 5点对齐 |
| 服务端通用人脸识别 | `det_10g` / `scrfd_10g_bnkps` + `w600k_r50` 或 `glintr100` |
| 最高识别精度 | `scrfd_10g_bnkps` + `glintr100`（antelopev2 思路） |
| 人脸属性分析 | 检测 + `genderage.onnx` |
| 人脸交换 | 检测 + 对齐 + `inswapper_128.onnx` |
| 3D 人脸相关 | 检测 + `1k3d68.onnx`（3D 68点） |
| 美颜/妆容 | 检测 + `2d106det.onnx`（2D 106点） |
| 人/脸分离或人体检测 | `scrfd_person_2.5g.onnx` |

> 完整识别 pipeline 通常为：**检测 → 5点关键点对齐 → embed 或 属性/关键点/换脸**。注意 `scrfd_person_2.5g` 与 `blaze_face_short_range` 用途特殊，不要与标准人脸识别链路混用。