FaceFound Android - 离线人脸识别移动端应用

项目介绍

FaceFound Android 是基于 InsightFace (buffalo_l) 和 ONNX Runtime Mobile 的高性能离线人脸识别 Android 应用。所有推理在设备端完成，无需网络连接，保护用户隐私。

项目地址：https://github.com/Enco-shark/facefound_android

功能特性

人脸检测 — SCRFD (det_10g) 多尺度锚点检测，输出边界框 + 5 点关键点
人脸对齐 — 5 点最小二乘相似变换，对齐到 ArcFace 标准 112x112 模板
人脸识别 — ArcFace (w600k_r50) 提取 512 维嵌入向量，余弦相似度匹配
模板管理 — 支持 .npz 格式模板导入，持久化存储，查看/重命名/删除
识别历史 — 自动保存识别时间、结果和耗时
结果保存 — 识别结果图片保存到系统相册
主题切换 — 深色/浅色主题
现代化 UI — Jetpack Compose + Material 3
离线运行 — 所有推理在设备端完成，无需网络

技术栈

库	版本	用途
ONNX Runtime	1.17.0	模型推理引擎（核心）
Jetpack Compose	BOM 2024.02.00	UI 框架
Material 3	(BOM 管理)	设计系统
Navigation Compose	2.7.7	页面导航
Coil	2.5.0	图片加载
Kotlin Coroutines	1.7.3	异步处理
Lifecycle Runtime KTX	2.7.0	生命周期管理
Activity Compose	1.8.2	Compose 集成

开发环境

项目	版本	说明
Android Studio	Giraffe (2023.1.1)+	推荐 Hedgehog 或更新
JDK	17	必须，不支持 JDK 8/11
Gradle	8.2	项目自带 wrapper
Android Gradle Plugin	8.2.2	构建插件
Kotlin	1.9.20	编译器版本
Android SDK	compileSdk 34	编译目标
minSdk	24	最低支持 Android 7.0
targetSdk	34	目标 Android 14

模型文件

文件	来源	大小	说明
`det_10g.onnx`	InsightFace buffalo_l	~170MB	SCRFD 人脸检测模型
`w600k_r50.onnx`	InsightFace buffalo_l	~65MB	ArcFace 人脸识别模型

模型文件需放置于 app/src/main/assets/ 目录。

构建教程

1. 安装开发环境

安装 JDK 17

1
2
3

# Windows: 下载 Adoptium JDK 17，安装后设置 JAVA_HOME
# 验证:
java -version  # 输出 17.x.x

安装 Android Studio

下载 Android Studio
安装时勾选 Android SDK，确保 SDK Platform 34 已安装
配置 SDK Manager: 勾选 Android 14 (API 34) 和 NDK

配置环境变量

1 2	ANDROID_HOME = C:\Users\<用户名>\AppData\Local\Android\Sdk Path 添加: %ANDROID_HOME%\platform-tools

2. 获取模型文件

# Python 方式获取模型
pip install insightface
python -c "import insightface; model = insightface.app.FaceAnalysis(name='buffalo_l'); model.prepare(ctx_id=-1)"
# 模型下载到 ~/.insightface/models/buffalo_l/

将模型复制到项目：

# Windows
xcopy /Y "%USERPROFILE%\.insightface\models\buffalo_l\det_10g.onnx" "app\src\main\assets\"
xcopy /Y "%USERPROFILE%\.insightface\models\buffalo_l\w600k_r50.onnx" "app\src\main\assets\"

# Linux/Mac
cp ~/.insightface/models/buffalo_l/det_10g.onnx app/src/main/assets/
cp ~/.insightface/models/buffalo_l/w600k_r50.onnx app/src/main/assets/

3. 导入与同步

打开 Android Studio → Open an Existing Project → 选择项目目录，等待 Gradle 同步完成。

4. 连接设备

手机开启 开发者选项 → USB 调试
USB 连接电脑，授权调试
Android Studio 顶部设备列表选择你的手机

5. 运行与构建

Android Studio 运行: 点击 ▶️ 或 Shift+F10

命令行构建:

# Windows PowerShell
.\gradlew.bat assembleDebug

# Linux/Mac
chmod +x gradlew
./gradlew assembleDebug

构建输出: app/build/outputs/apk/debug/app-debug.apk

Release 构建:

1	.\gradlew.bat assembleRelease

输出: app/build/outputs/apk/release/app-release-unsigned.apk

项目结构

android_project/
├── app/
│   ├── build.gradle.kts                    # 应用构建配置
│   ├── proguard-rules.pro                  # ProGuard 混淆规则
│   └── src/main/
│       ├── AndroidManifest.xml             # 应用清单
│       ├── assets/                         # 模型文件目录
│       │   ├── det_10g.onnx                #   人脸检测模型
│       │   └── w600k_r50.onnx              #   人脸识别模型
│       ├── java/com/Enco/facefound/
│       │   ├── MainActivity.kt             # 主 Activity
│       │   ├── FaceRecognitionApp.kt       # Application 类
│       │   ├── ml/
│       │   │   └── OnnxFaceRecognition.kt  # ★ 核心推理引擎
│       │   ├── ui/
│       │   │   ├── screens/
│       │   │   │   └── MainScreen.kt       # Compose 主界面
│       │   │   ├── theme/                  # 主题配置
│       │   │   └── viewmodel/
│       │   │       └── FaceRecognitionViewModel.kt
│       │   └── util/                       # 工具类

核心推理流程

摄像头/相册图片
    ↓
ONNX Runtime 加载 det_10g.onnx
    ↓
SCRFD 人脸检测 → 边界框 + 5 点关键点
    ↓
5 点相似变换对齐 → 112x112 标准模板
    ↓
ONNX Runtime 加载 w600k_r50.onnx
    ↓
ArcFace 特征提取 → 512 维嵌入向量
    ↓
与模板库余弦相似度匹配
    ↓
输出识别结果

性能优化

ONNX Runtime Mobile — 专为移动端优化的推理引擎
多线程处理 — 利用 Kotlin Coroutines 实现异步推理
模型量化 — 支持 INT8 量化，减小模型体积
内存管理 — 及时释放推理结果，避免 OOM

总结

FaceFound Android 是一款完全离线的人脸识别应用，适合：

门禁系统原型开发
照片智能分类
学习移动端 AI 推理技术
保护隐私的本地识别场景

欢迎 Star 和 PR！🌟

Enco的小站