Glance 模型转换实战:如何把 InsightFace ArcFace 权重转为 Core ML,打造 Mac 人脸解锁

原创2026-10-11 13:35:58711 阅读
文章标签:桌面应用计算机视觉人工智能身份认证应用安全

Glance 模型转换实战:如何把 InsightFace ArcFace 权重转为 Core ML,打造 Mac 人脸解锁

Glance 是一个 Mac 人脸解锁应用,它把 InsightFace 的 ArcFace 识别权重转换为 Core ML 模型,驱动本地人脸解锁。本文用 Glance 仓库里现成的转换脚本作为教材,带你完整走一遍「InsightFace ArcFace 权重 → Core ML 模型」的实战流程:为什么需要转换、管道如何工作、如何一键运行、以及那个保命的数值一致性验证。

Glance Mac人脸解锁应用图标

为什么要把 ArcFace 权重转成 Core ML?

Glance 的体验是「看一眼屏幕,Mac 就解锁」。核心动作是:把摄像头里的人脸变成一个 512 维数字向量(embedding,即人脸的数学指纹),再和你注册时存下的向量比相似度。

这个「人脸 → 向量」的活儿由 InsightFace 的 ArcFace 模型完成——用 MobileFaceNet 骨干网训练,识别能力经过大规模验证。但 ArcFace 官方发布的是 ONNX 格式权重,而 macOS 上原生能跑、还能调用 Apple 神经引擎(Neural Engine)推理的格式是 Core ML。所以中间必须做一步格式转换。

在 Glance 的解锁管线里,模型的位置是:

  1. 摄像头帧 → Vision 检测人脸
  2. FaceAligner.swift 按标准 ArcFace 模板把人脸对齐、缩放为 112×112(FaceAligner.swift 中 outputSize = 112)
  3. ArcFaceEmbedder.swift 把对齐后的图喂给 Core ML 模型,得到 512 维向量并做 L2 归一化
  4. 与已注册身份比对,高于阈值才算「是你」

也就是说:转换脚本产出的模型文件,就是整条 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 内置了一个真正的正确性检查:

  1. 生成一张 112×112 的随机像素图
  2. 同一张图分别喂给原始 ONNX 模型和转换后的 Core ML 模型
  3. 计算两组 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 模型转换这一步必须做对。

小结:核心要点清单

  1. ArcFace 官方是 ONNX 格式,macOS 本地推理用 Core ML,中间需要转换
  2. Glance 的管道:ONNX → onnx2torch → TorchScript → coremltools,预处理 (px-127.5)/127.5 直接烘焙进模型
  3. 输入契约 112×112 RGB、输出契约 512 维未归一化向量,两端都写得很严格
  4. 必须跑通余弦相似度 > 0.999 的数值一致性验证,这是判断转换正确与否的唯一标准
  5. 产物 glance/Models/ArcFace.mlpackage 提交入库,Xcode 构建时自动编译为 .mlmodelc 随 App 分发
登录后查看全文
glance