简介这是一份面向Android开发者与AI初学者的表情识别可运行Demo可在普通手机上实时检测人脸表情CPU4线程单次推理约30ms、GPU约25ms适合快速体验端侧表情识别效果也适合作为移动端模型部署、性能调优的入门参考。压缩包共2个文件以可直接安装的apk和json配置信息为主apk用于在手机上装包体验json记录构建或输出相关信息整体仅24.53MB下载和运行成本都很低。目前已有1815人学习。通过这份资源可以拿到完整可运行的程序包免去从零搭建Android环境的步骤配合作者“面部表情识别”系列文章可串联人脸表情数据集、Pytorch训练、C/Android实现等知识点形成从模型训练到端侧落地的完整链路。其输出结果和耗时统计也可直接作为优化参考对打算在移动端快速实现表情识别或做同类视觉项目的开发者颇具实用价值。 表情识别在Android上一直是个“看起来谁都做过但真跑起来一堆坑”的事。最近我整理了一个基于YOLOv8n-face的Android实时表情识别Demo把整个人脸检测加表情分类的链路完整打通了涵盖了模型选型、ONNX转换、CameraX实时推理、UI绘制这几个关键环节真机实测能跑到25fps左右。这篇文章就以这个Demo为线索把设计和实现过程中的思路、代码和踩过的坑全部摊开来聊适合正在做移动端人脸识别、互动特效、课堂专注度分析等方向的同学参考。1. 项目整体思路与方案选型1.1 这个Demo解决了什么问题表情识别在移动端的应用场景比你想象中要广。短视频平台的表情互动特效、线下门店的客流情绪统计、在线教育里的课堂专注度分析、智能座舱的驾驶员状态监测背后都依赖“实时识别画面中人物的情绪状态”这个基础能力。但大部分业务方并不需要从零训练一个大模型他们要的是一个能跑在Android真机上、帧率可接受、结果可接入业务的稳定方案。这个Demo做的事情很明确打开手机摄像头在预览画面上实时框出人脸位置并判断当前表情属于开心、悲伤、惊讶、生气、厌恶、恐惧、中性这7类中的哪一类然后把标签和置信度直接绘制在画面中。作为Demo而言它证明了一条可复制的技术链路后续想接业务只需要替换模型或者改输出展示逻辑。我自己在实际开发中的体会是表情识别本身不难难的是把“检测分类”两个模型在手机端跑实时还要保证不卡顿、不崩溃、不发热严重。所以这个Demo的架构从一开始就是按“端侧实时”来设计的后面所有选型都围绕这个指标展开。1.2 技术路线为什么选择YOLOv8n-face 独立表情分类我在做方案对比时列了三种路线。第一种是传统方案OpenCV的Haar Cascade做人脸检测再用HOG或者LBP特征配合SVM做表情分类。这种方案的问题在于Haar检测器对侧脸、暗光、遮挡非常敏感误检率和漏检率都偏高用在演示环境问题不大但稍微换一个复杂背景就露馅。第二种是端到端方案训练一个同时输出人脸框和表情类别的多任务模型。理论上效果和效率最优但多任务标注数据很难获取中小团队基本很难复现。第三种就是Demo采用的折中方案用YOLOv8n-face做人脸检测再用一个独立的MobileNetV2分类网络做表情识别。两个模型各司其职任何一方有问题都可以单独替换灵活性最高。YOLOv8n-face是YOLOv8针对人脸检测任务的适配版本n代表nano是YOLOv8系里体积最小、速度最快的版本。它的优势在于模型结构成熟、部署生态好导出ONNX后不需要额外写自定义算子Android端可以直接用ONNX Runtime加载。表情分类模型我用的是MobileNetV2参数量只有2.3M左右导出后约9MB在移动端CPU上单次推理仅需10ms左右这两个模型加起来能轻松满足实时性要求。1.3 实时检测的硬性指标做移动端实时识别和服务器端完全是两套逻辑。服务器可以堆GPU、拉大batch手机端不行。内存有限算力有限还要考虑耗电和发热。所以我给这个Demo定了几条硬指标单帧完整推理时间小于50ms两个模型文件合计小于15MB真机连续运行30分钟不闪退、不内存泄漏。后面所有参数调优和代码实现都围绕这些指标展开比如输入分辨率控制在640x640以内模型全部用INT8或FP16量化UI层避免频繁创建对象等。2. 核心技术点拆解2.1 YOLOv8n-face的检测原理与输出解析第一次接触YOLO的人十有八九会被输出张量的维度搞晕。YOLOv8n-face的ONNX输出是一个三维张量常见的形状是(1, 84, 8400)或者(1, 6, 8400)具体取决于有没有把NMS整合进导出图里。以(1, 84, 8400)为例84代表4个边界框坐标加上80个类别概率8400是不同尺度特征图上的anchor点总数来自FPN的多尺度融合。如果你用的是仅人脸检测的专用版本输出可能是(1, 5, 8400)其中5代表4个坐标加1个置信度。搞清楚这个维度后解析结果就简单了。我写了一个轻量NMS逻辑先把所有候选框按置信度从高到低排序保留最高置信度的框然后删除与其IoU超过0.45的其它框重复这个过程直到候选框耗尽。如果只是做一个单人人脸的表情识别Demo也可以直接取置信度最高的框能省去NMS的耗时但多人场景会漏检。我建议还是保留NMS逻辑后面扩展多人识别时不用返工。2.2 表情分类模型为什么选MobileNetV2表情识别本质上是个图像分类问题可选骨干网络有ResNet18、MobileNetV2、EfficientNet-Lite等。我最后选了MobileNetV2理由很直接它是移动端分类模型的经典选择倒残差结构在速度和精度之间平衡得非常好。在FER2013和RAF-DB混合数据集上训练输入尺寸112x112分类头是全局平均池化加全连接层输出7维向量经过softmax得到每个类别的概率。训练时要注意数据分布问题。FER2013这个数据集本身有很多错标样本而且真实场景的覆盖度不够尤其对侧脸、戴眼镜、暗光环境下的泛化能力很差。我的做法是用FER2013做预训练再用RAF-DB的一部分数据做微调并加入了随机裁剪、颜色抖动、水平翻转等增强策略。即便这样在Demo里也会出现角度过大时识别不准的情况这是数据问题不是工程问题。如果你准备把这个Demo产品化强烈建议自采业务场景图片做二次微调否则效果很难满足需求。2.3 两套预处理参数绝不能混用检测模型和分类模型的输入尺寸、归一化方式、通道顺序都不一样这是新手最容易忽略的细节。检测模型YOLOv8n-face的输入是640x640使用letterbox保持宽高比在两侧填充灰色边像素值归一化到0~1通道顺序是RGB。分类模型MobileNetV2的输入是112x112直接resize不做letterbox像素值归一化到-1~1。这两套参数一旦混用最直接的表现就是检测框漂移和分类准确率骤降。很多人做完检测结果不准排查到最后发现是letterbox填充值设置错了。填充值一般用128对应归一化后的0.5用0或255都会影响模型对边界区域人脸的特征提取。3. 实操过程从零实现一个可运行的实时Demo3.1 Android工程搭建与依赖配置开发环境我用的是Android Studio Hedgehog版本Kotlin语言minSdk 24targetSdk 34。核心依赖就四个CameraX用于相机预览和图像分析ONNX Runtime用于模型推理Coroutines用于线程切换。在build.gradle.kts里加入这些依赖implementation(androidx.camera:camera-core:1.3.1) implementation(androidx.camera:camera-camera2:1.3.1) implementation(androidx.camera:camera-lifecycle:1.3.1) implementation(androidx.camera:camera-view:1.3.1) implementation(com.microsoft.onnxruntime:onnxruntime-android:1.17.1) implementation(org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3)onnxruntime-android默认包含armeabi-v7a、arm64-v8a、x86_64三个ABI的so文件。真机调试时建议在defaultConfig里只保留arm64-v8a能显著减小APK体积。我实测在只保留arm64-v8a的情况下ONNX Runtime的so文件约8MB加上两个模型文件APK总共25MB左右大小很可控。3.2 模型导出与文件放置YOLOv8n-face模型一般是用PyTorch训练或从社区获取的预训练权重需要导出成ONNX格式。导出时注意三点opset_version不低于12输入尺寸固定为640x640方便后续处理如果条件允许就把NMS节点一并导出这样Android端就不用自己实现NMS直接用ONNX Runtime调用即可。表情分类模型导出更简单MobileNetV2加一个全连接层PyTorch的torch.onnx.export一把梭保持输入112x112。两个模型文件都放在src/main/assets/models/目录下运行时通过AssetManager读取字节流加载。我习惯把它们命名为yolov8n-face.onnx和mobilenetv2_fer.onnx命名清晰方便排查问题。这里要提醒一点Android的assets目录是大小写敏感的models和Models会被当成两个不同目录。之前有朋友把路径写错编译不报错运行时疯狂崩查了半天才发现是大小写问题。3.3 检测与分类的推理代码实现模型的初始化封装在一个ExpressionDetector类里加载模型、创建Session、执行推理都在这里完成。关键代码如下class ExpressionDetector(context: Context) { private val ortEnv OrtEnvironment.getEnvironment() private val detectSession: OrtSession private val classifySession: OrtSession private val detectInputName: String private val classifyInputName: String init { val detectBytes context.assets.open(models/yolov8n-face.onnx).readBytes() val classBytes context.assets.open(models/mobilenetv2_fer.onnx).readBytes() detectSession ortEnv.createSession(detectBytes, OrtSession.SessionOptions()) classifySession ortEnv.createSession(classBytes, OrtSession.SessionOptions()) detectInputName detectSession.inputNames.iterator().next() classifyInputName classifySession.inputNames.iterator().next() } }注意OrtSession创建时必须传入完整的字节数组不能直接传InputStream。这个问题我印象特别深第一次写的时候偷懒传了stream结果直接native层崩溃报错信息又很不明确排查了很久。检测部分的流程是这样的先把Bitmap做letterbox变换转成640x640的float数组然后通过session跑推理。拿到输出后做坐标解析和NMS得到人脸框。坐标映射公式是这里最容易出错的地方给大家一个可以照着写的参考// 原图宽高 ow、oh模型输入尺寸 640x640 // scale min(640/ow, 640/oh) // padX (640 - ow*scale) / 2 // padY (640 - oh*scale) / 2 // 从原图坐标(x, y)映射到letterbox图 // bx x*scale padX // by y*scale padY // 反向映射回原图 // ox (bx - padX) / scale // oy (by - padY) / scale竖屏拍摄时如果发现检测框偏移先检查这个映射逻辑十有八九是pad计算顺序弄反了。分类部分相对简单从原Bitmap中裁剪人脸区域resize到112x112归一化后跑分类模型取softmax概率最大的类别作为结果。裁剪时一定要做边界约束防止框超出图片范围导致越界崩溃。3.4 CameraX实时检测链路搭建CameraX作为Android官方相机库对Camera2做了很好的封装特别适合做这种图像分析任务。我的实现里ImageAnalysis设置640x640的目标分辨率背压策略用STRATEGY_KEEP_ONLY_LATEST搭配单线程Executor。这样设计的好处是当处理速度跟不上帧率时CameraX会自动丢帧而不是无限积压保证系统的实时性。val analysis ImageAnalysis.Builder() .setTargetResolution(Size(640, 640)) .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST) .build() analysis.setAnalyzer(executor) { imageProxy - val bitmap imageProxy.toBitmap() val result detector.detect(bitmap) runOnUiThread { overlayView.setResult(result) } imageProxy.close() }这里有一个非常关键的操作imageProxy.close()必须在处理完后立刻调用否则CameraX会在2秒后自动断开预览流。这个坑我在刚开始用CameraX时的确踩过现象就是预览突然黑屏然后logcat里报BufferQueue的异常。UI层我建议用SurfaceView做预览上面叠加一个自定义的OverlayView负责绘制矩形框和文字标签。不要在CameraView上直接用ImageView叠结果因为每帧都要更新频繁创建视图会导致页面卡顿。OverlayView用canvas.drawText和drawRect绘制即可性能远优于普通View的图片组件。真机配置方面我在Redmi K60和Pixel 6上分别做了测试芯片都算中端偏上单帧完整推理时间约35ms换算下来帧率约25fps完全满足实时检测的需求。作为对比如果不用量化模型推理时间会上升到60到80ms帧率掉到15fps以下体验直接打对折。4. 常见问题与排查技巧实录4.1 模型加载失败或运行崩溃报错信息里如果出现libonnxruntime.so not found基本可以确定是ABI配置问题。我在排查这类问题时习惯先在手机上用adb shell getprop ro.product.cpu.abi看真机架构再和工程的abiFilters配置比对。真机调试建议只保留arm64-v8a模拟器调试则需要x86_64两个环境不能混用。还有一个比较隐蔽的问题是OrtSession加载模型字节流时崩溃。检查点有三处模型文件是否完整导出、assets路径是否正确、读取时是否用了完整字节数组。之前遇到过从网上下载的onnx文件只有100多KB明显不完整加载时直接报错换成完整文件后一切正常。4.2 检测框错位、偏移或方向不对检测框错位分为两种情况。第一种是坐标映射错误表现在横屏或者竖屏时框的位置整体偏移按照3.3节的letterbox映射公式逐行核对就能解决。第二种是图像方向错误这是CameraX最容易踩的坑。ImageAnalysis拿到的图像是传感器原始方向和预览画面不一定一致必须在转Bitmap时用rotationDegrees做旋转校正。我在代码里的处理方式是通过imageProxy.imageInfo.rotationDegrees获取旋转角度然后用Matrix做一次旋转再送进检测器。这一步官方文档写得很含糊我看不少人在这地方卡了很久。如果省略这一步检测框在竖屏状态下会偏约90度而且框的位置越靠近图像边缘偏移越明显。4.3 实时帧率低到没法用帧率低于10fps的时候99%的问题不在模型而在工程实现。我排查过四类最典型的原因一是每帧都创建新的Bitmap和ByteArray导致GC频繁触发CPU大量消耗在垃圾回收上二是ImageAnalysis的背压策略用了BUFFER_MODE_QUEUE图像帧无限积压三是推理操作跑在了主线程卡UI四是ImageAnalysis输入分辨率设置过高比如1920x1080然后每帧再做resize。这四类问题分别对应四个解决方案复用buffer、改回KEEP_ONLY_LATEST、用独立Executor、把targetResolution降低到640x640。内存方面也要注意Bitmap对象在长时间预览时需要及时回收。我的OverlayView在onDraw里不会创建新对象检测结果用一个data class保存每帧复用同一个实例减少内存抖动。长时间测试后没有出现内存泄漏。4.4 表情识别结果明显不准如果检测框准确但表情分类一直错问题基本出在数据侧而不是工程侧。模型对侧脸、暗光、遮挡这类“非标准”输入会表现得很不稳定这是训练数据限制决定的。检查时我建议按优先级排查训练数据是否覆盖了目标场景、是否做了数据增强、输入图像的通道顺序是否和训练一致。RGB和BGR通道互换会让分类精度急剧下降这个点经常被忽略。对于Demo来说模型效果够用即可但要上生产环境务必要用业务场景的数据做微调否则上线后用户反馈会让你很被动。我在实际做这个Demo的过程中最大的感受是移动端AI项目真正花时间的不是模型训练而是工程链路的打磨。把模型跑通只需要半天但要把帧率、内存、稳定性、兼容性都调到满意的状态至少需要两三天的调试。希望这篇文章能帮你把该踩的坑提前避开。本文还有配套的精品资源点击获取 Android实时表情识别：基于YOLOv8n-face与MobileNetV2的实践
简介这是一份面向Android开发者与AI初学者的表情识别可运行Demo可在普通手机上实时检测人脸表情CPU4线程单次推理约30ms、GPU约25ms适合快速体验端侧表情识别效果也适合作为移动端模型部署、性能调优的入门参考。压缩包共2个文件以可直接安装的apk和json配置信息为主apk用于在手机上装包体验json记录构建或输出相关信息整体仅24.53MB下载和运行成本都很低。目前已有1815人学习。通过这份资源可以拿到完整可运行的程序包免去从零搭建Android环境的步骤配合作者“面部表情识别”系列文章可串联人脸表情数据集、Pytorch训练、C/Android实现等知识点形成从模型训练到端侧落地的完整链路。其输出结果和耗时统计也可直接作为优化参考对打算在移动端快速实现表情识别或做同类视觉项目的开发者颇具实用价值。 表情识别在Android上一直是个“看起来谁都做过但真跑起来一堆坑”的事。最近我整理了一个基于YOLOv8n-face的Android实时表情识别Demo把整个人脸检测加表情分类的链路完整打通了涵盖了模型选型、ONNX转换、CameraX实时推理、UI绘制这几个关键环节真机实测能跑到25fps左右。这篇文章就以这个Demo为线索把设计和实现过程中的思路、代码和踩过的坑全部摊开来聊适合正在做移动端人脸识别、互动特效、课堂专注度分析等方向的同学参考。1. 项目整体思路与方案选型1.1 这个Demo解决了什么问题表情识别在移动端的应用场景比你想象中要广。短视频平台的表情互动特效、线下门店的客流情绪统计、在线教育里的课堂专注度分析、智能座舱的驾驶员状态监测背后都依赖“实时识别画面中人物的情绪状态”这个基础能力。但大部分业务方并不需要从零训练一个大模型他们要的是一个能跑在Android真机上、帧率可接受、结果可接入业务的稳定方案。这个Demo做的事情很明确打开手机摄像头在预览画面上实时框出人脸位置并判断当前表情属于开心、悲伤、惊讶、生气、厌恶、恐惧、中性这7类中的哪一类然后把标签和置信度直接绘制在画面中。作为Demo而言它证明了一条可复制的技术链路后续想接业务只需要替换模型或者改输出展示逻辑。我自己在实际开发中的体会是表情识别本身不难难的是把“检测分类”两个模型在手机端跑实时还要保证不卡顿、不崩溃、不发热严重。所以这个Demo的架构从一开始就是按“端侧实时”来设计的后面所有选型都围绕这个指标展开。1.2 技术路线为什么选择YOLOv8n-face 独立表情分类我在做方案对比时列了三种路线。第一种是传统方案OpenCV的Haar Cascade做人脸检测再用HOG或者LBP特征配合SVM做表情分类。这种方案的问题在于Haar检测器对侧脸、暗光、遮挡非常敏感误检率和漏检率都偏高用在演示环境问题不大但稍微换一个复杂背景就露馅。第二种是端到端方案训练一个同时输出人脸框和表情类别的多任务模型。理论上效果和效率最优但多任务标注数据很难获取中小团队基本很难复现。第三种就是Demo采用的折中方案用YOLOv8n-face做人脸检测再用一个独立的MobileNetV2分类网络做表情识别。两个模型各司其职任何一方有问题都可以单独替换灵活性最高。YOLOv8n-face是YOLOv8针对人脸检测任务的适配版本n代表nano是YOLOv8系里体积最小、速度最快的版本。它的优势在于模型结构成熟、部署生态好导出ONNX后不需要额外写自定义算子Android端可以直接用ONNX Runtime加载。表情分类模型我用的是MobileNetV2参数量只有2.3M左右导出后约9MB在移动端CPU上单次推理仅需10ms左右这两个模型加起来能轻松满足实时性要求。1.3 实时检测的硬性指标做移动端实时识别和服务器端完全是两套逻辑。服务器可以堆GPU、拉大batch手机端不行。内存有限算力有限还要考虑耗电和发热。所以我给这个Demo定了几条硬指标单帧完整推理时间小于50ms两个模型文件合计小于15MB真机连续运行30分钟不闪退、不内存泄漏。后面所有参数调优和代码实现都围绕这些指标展开比如输入分辨率控制在640x640以内模型全部用INT8或FP16量化UI层避免频繁创建对象等。2. 核心技术点拆解2.1 YOLOv8n-face的检测原理与输出解析第一次接触YOLO的人十有八九会被输出张量的维度搞晕。YOLOv8n-face的ONNX输出是一个三维张量常见的形状是(1, 84, 8400)或者(1, 6, 8400)具体取决于有没有把NMS整合进导出图里。以(1, 84, 8400)为例84代表4个边界框坐标加上80个类别概率8400是不同尺度特征图上的anchor点总数来自FPN的多尺度融合。如果你用的是仅人脸检测的专用版本输出可能是(1, 5, 8400)其中5代表4个坐标加1个置信度。搞清楚这个维度后解析结果就简单了。我写了一个轻量NMS逻辑先把所有候选框按置信度从高到低排序保留最高置信度的框然后删除与其IoU超过0.45的其它框重复这个过程直到候选框耗尽。如果只是做一个单人人脸的表情识别Demo也可以直接取置信度最高的框能省去NMS的耗时但多人场景会漏检。我建议还是保留NMS逻辑后面扩展多人识别时不用返工。2.2 表情分类模型为什么选MobileNetV2表情识别本质上是个图像分类问题可选骨干网络有ResNet18、MobileNetV2、EfficientNet-Lite等。我最后选了MobileNetV2理由很直接它是移动端分类模型的经典选择倒残差结构在速度和精度之间平衡得非常好。在FER2013和RAF-DB混合数据集上训练输入尺寸112x112分类头是全局平均池化加全连接层输出7维向量经过softmax得到每个类别的概率。训练时要注意数据分布问题。FER2013这个数据集本身有很多错标样本而且真实场景的覆盖度不够尤其对侧脸、戴眼镜、暗光环境下的泛化能力很差。我的做法是用FER2013做预训练再用RAF-DB的一部分数据做微调并加入了随机裁剪、颜色抖动、水平翻转等增强策略。即便这样在Demo里也会出现角度过大时识别不准的情况这是数据问题不是工程问题。如果你准备把这个Demo产品化强烈建议自采业务场景图片做二次微调否则效果很难满足需求。2.3 两套预处理参数绝不能混用检测模型和分类模型的输入尺寸、归一化方式、通道顺序都不一样这是新手最容易忽略的细节。检测模型YOLOv8n-face的输入是640x640使用letterbox保持宽高比在两侧填充灰色边像素值归一化到0~1通道顺序是RGB。分类模型MobileNetV2的输入是112x112直接resize不做letterbox像素值归一化到-1~1。这两套参数一旦混用最直接的表现就是检测框漂移和分类准确率骤降。很多人做完检测结果不准排查到最后发现是letterbox填充值设置错了。填充值一般用128对应归一化后的0.5用0或255都会影响模型对边界区域人脸的特征提取。3. 实操过程从零实现一个可运行的实时Demo3.1 Android工程搭建与依赖配置开发环境我用的是Android Studio Hedgehog版本Kotlin语言minSdk 24targetSdk 34。核心依赖就四个CameraX用于相机预览和图像分析ONNX Runtime用于模型推理Coroutines用于线程切换。在build.gradle.kts里加入这些依赖implementation(androidx.camera:camera-core:1.3.1) implementation(androidx.camera:camera-camera2:1.3.1) implementation(androidx.camera:camera-lifecycle:1.3.1) implementation(androidx.camera:camera-view:1.3.1) implementation(com.microsoft.onnxruntime:onnxruntime-android:1.17.1) implementation(org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3)onnxruntime-android默认包含armeabi-v7a、arm64-v8a、x86_64三个ABI的so文件。真机调试时建议在defaultConfig里只保留arm64-v8a能显著减小APK体积。我实测在只保留arm64-v8a的情况下ONNX Runtime的so文件约8MB加上两个模型文件APK总共25MB左右大小很可控。3.2 模型导出与文件放置YOLOv8n-face模型一般是用PyTorch训练或从社区获取的预训练权重需要导出成ONNX格式。导出时注意三点opset_version不低于12输入尺寸固定为640x640方便后续处理如果条件允许就把NMS节点一并导出这样Android端就不用自己实现NMS直接用ONNX Runtime调用即可。表情分类模型导出更简单MobileNetV2加一个全连接层PyTorch的torch.onnx.export一把梭保持输入112x112。两个模型文件都放在src/main/assets/models/目录下运行时通过AssetManager读取字节流加载。我习惯把它们命名为yolov8n-face.onnx和mobilenetv2_fer.onnx命名清晰方便排查问题。这里要提醒一点Android的assets目录是大小写敏感的models和Models会被当成两个不同目录。之前有朋友把路径写错编译不报错运行时疯狂崩查了半天才发现是大小写问题。3.3 检测与分类的推理代码实现模型的初始化封装在一个ExpressionDetector类里加载模型、创建Session、执行推理都在这里完成。关键代码如下class ExpressionDetector(context: Context) { private val ortEnv OrtEnvironment.getEnvironment() private val detectSession: OrtSession private val classifySession: OrtSession private val detectInputName: String private val classifyInputName: String init { val detectBytes context.assets.open(models/yolov8n-face.onnx).readBytes() val classBytes context.assets.open(models/mobilenetv2_fer.onnx).readBytes() detectSession ortEnv.createSession(detectBytes, OrtSession.SessionOptions()) classifySession ortEnv.createSession(classBytes, OrtSession.SessionOptions()) detectInputName detectSession.inputNames.iterator().next() classifyInputName classifySession.inputNames.iterator().next() } }注意OrtSession创建时必须传入完整的字节数组不能直接传InputStream。这个问题我印象特别深第一次写的时候偷懒传了stream结果直接native层崩溃报错信息又很不明确排查了很久。检测部分的流程是这样的先把Bitmap做letterbox变换转成640x640的float数组然后通过session跑推理。拿到输出后做坐标解析和NMS得到人脸框。坐标映射公式是这里最容易出错的地方给大家一个可以照着写的参考// 原图宽高 ow、oh模型输入尺寸 640x640 // scale min(640/ow, 640/oh) // padX (640 - ow*scale) / 2 // padY (640 - oh*scale) / 2 // 从原图坐标(x, y)映射到letterbox图 // bx x*scale padX // by y*scale padY // 反向映射回原图 // ox (bx - padX) / scale // oy (by - padY) / scale竖屏拍摄时如果发现检测框偏移先检查这个映射逻辑十有八九是pad计算顺序弄反了。分类部分相对简单从原Bitmap中裁剪人脸区域resize到112x112归一化后跑分类模型取softmax概率最大的类别作为结果。裁剪时一定要做边界约束防止框超出图片范围导致越界崩溃。3.4 CameraX实时检测链路搭建CameraX作为Android官方相机库对Camera2做了很好的封装特别适合做这种图像分析任务。我的实现里ImageAnalysis设置640x640的目标分辨率背压策略用STRATEGY_KEEP_ONLY_LATEST搭配单线程Executor。这样设计的好处是当处理速度跟不上帧率时CameraX会自动丢帧而不是无限积压保证系统的实时性。val analysis ImageAnalysis.Builder() .setTargetResolution(Size(640, 640)) .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST) .build() analysis.setAnalyzer(executor) { imageProxy - val bitmap imageProxy.toBitmap() val result detector.detect(bitmap) runOnUiThread { overlayView.setResult(result) } imageProxy.close() }这里有一个非常关键的操作imageProxy.close()必须在处理完后立刻调用否则CameraX会在2秒后自动断开预览流。这个坑我在刚开始用CameraX时的确踩过现象就是预览突然黑屏然后logcat里报BufferQueue的异常。UI层我建议用SurfaceView做预览上面叠加一个自定义的OverlayView负责绘制矩形框和文字标签。不要在CameraView上直接用ImageView叠结果因为每帧都要更新频繁创建视图会导致页面卡顿。OverlayView用canvas.drawText和drawRect绘制即可性能远优于普通View的图片组件。真机配置方面我在Redmi K60和Pixel 6上分别做了测试芯片都算中端偏上单帧完整推理时间约35ms换算下来帧率约25fps完全满足实时检测的需求。作为对比如果不用量化模型推理时间会上升到60到80ms帧率掉到15fps以下体验直接打对折。4. 常见问题与排查技巧实录4.1 模型加载失败或运行崩溃报错信息里如果出现libonnxruntime.so not found基本可以确定是ABI配置问题。我在排查这类问题时习惯先在手机上用adb shell getprop ro.product.cpu.abi看真机架构再和工程的abiFilters配置比对。真机调试建议只保留arm64-v8a模拟器调试则需要x86_64两个环境不能混用。还有一个比较隐蔽的问题是OrtSession加载模型字节流时崩溃。检查点有三处模型文件是否完整导出、assets路径是否正确、读取时是否用了完整字节数组。之前遇到过从网上下载的onnx文件只有100多KB明显不完整加载时直接报错换成完整文件后一切正常。4.2 检测框错位、偏移或方向不对检测框错位分为两种情况。第一种是坐标映射错误表现在横屏或者竖屏时框的位置整体偏移按照3.3节的letterbox映射公式逐行核对就能解决。第二种是图像方向错误这是CameraX最容易踩的坑。ImageAnalysis拿到的图像是传感器原始方向和预览画面不一定一致必须在转Bitmap时用rotationDegrees做旋转校正。我在代码里的处理方式是通过imageProxy.imageInfo.rotationDegrees获取旋转角度然后用Matrix做一次旋转再送进检测器。这一步官方文档写得很含糊我看不少人在这地方卡了很久。如果省略这一步检测框在竖屏状态下会偏约90度而且框的位置越靠近图像边缘偏移越明显。4.3 实时帧率低到没法用帧率低于10fps的时候99%的问题不在模型而在工程实现。我排查过四类最典型的原因一是每帧都创建新的Bitmap和ByteArray导致GC频繁触发CPU大量消耗在垃圾回收上二是ImageAnalysis的背压策略用了BUFFER_MODE_QUEUE图像帧无限积压三是推理操作跑在了主线程卡UI四是ImageAnalysis输入分辨率设置过高比如1920x1080然后每帧再做resize。这四类问题分别对应四个解决方案复用buffer、改回KEEP_ONLY_LATEST、用独立Executor、把targetResolution降低到640x640。内存方面也要注意Bitmap对象在长时间预览时需要及时回收。我的OverlayView在onDraw里不会创建新对象检测结果用一个data class保存每帧复用同一个实例减少内存抖动。长时间测试后没有出现内存泄漏。4.4 表情识别结果明显不准如果检测框准确但表情分类一直错问题基本出在数据侧而不是工程侧。模型对侧脸、暗光、遮挡这类“非标准”输入会表现得很不稳定这是训练数据限制决定的。检查时我建议按优先级排查训练数据是否覆盖了目标场景、是否做了数据增强、输入图像的通道顺序是否和训练一致。RGB和BGR通道互换会让分类精度急剧下降这个点经常被忽略。对于Demo来说模型效果够用即可但要上生产环境务必要用业务场景的数据做微调否则上线后用户反馈会让你很被动。我在实际做这个Demo的过程中最大的感受是移动端AI项目真正花时间的不是模型训练而是工程链路的打磨。把模型跑通只需要半天但要把帧率、内存、稳定性、兼容性都调到满意的状态至少需要两三天的调试。希望这篇文章能帮你把该踩的坑提前避开。本文还有配套的精品资源点击获取