简介：面向需要在 Android 端集成人脸识别能力的开发者，这份 SeetaFace6 DEMO 工程提供了一套可参考的完整项目结构，重点解决多 ABI 适配与本地 SO 库部署问题。工程同时包含 arm64-v8a 与 armeabi-v7a 两套预编译动态库，并配套 C++ 头文件、配置及数据文件、Java 调用示例与 Gradle 构建脚本，便于对照理解 JNI 接口和工程组织方式。压缩包共 565 个文件，以 hpp、h 头文件、xml 配置、so 库及 java 源码为主，整体约 146.83MB，目录按模块划分，检索与替换库文件较为方便。已有 756 人学习，适合具备一定 Android NDK 基础、希望快速验证人脸检测、关键点定位、人脸识别、活体检测、质量评估、年龄性别估计及口罩检测等能力的开发者参考。
1. 从一台旧 Android 机跑起：这套双 ABI 人脸识别 DEMO 到底能做什么
拿一台四年前的中端机，装上这个 Android 人脸识别 DEMO 工程，切到前置摄像头，画面里人脸框跟着走，关键点落在眼角和嘴角，识别结果在几百毫秒内刷出来。这套 SeetaFace6 的 Android DEMO 自带 arm64-v8a 和 armeabi-v7a 两套 so 库，相机预览、人脸检测、关键点定位、特征提取和 1:N 比对都有现成调用链。它适合想在人脸考勤、门禁、相册聚类里快速验证效果的 Android 开发，也适合手里有 32 位老设备、不想被只发 64 位 so 的 SDK 卡住的团队。别急着改模型，先把 demo 跑通，后面换阈值、加活体、抽 AAR 才有参照。
2. 工程骨架拆解：app、native、jniLibs 与 CMake 的四层结构
2.1 目录树与模块职责
这份 DEMO 的目录不复杂，但几个关键目录一旦放错，运行时就只会给你一个UnsatisfiedLinkError。常见结构如下，不同 Android Studio 版本可能多一层cpp或jni，职责基本一致。
app/ src/main/ java/com/example/facedemo/ MainActivity.java # 相机预览、权限、按钮交互 FaceEngine.java # native 方法声明与 Java 层封装 FaceResult.java # 检测框、关键点、相似度结果 cpp/ face_jni.cpp # JNI 入口，桥接 Java 与 C++ face_engine.cpp # 检测、关键点、识别器生命周期 CMakeLists.txt # 编译 native 库 jniLibs/ arm64-v8a/ libseeta_facedetector.so libseeta_facelandmarker.so libseeta_facerecognizer.so libseeta_faceengine.so armeabi-v7a/ libseeta_facedetector.so libseeta_facelandmarker.so libseeta_facerecognizer.so libseeta_faceengine.so assets/ models/ face_detector.csta face_landmarker_pts5.csta face_recognizer.cstajniLibs下按 ABI 分目录，这是 Android 打包 so 的默认规则。arm64-v8a给 64 位设备，armeabi-v7a给仍在流通的 32 位设备。assets/models放模型文件，安装后不能直接当文件路径用，常见做法是首次启动时拷贝到filesDir再传给 native。cpp目录只负责 JNI 和引擎封装，不把业务逻辑塞进MainActivity，否则后面抽 AAR 会很痛苦。
我一般会先看jniLibs里两套 ABI 的 so 数量是否一致。如果arm64-v8a有 8 个 so，armeabi-v7a只有 6 个，运行到 32 位设备上大概率在System.loadLibrary阶段就崩。这个目录树的价值不是好看，而是让你在构建前就能发现缺库。
2.2 Gradle 里 ABIs 与 so 库的挂载方式
老工程常见用abiFilters控制打包，新工程可能用splits或packaging。核心是别让 Gradle 把不需要的 ABI 打进去，也别把jniLibs排除掉。
android { defaultConfig { ndk { // 只保留工程实际提供的两套 ABI abiFilters 'arm64-v8a', 'armeabi-v7a' } } sourceSets { main { // 默认就会读 src/main/jniLibs，这里显式写出来便于排查 jniLibs.srcDirs = ['src/main/jniLibs'] } } packagingOptions { // 避免多个依赖携带同名 so 时冲突 pickFirst 'lib/arm64-v8a/libseeta_faceengine.so' pickFirst 'lib/armeabi-v7a/libseeta_faceengine.so' } }abiFilters里写两个 ABI，打出来的 APK 会同时包含两套 so，包体会变大，但换来老设备兼容。pickFirst只在依赖冲突时用，不要无脑加，否则可能把正确版本盖掉。jniLibs.srcDirs显式声明后，Android Studio 的 Build 输出里能看到mergeDebugJniLibFolders任务，排查缺库时直接看这个任务有没有把两套目录都合进去。
另一个容易忽略的点是 16KB 页对齐。新系统对 so 的段对齐有要求，如果 so 是旧工具链编的，安装时可能报INSTALL_FAILED_INVALID_APK或运行时加载失败。常见做法是用 NDK r27 以上重新链接，或者在CMakeLists.txt里加链接参数。这个坑在双 ABI 工程里更明显，因为 32 位 so 往往是历史产物。
2.3 主 Activity 的相机预览链路
DEMO 里相机部分通常是 CameraX 的ImageAnalysis，因为拿到ImageProxy后可以转 NV21 或直接转 RGB。下面这段是常见写法，重点看setBackpressureStrategy和YUV_420_888的转换入口。
// MainActivity.java private void startCamera() { ListenableFuture<ProcessCameraProvider> future = ProcessCameraProvider.getInstance(this); future.addListener(() -> { try { ProcessCameraProvider provider = future.get(); Preview preview = new Preview.Builder().build(); ImageAnalysis analysis = new ImageAnalysis.Builder() // 只保留最新帧，避免排队导致预览延迟 .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST) .setTargetResolution(new Size(640, 480)) .build(); analysis.setAnalyzer(executor, image -> { // 这里不要直接跑识别，先转成引擎需要的格式 byte[] nv21 = ImageUtils.yuv420ToNv21(image); int rotation = image.getImageInfo().getRotationDegrees(); faceEngine.detectAndRecognize(nv21, image.getWidth(), image.getHeight(), rotation); image.close(); }); provider.unbindAll(); provider.bindToLifecycle(this, CameraSelector.DEFAULT_FRONT_CAMERA, preview, analysis); } catch (Exception e) { Log.e(TAG, "camera bind failed", e); } }, ContextCompat.getMainExecutor(this)); }STRATEGY_KEEP_ONLY_LATEST很关键，人脸检测一帧几十毫秒，如果相机每秒出 30 帧而分析器排队，预览会越来越滞后。setTargetResolution(640, 480)是常见折中，太大检测慢，太小远景脸丢关键点。rotation必须传下去，前置摄像头还有镜像问题，不处理会出现检测框左右反。image.close()一定要在分析结束调用，否则相机会卡住。
这段链路只负责“拿到帧并送进引擎”，识别结果通过回调或runOnUiThread刷到预览层。不要把模型加载放在onCreate里同步做，首次拷贝模型可能几百毫秒，主线程会白屏。常见做法是开一个Executors.newSingleThreadExecutor()做初始化，UI 上先显示“引擎加载中”。
3. JNI 桥接与 so 加载：从 System.loadLibrary 到 native 句柄
3.1 native 方法签名与 Java 层封装
Java 层不要直接把所有 native 方法散在 Activity 里，抽一个FaceEngine类，方法签名和 C++ 侧严格对应。包名、类名、方法名任何一处改动，JNI 注册就会失败。
// FaceEngine.java package com.example.facedemo; public class FaceEngine { static { // 顺序很重要：被依赖的库先加载 System.loadLibrary("seeta_facedetector"); System.loadLibrary("seeta_facelandmarker"); System.loadLibrary("seeta_facerecognizer"); System.loadLibrary("seeta_faceengine"); } private long nativeHandle; public native boolean nativeInit(String modelDir); public native FaceResult[] nativeDetect(byte[] nv21, int width, int height, int rotation); public native float nativeCompare(byte[] feature1, byte[] feature2); public native void nativeRelease(); }static块里的加载顺序不是随便写的。seeta_faceengine依赖检测器、关键点、识别器三个 so，如果先加载引擎库，动态链接器找不到符号，会报dlopen failed: library "libseeta_facedetector.so" not found或cannot locate symbol。nativeHandle用long存 C++ 对象指针，避免 Java 层直接持有 native 内存。nativeInit传模型目录，nativeDetect传 NV21 字节数组、宽高和旋转角，nativeCompare传两个特征字节数组。参数类型要和 C++ 的jbyteArray、jint对上，别用int[]接 NV21。
签名一旦确定，nativeInit里要做三件事：创建检测器、创建关键点定位器、创建识别器。任何一步失败都返回false，Java 层据此提示“模型加载失败”，而不是让空指针在 native 里崩掉。
3.2 so 库加载顺序与 ABI 选择
System.loadLibrary("seeta_faceengine")会按当前进程的 ABI 去jniLibs里找libseeta_faceengine.so。64 位进程找arm64-v8a，32 位进程找armeabi-v7a。如果只放了一套，另一套设备安装后运行就崩。
// 排查当前进程 ABI 的常用写法 private String currentAbi() { if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) { for (String abi : Build.SUPPORTED_ABIS) { if ("arm64-v8a".equals(abi) || "armeabi-v7a".equals(abi)) { return abi; } } } return Build.CPU_ABI; }Build.SUPPORTED_ABIS返回顺序是从首选到次选，64 位设备通常第一个是arm64-v8a。如果 APK 里只有armeabi-v7a，系统会以 32 位模式运行，这时arm64-v8a的 so 不会被加载。双 ABI 工程的价值就在这里：同一份 APK 在两种设备上都能跑。但要注意，如果某个第三方依赖只带了arm64-v8a，Gradle 合并后 32 位包可能缺库，abiFilters要结合实际依赖检查。
我一般会在Application.onCreate里打一条日志，把SUPPORTED_ABIS和applicationInfo.nativeLibraryDir打出来。nativeLibraryDir能直接告诉你系统从哪个目录加载 so，排查“明明放了库却找不到”时非常省时间。
3.3 C++ 侧初始化与模型文件路径
模型文件在assets里，native 不能直接读。常见做法是 Java 层首次启动时把assets/models拷贝到getFilesDir()/models，再把绝对路径传给nativeInit。
// face_jni.cpp extern "C" JNIEXPORT jboolean JNICALL Java_com_example_facedemo_FaceEngine_nativeInit( JNIEnv* env, jobject thiz, jstring modelDir) { const char* dir = env->GetStringUTFChars(modelDir, nullptr); if (dir == nullptr) { return JNI_FALSE; } std::string base(dir); env->ReleaseStringUTFChars(modelDir, dir); // 模型文件名要和 assets 里保持一致 std::string detectorPath = base + "/face_detector.csta"; std::string landmarkerPath = base + "/face_landmarker_pts5.csta"; std::string recognizerPath = base + "/face_recognizer.csta"; auto* engine = new FaceEngineWrapper(); bool ok = engine->init(detectorPath, landmarkerPath, recognizerPath); if (!ok) { delete engine; return JNI_FALSE; } // 把 native 指针塞回 Java 的 long 字段 jclass clazz = env->GetObjectClass(thiz); jfieldID field = env->GetFieldID(clazz, "nativeHandle", "J"); env->SetLongField(thiz, field, reinterpret_cast<jlong>(engine)); return JNI_TRUE; }GetStringUTFChars和ReleaseStringUTFChars必须成对，否则有内存泄漏。FaceEngineWrapper里持有检测器、关键点、识别器三个对象，init里依次调用各自的构造或加载方法。模型路径用std::string拼接，不要用sprintf拼固定长度缓冲区。nativeHandle的字段签名是J，对应 Java 的long，写错会抛NoSuchFieldError。
nativeRelease里要delete这个指针，并把 Java 字段置 0。如果 Activity 销毁时不释放，反复进出页面会累积 native 内存。常见做法是在FaceEngine里加一个release()，内部判断nativeHandle != 0再调 native，避免重复释放。
4. 人脸检测与识别主链路：一帧 NV21 数据怎么走完检测、关键点和对齐
4.1 帧数据格式转换与旋转处理
CameraX 的ImageAnalysis默认给YUV_420_888，而很多人脸引擎接口吃 NV21。转换时要注意rowStride和pixelStride，不同机型不一致，直接按宽高拷会花屏。
// ImageUtils.java public static byte[] yuv420ToNv21(ImageProxy image) { ImageProxy.PlaneProxy[] planes = image.getPlanes(); ByteBuffer yBuffer = planes[0].getBuffer(); ByteBuffer uBuffer = planes[1].getBuffer(); ByteBuffer vBuffer = planes[2].getBuffer(); int ySize = yBuffer.remaining(); int uSize = uBuffer.remaining(); int vSize = vBuffer.remaining(); byte[] nv21 = new byte[ySize + uSize + vSize]; yBuffer.get(nv21, 0, ySize); // NV21 是 VU 交错，先 V 后 U vBuffer.get(nv21, ySize, vSize); uBuffer.get(nv21, ySize + vSize, uSize); return nv21; }这段是最简版本，适合rowStride等于宽度的机型。如果遇到预览花屏，先把image.getWidth()、getHeight()、每个 plane 的rowStride打出来。有些设备 Y 平面有 padding，需要按行拷贝。rotation从image.getImageInfo().getRotationDegrees()拿，前置摄像头还要判断是否镜像。常见做法是旋转和镜像都在 native 里做，Java 只传原始 NV21 和角度，减少一次大数组拷贝。
4.2 检测、关键点、特征提取的调用顺序
一帧数据的处理顺序是：检测人脸框 → 对每个人脸定位关键点 → 根据关键点对齐 → 提取特征。顺序不能反，关键点依赖检测框，特征依赖对齐后的人脸。
// face_engine.cpp FaceResultList FaceEngineWrapper::detectAndRecognize( const uint8_t* nv21, int width, int height, int rotation) { // 1. 转成引擎需要的 RGB 或灰度图 SeetaImageData image = convertToSeetaImage(nv21, width, height, rotation); // 2. 检测人脸，返回框和置信度 std::vector<SeetaFaceInfo> faces = detector.detect(image); FaceResultList results; for (const auto& face : faces) { // 3. 五点关键点定位 std::vector<SeetaPointF> points = landmarker.mark(image, face.pos); if (points.size() < 5) { continue; } // 4. 根据关键点对齐，得到 256x256 的人脸图 SeetaImageData aligned = alignFace(image, points); // 5. 提取特征 std::vector<float> feature = recognizer.Extract(aligned); results.push_back(makeResult(face, points, feature)); } return results; }detector.detect返回的face.pos是矩形框，landmarker.mark需要原图和框。alignFace通常做相似变换，把眼睛、鼻子、嘴角对齐到固定位置。recognizer.Extract输出固定长度特征向量，常见是 1024 维 float。如果检测不到人脸，直接返回空列表，不要在对齐阶段对空框做运算。
4.3 识别阈值与结果封装
1:1 比对用余弦相似度或欧氏距离，1:N 识别要维护特征库。阈值不要拍脑袋，常见起点是 0.6 到 0.7，具体看模型和场景。
// FaceResult.java public class FaceResult { public final Rect rect; public final float[] landmarks; // 10 个 float，5 个点 public final byte[] feature; public final float similarity; public FaceResult(Rect rect, float[] landmarks, byte[] feature, float similarity) { this.rect = rect; this.landmarks = landmarks; this.feature = feature; this.similarity = similarity; } public boolean isSamePerson(float threshold) { // 相似度高于阈值才认为同一人 return similarity >= threshold; } }feature用byte[]传回 Java 是为了方便存数据库或做网络传输，实际比对时在 native 里转成float*。similarity是当前帧和特征库里最相似那条的得分。阈值调低会提高通过率，但误识也会上来；调高则相反。门禁场景一般偏严，相册聚类可以偏松。这个参数最好放到配置里，别写死在if里。
5. 避坑与排查：双 ABI、模型路径、16KB 页对齐和相机方向
5.1 so 加载与 ABI 相关的崩溃
现象一：64 位真机安装后一打开就闪退，日志里是java.lang.UnsatisfiedLinkError: dlopen failed: library "libseeta_faceengine.so" not found。
原因：APK 里只打进了armeabi-v7a，或者jniLibs目录名写成了arm64、armeabi-v7a/下少了某个依赖 so。
解决：解压 APK 看lib/下有没有arm64-v8a和armeabi-v7a两个目录，数量是否一致。Gradle 里确认abiFilters没把 64 位过滤掉，sourceSets.jniLibs.srcDirs指向正确。如果是依赖冲突，用pickFirst前先看./gradlew app:dependencies里谁带了同名库。
现象二：32 位老设备能装但跑起来报cannot locate symbol "__android_log_print"或某个 C++ 符号缺失。
原因：so 编译时链接了不同版本的 NDK 运行时，或者 32 位 so 依赖了未打包的第三方库。
解决：用readelf -d libseeta_faceengine.so看NEEDED列表，确认每个依赖都在jniLibs里。统一用同一套 NDK 重新编译，别把不同来源的 so 混放。32 位 so 还要注意 16KB 页对齐，旧工具链产物在新系统上可能加载失败。
5.2 模型、权限与混淆导致的静默失败
现象三：nativeInit返回false，但日志里没有明显异常，相机预览正常，就是不出检测框。
原因：assets/models拷贝到filesDir时文件名大小写不一致，或者拷贝没完成就调了初始化。
解决：在nativeInit前打印模型目录和每个文件的length()，为 0 就是没拷过去。拷贝放在Executors里，完成后再回调初始化。模型文件名不要改，face_landmarker_pts5.csta和face_landmarker_pts68.csta是不同模型，混用会关键点数量不对。
现象四：Debug 包正常，Release 包一调 native 就崩，报NoSuchMethodError。
原因：混淆把FaceEngine的类名或 native 方法名改了，JNI 按原名找不到。
解决：在proguard-rules.pro里保留类和 native 方法：-keep class com.example.facedemo.FaceEngine { native <methods>; }。同时保留FaceResult的字段，避免结果解析空指针。
5.3 预览方向与帧格式的现场排查
现象五：前置摄像头检测框左右相反，或者人脸旋转 90 度后关键点全错。
原因：只传了rotation没处理镜像，或者 NV21 转换时 U/V 顺序反了。
解决：前置摄像头在 native 里做水平翻转，或者 Java 层对 NV21 做镜像。先用一张静态图测试转换函数，确认yuv420ToNv21出来的图在 ImageView 里颜色正常，再进检测。rotation为 90 或 270 时，宽高要交换，别把原图宽高直接传给引擎。
注意：双 ABI 工程排查时，先确认当前进程 ABI，再看
nativeLibraryDir里实际加载了哪些 so，最后才去看模型。顺序反了容易在错误的方向上耗时间。
6. 二次开发：换模型、加活体检测、抽成 AAR 的三个改造方向
第一个方向是换模型和调阈值。检测器、关键点、识别器是分开加载的，换face_recognizer.csta后特征维度可能变，nativeCompare里的循环要跟着改。阈值别只改一个全局变量，我一般按场景拆成detectThreshold、similarityThreshold、landmarkQualityThreshold三个，前两个控制召回和误识，第三个过滤侧脸和遮挡。
第二个方向是加活体检测。DEMO 里没有活体模块时，常见做法是在检测到人脸后加动作指令，比如转头、眨眼，用关键点位移做简单判断；或者接一个静默活体 so，把 RGB 帧同时送进活体和识别两条链路。注意活体模型也会占 ABI，jniLibs两套目录都要补齐，否则又回到 32 位设备崩的老路。
第三个方向是抽 AAR。把FaceEngine、FaceResult、jniLibs、assets/models从 app 模块挪到face-sdk模块，对外只暴露初始化和检测接口。Gradle 里用api而不是implementation暴露必要类，consumerProguardFiles带上混淆规则。抽完后用一个空 app 依赖 AAR 跑一遍双 ABI 真机，确认模型拷贝和 so 加载都不依赖原 DEMO 的MainActivity。
| 改造方向 | 主要改动 | 验证重点 |
|---|---|---|
| 换模型 | 替换 assets 模型、调整特征维度 | 关键点数量、特征长度、阈值 |
| 加活体 | 增加活体 so 和调用链 | 双 ABI 是否齐全、帧率是否掉 |
| 抽 AAR | 模块拆分、混淆规则外置 | 空工程依赖后能否初始化 |
血泪经验是：每次改完jniLibs或CMakeLists.txt，先./gradlew clean再装包，别信增量编译。从那以后我每次动 so 目录，都强制走一遍“解压 APK 看 lib 目录 → 真机看 nativeLibraryDir → 跑一张静态图”的流程，再谈业务效果。希望帮到你。
本文还有配套的精品资源，点击获取
