Glance 模型转换实战:如何把 InsightFace ArcFace 权重转为 Core ML,打造 Mac 人脸解锁
Glance 模型转换实战:如何把 InsightFace ArcFace 权重转为 Core ML,打造 Mac 人脸解锁
Glance 是一个 Mac 人脸解锁应用,它把 InsightFace 的 ArcFace 识别权重转换为 Core ML 模型,驱动本地人脸解锁。本文用 Glance 仓库里现成的转换脚本作为教材,带你完整走一遍「InsightFace ArcFace 权重 → Core ML 模型」的实战流程:为什么需要转换、管道如何工作、如何一键运行、以及那个保命的数值一致性验证。
为什么要把 ArcFace 权重转成 Core ML?
Glance 的体验是「看一眼屏幕,Mac 就解锁」。核心动作是:把摄像头里的人脸变成一个 512 维数字向量(embedding,即人脸的数学指纹),再和你注册时存下的向量比相似度。
这个「人脸 → 向量」的活儿由 InsightFace 的 ArcFace 模型完成——用 MobileFaceNet 骨干网训练,识别能力经过大规模验证。但 ArcFace 官方发布的是 ONNX 格式权重,而 macOS 上原生能跑、还能调用 Apple 神经引擎(Neural Engine)推理的格式是 Core ML。所以中间必须做一步格式转换。
在 Glance 的解锁管线里,模型的位置是:
- 摄像头帧 → Vision 检测人脸
- FaceAligner.swift 按标准 ArcFace 模板把人脸对齐、缩放为 112×112(FaceAligner.swift 中
outputSize = 112) - ArcFaceEmbedder.swift 把对齐后的图喂给 Core ML 模型,得到 512 维向量并做 L2 归一化
- 与已注册身份比对,高于阈值才算「是你」
也就是说:转换脚本产出的模型文件,就是整条 Mac 人脸解锁链路的心脏。
三步转换管道:ONNX → torch → Core ML
Glance 的转换脚本 tools/convert_arcface.py 走的是这样一条管道:
ONNX (InsightFace 官方权重)
│ onnx2torch
▼
Torch 模型 ──torch.jit.trace──▶ TorchScript
│ coremltools.convert
▼
ArcFace.mlpackage (Core ML)
| 步骤 | 工具 | 做了什么 |
|---|---|---|
| 1. ONNX → torch | onnx2torch | 把 ONNX 计算图转成 PyTorch 模型,方便后续追踪 |
| 2. torch → TorchScript | torch.jit.trace |
用随机输入跑一遍,记录出静态计算图(convert_arcface.py) |
| 3. TorchScript → Core ML | coremltools | 生成 .mlpackage,并把预处理烘焙进模型 |
第三步最值得关注:转换时把归一化参数 (px - 127.5) / 127.5 和 RGB 通道顺序直接写进了 Core ML 模型(convert_arcface.py 的 scale / bias / color_layout)。这样一来,Swift 端只要递上一张原始 RGB 112×112 图片即可,不用自己写任何预处理代码——预处理错误正是模型转换里最常见的「静默翻车」来源。
一键运行:实战四步走
环境要求:macOS 15+,Python 3.9+(脚本见 tools/requirements.txt:coremltools、torch、onnx2torch、insightface 等)。
第 1 步:拿到代码
git clone https://gitcode.com/gh_mirrors/glance21/glance
cd glance
第 2 步:准备 Python 虚拟环境
python3 -m venv .venv
source .venv/bin/activate
pip install -r tools/requirements.txt
注意:首次安装会下载约 2GB 的 Python 工具链(torch、coremltools 等),耗时几分钟,属正常现象。
第 3 步:运行转换脚本
python tools/convert_arcface.py --variant w600k_mbf
脚本会依次:
- 自动通过 insightface 的 model zoo 下载官方
buffalo_s模型包(约 13MB 的w600k_mbf.onnx),缓存到~/.insightface/models/,下次秒过 - 执行上面的三步管道转换
- 自动跑数值一致性验证(见下一节,这是灵魂步骤)
- 保存产物到 glance/Models/ArcFace.mlpackage
第 4 步:接进 Xcode
glance/ 目录在 Xcode 工程里是文件系统同步组,.mlpackage 一般会自动出现;若没有,拖进 glance.xcodeproj 并勾选 glance 目标即可。Xcode 会在构建时把它编译成 .mlmodelc 打进 App,ArcFaceEmbedder.swift 运行时自动查找加载。
模型契约:Swift 端到底期待什么?
转换脚本和 Swift 端之间有一份「契约」(tools/README.md 第 55-65 行):
| 项目 | 约定 |
|---|---|
| 输入 | input_image,112×112 RGB 图像(CVPixelBuffer / CGImage) |
| 输出 | embedding,512 个浮点数,不做 L2 归一化(由 Swift 端负责) |
| 预处理 | 已烘焙进模型:(pixel - 127.5) / 127.5,RGB 通道序 |
| 精度 / 硬件 | FLOAT16 计算精度,computeUnits = .all 优先跑神经引擎(ArcFaceEmbedder.swift) |
Swift 端对契约执行得很严格:输入尺寸不是 112×112 直接抛错,提示你先跑 FaceAligner(ArcFaceEmbedder.swift);输出向量长度不是 512 也抛错(ArcFaceEmbedder.swift)。
灵魂步骤:数值一致性验证
「加载成功、跑起来了」≠「转对了」。通道顺序写反(RGB 写成 BGR)或缩放系数错一位,模型照样加载、照样输出 512 个数——只是那 512 个数是「看起来很像那么回事的垃圾」,识别率会崩掉且不报任何错。
所以 convert_arcface.py 内置了一个真正的正确性检查:
- 生成一张 112×112 的随机像素图
- 同一张图分别喂给原始 ONNX 模型和转换后的 Core ML 模型
- 计算两组 512 维输出的余弦相似度,要求 > 0.999 才算通过
ONNX vs Core ML cosine similarity: 0.999998 (expect > 0.999)
Parity check passed. The conversion is numerically correct.
验证失败时脚本会以错误退出并明确提示「模型不可用,不要接进项目」(convert_arcface.py)。这条经验值得抄进你自己的任何模型转换流程里。
进阶与排错
-
换更大的 ArcFace 变体:
--variant w600k_r50会用 ResNet50 骨干(buffalo_l包,约 166MB)。模型契约完全不变,只有文件体积和推理延迟变化(convert_arcface.py)。 -
自动下载权重失败:InsightFace 的模型托管偶尔搬家。手动下载
w600k_mbf.onnx后绕过自动下载:python tools/convert_arcface.py --onnx-path /path/to/w600k_mbf.onnx -
模型缺失时的行为:FaceRecognitionPipeline.swift 里,
ArcFaceEmbedder构造失败不会让 App 崩溃,而是降级到 Apple Vision 的 FeaturePrint 内核对人脸做向量——能跑,但精度明显下降。所以想拿到完整的 Glance 人脸解锁体验,ArcFace 模型转换这一步必须做对。
小结:核心要点清单
- ArcFace 官方是 ONNX 格式,macOS 本地推理用 Core ML,中间需要转换
- Glance 的管道:ONNX → onnx2torch → TorchScript → coremltools,预处理
(px-127.5)/127.5直接烘焙进模型 - 输入契约 112×112 RGB、输出契约 512 维未归一化向量,两端都写得很严格
- 必须跑通余弦相似度 > 0.999 的数值一致性验证,这是判断转换正确与否的唯一标准
- 产物 glance/Models/ArcFace.mlpackage 提交入库,Xcode 构建时自动编译为
.mlmodelc随 App 分发