简介这是一份面向Java开发者与计算机专业学生的「人脸识别签到系统」完整项目源码适合希望将人脸识别API落地到实际业务、学习无接触身份验证流程的中级学习者。项目以Java为核心结合科大讯飞与Face的人脸检测、特征提取、比对及活体检测能力覆盖图像采集、人脸比对、签到记录与异常处理等完整链路可用于课程设计、毕业设计或企业考勤场景的二次开发。压缩包共225个文件约15.29MB其中65个java源文件承载核心业务逻辑78个xml负责界面与配置36个png与2个jpg提供图像素材18个so与14个jar为SDK及依赖库另有gradle构建脚本与说明文档目录结构清晰便于按模块研读。目前已有292人学习下载读者可借此掌握API密钥申请、SDK集成、图像处理与数据管理的具体实现并参考Swface-master的代码组织方式快速搭建可运行的人脸识别签到原型。1. 从一份只有 9 个文件的 Java 工程说起人脸识别签到系统到底怎么落地拿到「人脸识别签到系统_java」这个包的时候我第一反应是有点意外——目录里没有一堆截图、没有几十兆的模型文件只有gradlew.bat、gradlew、build.gradle、settings.gradle、.gitignore外加三个 jarrxjava-1.1.6.jar、Msc.jar、okhttp-3.4.1.jar。这其实是一份非常典型的 Java 客户端工程骨架Msc.jar是科大讯飞 SDK 的核心包okhttp负责网络请求rxjava负责把「采集—检测—比对—签到」这条异步链路串起来。它解决的不是「从零训练一个人脸模型」的问题而是把现成的人脸识别 API 接进一个能跑起来的签到流程里适合做课程设计、企业内部考勤原型或者想搞清楚人脸识别 API 调用链路的 Java 开发。下面我按「工程怎么读 → 接口怎么接 → 坑在哪 → 怎么验证」的顺序拆一遍能直接抄的部分我都落到代码和参数上。2. 拆开 Gradle 工程Msc.jar、okhttp、rxjava 各自管什么2.1 三个 jar 的分工与依赖关系先把这三个 jar 的角色说清楚不然后面调接口会乱。Msc.jar是科大讯飞 MSCMobile Speech ClientSDK 的 Java 封装人脸相关的检测、特征提取、比对能力都通过它暴露出来它内部会走网络请求到讯飞的服务端所以它本身也依赖 HTTP 客户端。okhttp-3.4.1.jar是 Square 出的 HTTP 客户端3.4.1 这个版本对应的是 OkHttp 3.x 早期API 和现在 4.x 有差异比如RequestBody.create的参数顺序、Response.body().string()的调用方式抄网上新版本示例会编译不过。rxjava-1.1.6.jar是 RxJava 1.x注意是 1.x 不是 2.xObservable、Subscriber、Subscription这套 API 和 2.x 的Flowable、Disposable完全不同网上搜「RxJava 人脸识别」出来的大多是 2.x 写法直接贴进来会报cannot resolve method。这三个 jar 放在工程根目录而不是libs/下说明这份工程大概率是用flatDir方式引本地 jar而不是走 Maven 仓库。build.gradle里通常会有类似这样的配置// build.gradle 片段本地 jar 依赖声明 repositories { flatDir { dirs . // 指向工程根目录因为 jar 就放在这里 } } dependencies { compile fileTree(dir: ., include: [*.jar]) // 把根目录所有 jar 都纳入编译 // 或者逐个声明 // compile name: Msc // compile name: okhttp-3.4.1 // compile name: rxjava-1.1.6 }这里flatDir的dirs .是关键很多人把 jar 拷进libs/却忘了改路径结果gradlew build报Could not find Msc.jar。compile fileTree这种写法省事但会把根目录所有 jar 都塞进 classpath如果以后加了别的 jar 容易冲突我一般会逐个compile name:声明出问题好定位。settings.gradle里一般只有一行rootProject.name xxx不影响依赖但工程名如果带中文或空格某些 Gradle 版本会出路径问题建议保持英文。2.2 用 gradlew 把工程跑起来的最小步骤这份工程带的是 Gradle Wrapper也就是gradlew和gradlew.bat好处是不用本机装 GradleWrapper 会按gradle-wrapper.properties里的版本去下载。但注意目录里没有看到gradle/wrapper/文件夹如果gradle-wrapper.properties缺失gradlew会直接报错找不到 distributionUrl。常见做法是补一个# 在工程根目录执行Windows 用 gradlew.bat # 先看 wrapper 配置在不在 ls gradle/wrapper/gradle-wrapper.properties # 如果缺失用本机已装的 gradle 重新生成 wrapper gradle wrapper --gradle-version 4.10.2 # 然后编译 ./gradlew build # Linux/Mac gradlew.bat build # Windows--gradle-version选多少要看build.gradle里的compileSdkVersion或 Java 插件版本。这份工程用的是compile而不是implementation说明 Gradle 版本偏老4.x 比较稳。如果本机 JDK 是 17跑 Gradle 4.x 会报Unsupported class file major version因为 Gradle 4.x 不支持高版本 JDK 编译解决办法是切到 JDK 8 再跑或者把 Gradle 升到 7.x 并把compile改成implementation。这一步是很多人第一次跑就翻车的地方不是代码问题是工具链版本对不上。2.3 从文件结构反推签到主流程工程里没有src/main/java的完整展开但从 jar 组合能反推出主流程Msc.jar负责「人脸检测 特征提取 比对」okhttp负责「把图片或特征传到服务端 / 拉取签到记录」rxjava负责「把上面这些异步调用串成一条链」。典型链路是摄像头采集一帧 → 转成 SDK 要求的格式一般是 byte[] 或 Bitmap→ 调Msc的检测接口拿到人脸框 → 调特征提取拿到特征串 → 调比对接口和库里预存特征比 → 比对通过后走okhttp发签到请求 →rxjava的onNext里更新 UI 或写本地记录。这条链路里任何一步失败都要有onError兜底否则界面会卡死。下面第 3 章就按这条链路把接口调用写细。3. 接科大讯飞与 Face 接口从 API Key 到比对返回的完整链路3.1 API Key 申请与 SDK 初始化参数科大讯飞和 Face 都需要先注册开发者账号拿 Key。讯飞这边一般是APPIDAPIKeyAPISecret三件套Face 是API KeyAPI Secret。这两个平台的免费额度、QPS 限制、支持的图片格式都不一样选型时如果只是做签到原型讯飞的 MSC SDK 对 Java 更友好因为它直接给了 jarFace 更多是走 HTTP API用 okhttp 自己拼请求也行但活体检测这类能力通常要额外开通。初始化讯飞 SDK 的常见写法// 讯飞 MSC SDK 初始化参数来自控制台 // APPID 是应用标识APIKey/APISecret 用于鉴权 String APPID 你的APPID; String APIKey 你的APIKey; String APISecret 你的APISecret; // 初始化 SDK第二个参数是日志级别调试时用 LOG_LEVEL_DEBUG MscConfig config new MscConfig(); config.setAppId(APPID); config.setApiKey(APIKey); config.setApiSecret(APISecret); config.setLogLevel(MscConfig.LOG_LEVEL_DEBUG); // 初始化失败会抛异常必须 try-catch try { MscEngine engine MscEngine.getInstance(); engine.init(config); } catch (MscException e) { // 常见原因APPID 和 Key 不匹配、网络不通、SDK 版本过期 e.printStackTrace(); }setLogLevel调成 DEBUG 后SDK 会把每次请求的 URL、参数、返回码打到日志里排查10105无效的 APPID或10106无效的 APIKey这类错误码时非常有用。注意MscEngine.getInstance()是单例整个应用初始化一次就行重复 init 可能报already initialized。Face 那边如果用 okhttp 直接调鉴权参数一般放在 URL query 或 header 里api_key和api_secret不要硬编码在代码里放local.properties或环境变量避免提交到仓库。3.2 人脸检测与特征提取的调用与返回解析检测接口的作用是告诉你在图片哪个位置有人脸返回一般是人脸框坐标 置信度。特征提取是在检测基础上拿到一个特征串feature这个串才是比对用的。以讯飞风格为例// 人脸检测传入图片字节数组返回人脸列表 // 参数 imageData 是图片的 byte[]format 指定 jpg/png byte[] imageData readImageBytes(face.jpg); FaceDetectResult detectResult engine.detectFace(imageData, jpg); if (detectResult.getFaceCount() 0) { // 没检测到人脸常见于光线太暗、人脸太小、侧脸角度过大 Log.e(Face, no face detected); return; } // 取第一张人脸的框left/top/right/bottom 是像素坐标 FaceRect rect detectResult.getFaces().get(0).getRect(); Log.d(Face, rect rect.left , rect.top , rect.right , rect.bottom); // 特征提取基于检测结果拿特征串 String feature engine.extractFeature(imageData, rect); // feature 是一段 Base64 或十六进制字符串长度通常几百到上千字符detectFace的第二个参数jpg要和实际图片格式一致传 png 图片却写 jpgSDK 可能解析失败返回空。getFaceCount()为 0 时不要直接抛异常签到场景里用户没对准摄像头是常态应该提示「请正对摄像头」而不是崩溃。特征串feature拿到后要存库存的时候注意字段长度MySQL 里用TEXT而不是VARCHAR(255)因为特征串可能超过 255。比对时把现场特征和库里特征一起传给比对接口返回一个相似度分数通常 0 到 1 之间阈值设 0.8 以上比较稳设太低会误识设太高用户签不上。3.3 用 RxJava 1.x 串起异步链路与签到落库RxJava 1.x 的写法核心是Observable.createsubscribeOnobserveOn。人脸检测和网络请求都是耗时操作必须放子线程结果回主线程更新 UI// RxJava 1.x把检测、比对、签到串成一条链 Observable.create(new Observable.OnSubscribeSignResult() { Override public void call(Subscriber? super SignResult subscriber) { try { // 1. 检测 FaceDetectResult detect engine.detectFace(imageData, jpg); if (detect.getFaceCount() 0) { subscriber.onError(new Throwable(no face)); return; } // 2. 提取特征 String feature engine.extractFeature(imageData, detect.getFaces().get(0).getRect()); // 3. 比对compareFeature 返回相似度 float score engine.compareFeature(feature, storedFeature); if (score 0.8f) { subscriber.onError(new Throwable(score too low: score)); return; } // 4. 签到落库走 okhttp SignResult result signApi.postSign(userId, score); subscriber.onNext(result); subscriber.onCompleted(); } catch (Exception e) { subscriber.onError(e); } } }) .subscribeOn(Schedulers.io()) // 耗时操作放 IO 线程 .observeOn(AndroidSchedulers.mainThread()) // 结果回主线程 .subscribe(new SubscriberSignResult() { Override public void onCompleted() { } Override public void onError(Throwable e) { // 统一在这里处理没人脸、分数低、网络失败 toast(签到失败 e.getMessage()); } Override public void onNext(SignResult r) { toast(签到成功相似度 r.getScore()); } });subscribeOn(Schedulers.io())决定上游在哪个线程跑observeOn决定下游在哪个线程收这两个顺序不能反。RxJava 1.x 里Subscriber没有Disposable取消订阅用Subscription如果 Activity 销毁时没取消回调里更新 UI 会崩。compareFeature的阈值 0.8 不是固定的光线好的室内可以到 0.85光线差的场景降到 0.75但低于 0.7 基本就不能用了误识率会明显上升。签到落库用 okhttp 时RequestBody用FormBody还是MultipartBody取决于后端接口传特征串用FormBody就够传图片才需要MultipartBody。4. 避坑与排查人脸识别签到系统最容易翻车的 5 个点4.1 现象gradlew 报 Could not find Msc.jar原因jar 放在根目录但build.gradle里flatDir的dirs指向了libs或者fileTree的dir写错。解决确认dirs .和 jar 实际位置一致或者把 jar 移到libs/并改dirs libs。另外 Windows 下路径分隔符用/而不是\Gradle 对反斜杠支持不好。4.2 现象调用检测接口返回 10105 或 10106原因APPID、APIKey、APISecret 三者不匹配或者 Key 复制时带了空格。解决去控制台重新复制注意不要带首尾空格确认应用状态是「已开通」而不是「审核中」如果换了应用Key 要同步换。日志级别开到 DEBUG 能看到具体是哪个参数被拒。4.3 现象特征比对分数总是很低本人也签不上原因注册时存的特征和签到时的特征提取条件不一致比如注册用高清图、签到用低分辨率摄像头帧或者两次光线差异大。解决注册和签到走同一套采集流程图片尺寸、格式、压缩质量保持一致阈值不要一刀切可以按场景调如果 SDK 支持活体检测开启后能过滤掉照片攻击但也会增加失败率要权衡。4.4 现象RxJava 回调里更新 UI 崩溃原因Activity 已销毁但订阅没取消onNext里还在调toast或setText。解决在onDestroy里保存Subscription并调unsubscribe()或者用CompositeSubscription统一管理销毁时clear()。RxJava 1.x 没有自动生命周期绑定这一点比 2.x 的AutoDispose麻烦。4.5 现象okhttp 请求签到接口超时或返回 415原因Content-Type没设对或者FormBody里参数名和后端不一致。解决用FormBody.Builder时确认add的 key 和后端RequestParam一致如果后端要 JSON改用RequestBody.create(MediaType.parse(application/json), jsonStr)注意 OkHttp 3.4.1 的create第一个参数是 MediaType顺序和新版本不同。5. 进阶验证用一组对照样本测出你系统的真实阈值调通接口只是第一步真正决定这套签到系统能不能用的是阈值定得准不准。我一般会做一组对照实验找 5 个人每人采 3 张注册图正脸、稍侧、不同光线再采 10 张签到图包含本人和他人跑一遍比对把分数记下来。下面这个表是我常用的记录格式样本类型样本数最低分最高分平均分本人正脸150.860.950.91本人侧脸100.720.840.78他人误识200.310.580.44从这组数能看出本人正脸和他人误识之间有明显的分数带间隔阈值设在 0.7 到 0.8 之间比较安全。如果本人侧脸的最低分掉到 0.65而他人误识最高分到了 0.62那这个间隔就太窄了说明特征区分度不够要么换更好的采集条件要么换识别方案。验证时还要注意同一张图重复调接口分数应该基本一致如果波动超过 0.05可能是服务端做了随机化或者网络传输丢了数据这种就要查 SDK 版本和网络链路。另一个容易被忽略的点是签到记录的幂等性。同一个人短时间内重复签到后端应该按时间窗口去重而不是每次都插一条。我一般会在签到接口里加一个last_sign_time判断比如 5 分钟内重复请求直接返回「已签到」避免刷接口。这个逻辑放在 Java 服务端比放在客户端可靠客户端的时间可以被改。从那以后我每次接人脸识别类的工程都强制先跑一遍「注册—签到—误识」三组对照把分数分布画出来再定阈值而不是拍脑袋写 0.8。这套流程看起来多花半小时但能省掉后面反复调参的血泪经验。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/29 23:31:54 · 阅读 1.2k Java人脸识别签到系统实战：Gradle工程与讯飞SDK集成
简介这是一份面向Java开发者与计算机专业学生的「人脸识别签到系统」完整项目源码适合希望将人脸识别API落地到实际业务、学习无接触身份验证流程的中级学习者。项目以Java为核心结合科大讯飞与Face的人脸检测、特征提取、比对及活体检测能力覆盖图像采集、人脸比对、签到记录与异常处理等完整链路可用于课程设计、毕业设计或企业考勤场景的二次开发。压缩包共225个文件约15.29MB其中65个java源文件承载核心业务逻辑78个xml负责界面与配置36个png与2个jpg提供图像素材18个so与14个jar为SDK及依赖库另有gradle构建脚本与说明文档目录结构清晰便于按模块研读。目前已有292人学习下载读者可借此掌握API密钥申请、SDK集成、图像处理与数据管理的具体实现并参考Swface-master的代码组织方式快速搭建可运行的人脸识别签到原型。1. 从一份只有 9 个文件的 Java 工程说起人脸识别签到系统到底怎么落地拿到「人脸识别签到系统_java」这个包的时候我第一反应是有点意外——目录里没有一堆截图、没有几十兆的模型文件只有gradlew.bat、gradlew、build.gradle、settings.gradle、.gitignore外加三个 jarrxjava-1.1.6.jar、Msc.jar、okhttp-3.4.1.jar。这其实是一份非常典型的 Java 客户端工程骨架Msc.jar是科大讯飞 SDK 的核心包okhttp负责网络请求rxjava负责把「采集—检测—比对—签到」这条异步链路串起来。它解决的不是「从零训练一个人脸模型」的问题而是把现成的人脸识别 API 接进一个能跑起来的签到流程里适合做课程设计、企业内部考勤原型或者想搞清楚人脸识别 API 调用链路的 Java 开发。下面我按「工程怎么读 → 接口怎么接 → 坑在哪 → 怎么验证」的顺序拆一遍能直接抄的部分我都落到代码和参数上。2. 拆开 Gradle 工程Msc.jar、okhttp、rxjava 各自管什么2.1 三个 jar 的分工与依赖关系先把这三个 jar 的角色说清楚不然后面调接口会乱。Msc.jar是科大讯飞 MSCMobile Speech ClientSDK 的 Java 封装人脸相关的检测、特征提取、比对能力都通过它暴露出来它内部会走网络请求到讯飞的服务端所以它本身也依赖 HTTP 客户端。okhttp-3.4.1.jar是 Square 出的 HTTP 客户端3.4.1 这个版本对应的是 OkHttp 3.x 早期API 和现在 4.x 有差异比如RequestBody.create的参数顺序、Response.body().string()的调用方式抄网上新版本示例会编译不过。rxjava-1.1.6.jar是 RxJava 1.x注意是 1.x 不是 2.xObservable、Subscriber、Subscription这套 API 和 2.x 的Flowable、Disposable完全不同网上搜「RxJava 人脸识别」出来的大多是 2.x 写法直接贴进来会报cannot resolve method。这三个 jar 放在工程根目录而不是libs/下说明这份工程大概率是用flatDir方式引本地 jar而不是走 Maven 仓库。build.gradle里通常会有类似这样的配置// build.gradle 片段本地 jar 依赖声明 repositories { flatDir { dirs . // 指向工程根目录因为 jar 就放在这里 } } dependencies { compile fileTree(dir: ., include: [*.jar]) // 把根目录所有 jar 都纳入编译 // 或者逐个声明 // compile name: Msc // compile name: okhttp-3.4.1 // compile name: rxjava-1.1.6 }这里flatDir的dirs .是关键很多人把 jar 拷进libs/却忘了改路径结果gradlew build报Could not find Msc.jar。compile fileTree这种写法省事但会把根目录所有 jar 都塞进 classpath如果以后加了别的 jar 容易冲突我一般会逐个compile name:声明出问题好定位。settings.gradle里一般只有一行rootProject.name xxx不影响依赖但工程名如果带中文或空格某些 Gradle 版本会出路径问题建议保持英文。2.2 用 gradlew 把工程跑起来的最小步骤这份工程带的是 Gradle Wrapper也就是gradlew和gradlew.bat好处是不用本机装 GradleWrapper 会按gradle-wrapper.properties里的版本去下载。但注意目录里没有看到gradle/wrapper/文件夹如果gradle-wrapper.properties缺失gradlew会直接报错找不到 distributionUrl。常见做法是补一个# 在工程根目录执行Windows 用 gradlew.bat # 先看 wrapper 配置在不在 ls gradle/wrapper/gradle-wrapper.properties # 如果缺失用本机已装的 gradle 重新生成 wrapper gradle wrapper --gradle-version 4.10.2 # 然后编译 ./gradlew build # Linux/Mac gradlew.bat build # Windows--gradle-version选多少要看build.gradle里的compileSdkVersion或 Java 插件版本。这份工程用的是compile而不是implementation说明 Gradle 版本偏老4.x 比较稳。如果本机 JDK 是 17跑 Gradle 4.x 会报Unsupported class file major version因为 Gradle 4.x 不支持高版本 JDK 编译解决办法是切到 JDK 8 再跑或者把 Gradle 升到 7.x 并把compile改成implementation。这一步是很多人第一次跑就翻车的地方不是代码问题是工具链版本对不上。2.3 从文件结构反推签到主流程工程里没有src/main/java的完整展开但从 jar 组合能反推出主流程Msc.jar负责「人脸检测 特征提取 比对」okhttp负责「把图片或特征传到服务端 / 拉取签到记录」rxjava负责「把上面这些异步调用串成一条链」。典型链路是摄像头采集一帧 → 转成 SDK 要求的格式一般是 byte[] 或 Bitmap→ 调Msc的检测接口拿到人脸框 → 调特征提取拿到特征串 → 调比对接口和库里预存特征比 → 比对通过后走okhttp发签到请求 →rxjava的onNext里更新 UI 或写本地记录。这条链路里任何一步失败都要有onError兜底否则界面会卡死。下面第 3 章就按这条链路把接口调用写细。3. 接科大讯飞与 Face 接口从 API Key 到比对返回的完整链路3.1 API Key 申请与 SDK 初始化参数科大讯飞和 Face 都需要先注册开发者账号拿 Key。讯飞这边一般是APPIDAPIKeyAPISecret三件套Face 是API KeyAPI Secret。这两个平台的免费额度、QPS 限制、支持的图片格式都不一样选型时如果只是做签到原型讯飞的 MSC SDK 对 Java 更友好因为它直接给了 jarFace 更多是走 HTTP API用 okhttp 自己拼请求也行但活体检测这类能力通常要额外开通。初始化讯飞 SDK 的常见写法// 讯飞 MSC SDK 初始化参数来自控制台 // APPID 是应用标识APIKey/APISecret 用于鉴权 String APPID 你的APPID; String APIKey 你的APIKey; String APISecret 你的APISecret; // 初始化 SDK第二个参数是日志级别调试时用 LOG_LEVEL_DEBUG MscConfig config new MscConfig(); config.setAppId(APPID); config.setApiKey(APIKey); config.setApiSecret(APISecret); config.setLogLevel(MscConfig.LOG_LEVEL_DEBUG); // 初始化失败会抛异常必须 try-catch try { MscEngine engine MscEngine.getInstance(); engine.init(config); } catch (MscException e) { // 常见原因APPID 和 Key 不匹配、网络不通、SDK 版本过期 e.printStackTrace(); }setLogLevel调成 DEBUG 后SDK 会把每次请求的 URL、参数、返回码打到日志里排查10105无效的 APPID或10106无效的 APIKey这类错误码时非常有用。注意MscEngine.getInstance()是单例整个应用初始化一次就行重复 init 可能报already initialized。Face 那边如果用 okhttp 直接调鉴权参数一般放在 URL query 或 header 里api_key和api_secret不要硬编码在代码里放local.properties或环境变量避免提交到仓库。3.2 人脸检测与特征提取的调用与返回解析检测接口的作用是告诉你在图片哪个位置有人脸返回一般是人脸框坐标 置信度。特征提取是在检测基础上拿到一个特征串feature这个串才是比对用的。以讯飞风格为例// 人脸检测传入图片字节数组返回人脸列表 // 参数 imageData 是图片的 byte[]format 指定 jpg/png byte[] imageData readImageBytes(face.jpg); FaceDetectResult detectResult engine.detectFace(imageData, jpg); if (detectResult.getFaceCount() 0) { // 没检测到人脸常见于光线太暗、人脸太小、侧脸角度过大 Log.e(Face, no face detected); return; } // 取第一张人脸的框left/top/right/bottom 是像素坐标 FaceRect rect detectResult.getFaces().get(0).getRect(); Log.d(Face, rect rect.left , rect.top , rect.right , rect.bottom); // 特征提取基于检测结果拿特征串 String feature engine.extractFeature(imageData, rect); // feature 是一段 Base64 或十六进制字符串长度通常几百到上千字符detectFace的第二个参数jpg要和实际图片格式一致传 png 图片却写 jpgSDK 可能解析失败返回空。getFaceCount()为 0 时不要直接抛异常签到场景里用户没对准摄像头是常态应该提示「请正对摄像头」而不是崩溃。特征串feature拿到后要存库存的时候注意字段长度MySQL 里用TEXT而不是VARCHAR(255)因为特征串可能超过 255。比对时把现场特征和库里特征一起传给比对接口返回一个相似度分数通常 0 到 1 之间阈值设 0.8 以上比较稳设太低会误识设太高用户签不上。3.3 用 RxJava 1.x 串起异步链路与签到落库RxJava 1.x 的写法核心是Observable.createsubscribeOnobserveOn。人脸检测和网络请求都是耗时操作必须放子线程结果回主线程更新 UI// RxJava 1.x把检测、比对、签到串成一条链 Observable.create(new Observable.OnSubscribeSignResult() { Override public void call(Subscriber? super SignResult subscriber) { try { // 1. 检测 FaceDetectResult detect engine.detectFace(imageData, jpg); if (detect.getFaceCount() 0) { subscriber.onError(new Throwable(no face)); return; } // 2. 提取特征 String feature engine.extractFeature(imageData, detect.getFaces().get(0).getRect()); // 3. 比对compareFeature 返回相似度 float score engine.compareFeature(feature, storedFeature); if (score 0.8f) { subscriber.onError(new Throwable(score too low: score)); return; } // 4. 签到落库走 okhttp SignResult result signApi.postSign(userId, score); subscriber.onNext(result); subscriber.onCompleted(); } catch (Exception e) { subscriber.onError(e); } } }) .subscribeOn(Schedulers.io()) // 耗时操作放 IO 线程 .observeOn(AndroidSchedulers.mainThread()) // 结果回主线程 .subscribe(new SubscriberSignResult() { Override public void onCompleted() { } Override public void onError(Throwable e) { // 统一在这里处理没人脸、分数低、网络失败 toast(签到失败 e.getMessage()); } Override public void onNext(SignResult r) { toast(签到成功相似度 r.getScore()); } });subscribeOn(Schedulers.io())决定上游在哪个线程跑observeOn决定下游在哪个线程收这两个顺序不能反。RxJava 1.x 里Subscriber没有Disposable取消订阅用Subscription如果 Activity 销毁时没取消回调里更新 UI 会崩。compareFeature的阈值 0.8 不是固定的光线好的室内可以到 0.85光线差的场景降到 0.75但低于 0.7 基本就不能用了误识率会明显上升。签到落库用 okhttp 时RequestBody用FormBody还是MultipartBody取决于后端接口传特征串用FormBody就够传图片才需要MultipartBody。4. 避坑与排查人脸识别签到系统最容易翻车的 5 个点4.1 现象gradlew 报 Could not find Msc.jar原因jar 放在根目录但build.gradle里flatDir的dirs指向了libs或者fileTree的dir写错。解决确认dirs .和 jar 实际位置一致或者把 jar 移到libs/并改dirs libs。另外 Windows 下路径分隔符用/而不是\Gradle 对反斜杠支持不好。4.2 现象调用检测接口返回 10105 或 10106原因APPID、APIKey、APISecret 三者不匹配或者 Key 复制时带了空格。解决去控制台重新复制注意不要带首尾空格确认应用状态是「已开通」而不是「审核中」如果换了应用Key 要同步换。日志级别开到 DEBUG 能看到具体是哪个参数被拒。4.3 现象特征比对分数总是很低本人也签不上原因注册时存的特征和签到时的特征提取条件不一致比如注册用高清图、签到用低分辨率摄像头帧或者两次光线差异大。解决注册和签到走同一套采集流程图片尺寸、格式、压缩质量保持一致阈值不要一刀切可以按场景调如果 SDK 支持活体检测开启后能过滤掉照片攻击但也会增加失败率要权衡。4.4 现象RxJava 回调里更新 UI 崩溃原因Activity 已销毁但订阅没取消onNext里还在调toast或setText。解决在onDestroy里保存Subscription并调unsubscribe()或者用CompositeSubscription统一管理销毁时clear()。RxJava 1.x 没有自动生命周期绑定这一点比 2.x 的AutoDispose麻烦。4.5 现象okhttp 请求签到接口超时或返回 415原因Content-Type没设对或者FormBody里参数名和后端不一致。解决用FormBody.Builder时确认add的 key 和后端RequestParam一致如果后端要 JSON改用RequestBody.create(MediaType.parse(application/json), jsonStr)注意 OkHttp 3.4.1 的create第一个参数是 MediaType顺序和新版本不同。5. 进阶验证用一组对照样本测出你系统的真实阈值调通接口只是第一步真正决定这套签到系统能不能用的是阈值定得准不准。我一般会做一组对照实验找 5 个人每人采 3 张注册图正脸、稍侧、不同光线再采 10 张签到图包含本人和他人跑一遍比对把分数记下来。下面这个表是我常用的记录格式样本类型样本数最低分最高分平均分本人正脸150.860.950.91本人侧脸100.720.840.78他人误识200.310.580.44从这组数能看出本人正脸和他人误识之间有明显的分数带间隔阈值设在 0.7 到 0.8 之间比较安全。如果本人侧脸的最低分掉到 0.65而他人误识最高分到了 0.62那这个间隔就太窄了说明特征区分度不够要么换更好的采集条件要么换识别方案。验证时还要注意同一张图重复调接口分数应该基本一致如果波动超过 0.05可能是服务端做了随机化或者网络传输丢了数据这种就要查 SDK 版本和网络链路。另一个容易被忽略的点是签到记录的幂等性。同一个人短时间内重复签到后端应该按时间窗口去重而不是每次都插一条。我一般会在签到接口里加一个last_sign_time判断比如 5 分钟内重复请求直接返回「已签到」避免刷接口。这个逻辑放在 Java 服务端比放在客户端可靠客户端的时间可以被改。从那以后我每次接人脸识别类的工程都强制先跑一遍「注册—签到—误识」三组对照把分数分布画出来再定阈值而不是拍脑袋写 0.8。这套流程看起来多花半小时但能省掉后面反复调参的血泪经验。希望帮到你。本文还有配套的精品资源点击获取