简介这是一份面向安卓开发者和移动端人工智能学习者的 TensorFlow Lite 图像分类示例工程重点演示在手机端加载轻量化模型并完成本地图片识别适合用于理解离线推理在移动应用中的工程落地方式。压缩包共110个文件、约3.76MB内含 Java 源码、XML 布局与资源、Gradle 构建配置、PNG 图片素材以及 tflite 模型文件覆盖界面资源、工程配置、模型集成与素材管理等常见组成部分整体结构较紧凑。目前已有6821人学习下载说明该示例在入门实践与课堂演示场景中具有一定的参考价值。工程保留较完整的 Android Studio 目录结构和构建脚本便于查看模型文件放置、推理代码组织、界面资源配合与基础调试入口也可作为原型验证、课程作业或二次开发的基础模板帮助读者快速熟悉 TensorFlow Lite 在移动端的项目形态与调试思路。1. 从一张图到一行结果先看清这条链路把一张 224×224 的图片丢给手机几百毫秒后屏幕上打出「金毛犬 0.87」——用 TensorFlow Lite 在 Android 上做图像分类代码量比大多数人想象得少真正让人卡住的从来不是模型本身。我见过不少团队花两周训出一个不错的分类器结果在真机上第一次跑就翻车App 不崩、也不报错只是每个人像都识别成同一类。事后定位下来既不是模型精度问题也不是算子不支持而是预处理里把 RGB 和 BGR 弄反了外加归一化系数照搬了训练脚本里的另一个版本。这类问题在 PC 上大概率会被掩盖一旦挪到移动端就集中暴露。这个 demo 面向的正是这条完整链路从已经训好的 Keras 模型出发转成.tflite再在 Android 端接 CameraX 取流、做预处理、调用 Interpreter 推理、把 top-k 结果映射成标签。它适合两类人一类是做过模型训练、但没在移动端部署过的算法同学另一类是写 Android 顺手、想把手势识别、垃圾分类、工业质检这类视觉需求塞进 App 的客户端。下面按「先弄懂运行时在做什么再动手转模型最后往手机上装」的顺序走每一步都给出能直接抄的代码和参数。2. TFLite 在 Android 上的运行机制与工程选型2.1 推理链路上到底有哪几层TensorFlow Lite 不是一个「把模型文件拖进工程就能跑」的黑匣子。它在 Android 上分三层最上层是 Java/Kotlin 的InterpreterAPI负责加载模型、分配张量、发起推理中间是 TFLite 的 C 运行时解析 FlatBuffer 格式的模型并调度算子最底层是各算子的内核实现可以选择纯 CPU 的 reference kernel也可以走 XNNPACK、GPU 委托或 NNAPI。理解这三层很关键因为后面绝大多数「为什么慢」「为什么结果不对」都能落回某一层。模型文件本身是 FlatBuffer 而非 protobuf这个设计是为了零拷贝加载——FileUtil.loadMappedFile把模型 mmap 进内存Interpreter直接在这块内存上工作不需要反序列化。这也解释了一个常见现象模型 40MB但 App 运行时内存增长并没有 40MB因为页是按需换入的。我第一次见这个行为时还以为是统计错了。输入输出张量的形状、类型、量化参数是这条链路上最需要提前固定的契约。图像分类 demo 的典型契约是输入[1, 224, 224, 3]数据类型可能是float32或uint8输出[1, 1000]或[1, num_classes]。这个契约在转换那一刻就写死在模型里了Android 端只能照着填不能想当然。2.2 环境与依赖清单我一般把环境钉死避免「同事能跑我不能跑」这种玄学问题。这个 demo 的基线如下注意 TFLite 的 AAR 版本和 Android Gradle Plugin 版本要能对上版本差太多会出现 native 库加载失败。组件版本 / 取值说明Android Gradle Plugin8.1.x与下面 NDK 兼容性较好最低 SDK24低于此值部分委托不可用目标 SDK34按当前上架要求取TFLite 运行时org.tensorflow:tensorflow-lite:2.14.0核心 InterpreterTFLite Supportorg.tensorflow:tensorflow-lite-support:0.4.4图像预处理工具类GPU 委托org.tensorflow:tensorflow-lite-gpu:2.14.0进阶章会用到相机CameraX 1.3.x预览 ImageAnalysisABI 过滤arm64-v8a、armeabi-v7a模拟器可加 x86_64build.gradle里关键几行android { defaultConfig { minSdk 24 ndk { // 只保留真机常用 ABI包体小一半 abiFilters arm64-v8a, armeabi-v7a } } aaptOptions { // .tflite 不能被压缩否则 mmap 失效加载会退化成整块读入 noCompress tflite } } dependencies { implementation org.tensorflow:tensorflow-lite:2.14.0 implementation org.tensorflow:tensorflow-lite-support:0.4.4 implementation androidx.camera:camera-camera2:1.3.4 implementation androidx.camera:camera-lifecycle:1.3.4 implementation androidx.camera:camera-view:1.3.4 }noCompress tflite这一行很多人会漏。模型被 APK 打包压缩后loadMappedFile拿不到可 mmap 的连续区域运行时会把整个模型读进堆内存大模型直接触发 OOM。这个坑不报错只在低端机上表现为偶发闪退很难查。模型文件放src/main/assets/命名统一用小写下划线比如mobilenetv3_int8.tflite。标签文件labels.txt一行一类顺序必须和训练时class_indices的索引严格对应——顺序错了不会报错只会安静地输出错类别属于典型的「结果对不上但程序没问题」。2.3 模型选型与输入张量约定图像分类在移动端选 backbone核心就三个指标参数量、单帧延迟、精度。224×224 输入下MobileNetV3-Small 的 int8 量化版大约 2.5MB中端机单帧 CPU 推理 1530msEfficientNet-Lite0 精度更高模型约 4.5MB延迟翻一倍左右ResNet50 这类就别往手机上塞了除非只做单张拍照识别、不在乎实时性。我一般按场景定实时相机预览、要求 15fps 以上MobileNetV3-Small 或 MobileNetV2 0.5 宽度乘子int8 量化CPU 4 线程。拍照后单张识别、允许 200msEfficientNet-Lite0float16 量化精度更稳。端上还要做二次校验用同一个 backbone 输出特征自己接一个小的度量学习头。输入张量约定要写进文档因为转换脚本和 Android 代码的人往往不是同一个人。这个 demo 统一约定输入名input形状[1, 224, 224, 3]通道顺序 RGB像素值范围[0, 255]若模型是 float32 输入则在 App 内除以 255 归一化到[0, 1]若模型是 uint8 输入则直接填原始像素。归一化发生在模型内还是 App 内决定了 Android 端要不要做除法这一步搞混精度会掉十几个点但程序照跑。3. 把训练好的模型转成 .tflite转换脚本、量化与精度验收3.1 Keras/SavedModel 到 TFLite 的转换参数转换阶段的输入最好是 SavedModel 或者固定了输入形状的 Keras 模型。动态 batch、动态分辨率在移动端没有任何意义反而会让转换器拒绝某些优化。所以第一步先把输入形状钉死。import tensorflow as tf # 1. 加载微调后的模型这里假设输入已是 224x224x3 model tf.keras.models.load_model(mobilenetv3_finetune.h5) # 2. 包一层 tf.function拿到固定形状的 ConcreteFunction run_model tf.function(lambda x: model(x)) concrete_func run_model.get_concrete_function( tf.TensorSpec([1, 224, 224, 3], tf.float32, nameinput) ) # 3. 基础转换先不做量化拿到一个 float32 基线模型 converter tf.lite.TFLiteConverter.from_concrete_functions([concrete_func]) tflite_fp32 converter.convert() with open(model_fp32.tflite, wb) as f: f.write(tflite_fp32) print(fp32 模型大小: %.2f MB % (len(tflite_fp32) / 1024 / 1024))from_concrete_functions比from_keras_model更可控因为它能保证输入签名和形状就是你写的那一个不会在转换时被推断成[None, None, None, 3]。TensorSpec里的nameinput会成为 TFLite 的输入张量名Android 端用getInputTensor(0)按索引取更稳妥名字只用于排查。先转一个 fp32 基线不是为了上线而是为了做对照。后面每做一次量化都拿它和基线比 top-1 一致率这样精度损失是量出来的不是猜的。3.2 三种量化策略与体积、精度的权衡量化是这个 demo 里收益最大的一步也是翻车最多的一步。常见三种做法策略配置体积相对 fp32速度精度损失ImageNet 量级适用动态范围量化Optimize.DEFAULT不设 representative_dataset约 1/4提升明显通常 1%首选基线几乎无痛全整型量化DEFAULTTFLITE_BUILTINS_INT8 校准集约 1/4更快可用 int8 内核1%3%取决于校准集低端机、要求低延迟Float16 量化DEFAULTsupported_types[tf.float16]约 1/2GPU 上收益大通常 0.5%走 GPU 委托时优先全整型量化的关键在representative_dataset。它不是随便抽几张图就行校准集的分布必须贴近线上真实输入。我用过一批室内场景图去校准一个户外垃圾分类模型结果模型对天空和草地的响应被压得很死线上准确率掉了 6 个点血泪经验。# 4. 全整型量化需要校准集产出 uint8 输入输出的模型 converter tf.lite.TFLiteConverter.from_concrete_functions([concrete_func]) converter.optimizations [tf.lite.Optimize.DEFAULT] converter.target_spec.supported_ops [tf.lite.OpsSet.TFLITE_BUILTINS_INT8] def representative_dataset(): # calib_ds 是 tf.data.Dataset元素形状 [1,224,224,3]值域 [0,1] for batch in calib_ds.take(200): yield [tf.cast(batch, tf.float32)] converter.representative_dataset representative_dataset # 让输入输出也变成 uint8省掉 Android 端的 float 转换 converter.inference_input_type tf.uint8 converter.inference_output_type tf.uint8 tflite_int8 converter.convert() with open(model_int8.tflite, wb) as f: f.write(tflite_int8)inference_input_type tf.uint8这一行决定了 Android 端的 buffer 分配方式输入 buffer 是1*224*224*3个字节不是 float 的 4 倍。这一点在下一章的预处理代码里必须对应上否则Interpreter会抛DataType mismatch或者更糟——不抛异常但结果全错。校准集数量我一般取 100300 张太少量化参数估不准太多转换时间线性增长。采样要覆盖各类别别把某个类漏掉漏掉的类在量化后几乎必然失效。3.3 用 Python 验证转换结果与输入输出对齐模型转完不能直接扔给 Android先在 PC 上验一遍张量契约和精度。这个脚本很短但能挡掉后面一大半联调时间。import numpy as np import tensorflow as tf interpreter tf.lite.Interpreter(model_pathmodel_int8.tflite) interpreter.allocate_tensors() inp interpreter.get_input_details()[0] out interpreter.get_output_details()[0] print(输入:, inp[name], inp[shape], inp[dtype], 量化:, inp[quantization]) print(输出:, out[name], out[shape], out[dtype], 量化:, out[quantization]) # 用一张真实图片跑一遍和 Keras 原模型对比 top-1 img tf.keras.utils.load_img(test.jpg, target_size(224, 224)) x tf.keras.utils.img_to_array(img) / 255.0 # uint8 模型把 [0,1] 还原成 [0,255] 再转 uint8 x_uint8 np.expand_dims((x * 255).astype(np.uint8), axis0) interpreter.set_tensor(inp[index], x_uint8) interpreter.invoke() y interpreter.get_tensor(out[index])[0] # 反量化scale 和 zero_point 从输出张量里取 scale, zero out[quantization] probs (y.astype(np.float32) - zero) * scale print(TFLite top-1:, int(np.argmax(probs)), float(np.max(probs)))这里最容易被忽略的是输出反量化。inference_output_type tf.uint8之后输出张量是 uint8np.argmax直接取也能得到正确类别因为量化是单调的但置信度数值完全不能用必须用(value - zero_point) * scale还原。很多 demo 里显示的「置信度 0.98」其实是没反量化的原始整数值除以 255看着像那么回事实际是错的。验证通过的标准有两条一是 top-1 类别和 Keras 原模型一致二是反量化后的置信度和原模型 softmax 输出的差距在 0.02 以内。达不到就回去查校准集和归一化不要带着问题进 Android。4. Android 端推理实现CameraX 取流、预处理与 Interpreter 调用4.1 CameraX 预览与 ImageAnalysis 配置取流这一层用 CameraX 比直接用 Camera2 省事得多ImageAnalysis的STRATEGY_KEEP_ONLY_LATEST能自动丢帧避免推理慢的时候队列堆积、画面延迟越来越大。这是移动端视觉 demo 的标配配置。private fun startCamera() { val cameraProviderFuture ProcessCameraProvider.getInstance(this) cameraProviderFuture.addListener({ val cameraProvider cameraProviderFuture.get() val preview Preview.Builder().build().also { it.setSurfaceProvider(binding.previewView.surfaceProvider) } val analysis ImageAnalysis.Builder() // 只保留最新帧推理跟不上时自动丢帧而不是排队 .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST) .setOutputImageFormat(ImageAnalysis.OUTPUT_IMAGE_FORMAT_RGBA_8888) .build() analysis.setAnalyzer(cameraExecutor) { imageProxy - val bitmap imageProxy.toBitmap() // RGBA_8888 直接转省掉 YUV 转换 val result classifier.classify(bitmap) runOnUiThread { renderResult(result) } imageProxy.close() // 必须关闭否则分析器会阻塞 } cameraProvider.unbindAll() cameraProvider.bindToLifecycle( this, CameraSelector.DEFAULT_BACK_CAMERA, preview, analysis ) }, ContextCompat.getMainExecutor(this)) }setOutputImageFormat(OUTPUT_IMAGE_FORMAT_RGBA_8888)是个实用开关。默认输出是 YUV_420_888转 Bitmap 需要写一段容易出错的 YUV 转换代码而且不同设备的 YUV 排列还有差异。改成 RGBA_8888 之后imageProxy.toBitmap()直接可用代价是多一次内存拷贝对 224 输入的分类任务完全可以接受。imageProxy.close()必须调且要在推理之后调或者至少保证一定被调用。漏掉这一行分析器只会收到第一帧然后画面就静止了——这个现象很像相机卡死实际是缓冲区没归还。4.2 图像预处理与 ByteBuffer 填充预处理是整条链路里最容易出错的一环核心是三件事缩放、通道顺序、数值类型。三者必须和转换时的约定逐字对齐。class ImageClassifier(context: Context) { private val interpreter: Interpreter private val labels: ListString private val inputSize 224 init { val model FileUtil.loadMappedFile(context, model_int8.tflite) val options Interpreter.Options().apply { setNumThreads(4) // 中端机 4 线程性价比最高 } interpreter Interpreter(model, options) labels context.assets.open(labels.txt).bufferedReader().readLines() } fun classify(bitmap: Bitmap): ListPairString, Float { val input interpreter.getInputTensor(0) val output interpreter.getOutputTensor(0) // uint8 模型每个像素 1 字节float32 模型则是 4 字节 val bytesPerChannel if (input.dataType() DataType.UINT8) 1 else 4 val buffer ByteBuffer.allocateDirect( 1 * inputSize * inputSize * 3 * bytesPerChannel ).order(ByteOrder.nativeOrder()) val resized Bitmap.createScaledBitmap(bitmap, inputSize, inputSize, true) val pixels IntArray(inputSize * inputSize) resized.getPixels(pixels, 0, inputSize, 0, 0, inputSize, inputSize) buffer.rewind() for (p in pixels) { val r (p shr 16) and 0xFF val g (p shr 8) and 0xFF val b p and 0xFF if (bytesPerChannel 1) { // RGB 顺序与训练时一致若训练用了 BGR 这里要换 buffer.put(r.toByte()); buffer.put(g.toByte()); buffer.put(b.toByte()) } else { buffer.putFloat(r / 255f); buffer.putFloat(g / 255f); buffer.putFloat(b / 255f) } } buffer.rewind() interpreter.run(buffer, ByteBuffer.allocateDirect( output.numElements() * if (output.dataType() DataType.UINT8) 1 else 4 ).order(ByteOrder.nativeOrder())) // 取输出并做反量化 softmax 归一 return postProcess(output) } }Bitmap.createScaledBitmap用的是双线性插值和训练时tf.image.resize的默认算法不完全一致但差距通常在千分位级别分类任务可以接受。如果模型对纹理极敏感可以在 Python 端改用ResizeMethod.BILINEAR对齐或直接在训练时用同一种插值。通道顺序这件事我建议在代码里留一行注释写死「训练用 RGB」别指望后来接手的人记得。这个 demo 的训练侧用的是tf.keras.utils.load_img默认 RGB所以 Android 端也按 RGB 填。反过来如果模型是用 OpenCV 读图训的默认 BGR这里就必须换顺序否则就是开头说的「所有图都识别成同一类」。4.3 Interpreter 调用与结果后处理Interpreter.run是最简单的一次性调用内部会做张量拷贝。对 224 输入的小模型这种开销可以忽略如果是多输入模型或者需要复用输入 buffer可以改用set_tensorinvoke。后处理的逻辑不长但几个细节值得写清楚。private fun postProcess(output: Tensor): ListPairString, Float { val shape output.shape() // [1, numClasses] val numClasses shape[1] val raw output.asByteBuffer().order(ByteOrder.nativeOrder()) val scores FloatArray(numClasses) if (output.dataType() DataType.UINT8) { val (scale, zeroPoint) output.quantizationParams() for (i in 0 until numClasses) { val q raw.get(i).toInt() and 0xFF scores[i] (q - zeroPoint) * scale } } else { for (i in 0 until numClasses) { scores[i] raw.getFloat(i * 4) } } // 计算 softmax把 logits 或分数转成概率 val maxScore scores.maxOrNull() ?: 0f val expSum scores.sumOf { kotlin.math.exp((it - maxScore).toDouble()) } val probs scores.map { kotlin.math.exp((it - maxScore).toDouble()) / expSum } return probs.indices .sortedByDescending { probs[it] } .take(3) .map { labels[it] to probs[it].toFloat() } }output.quantizationParams()返回的(scale, zeroPoint)就是转换时写进模型的量化参数必须用它反量化不能自己猜。int8 模型有时输出的是INT8类型而不是UINT8这时读字节要按有符号处理and 0xFF会把它变成错误的大正数得改成raw.get(i).toInt()。这个细节不同 TFLite 版本行为不完全一致拿到模型先打印output.dataType()确认。top-k 取 3 就够界面展示了。置信度低于 0.4 的时候我一般界面显示「无法确定」而不是硬给一个最高分类别——分类模型在分布外样本上的 softmax 经常很自信地给出错误答案这一点在产品层面要挡一下。5. 避坑排查真机联调里最常翻的五个车5.1 现象模型加载报NotFound但文件明明在 assets 里原因通常是noCompress tflite没配或者资源放在了res/raw却用loadMappedFile去读。FileUtil.loadMappedFile走的是AssetManager.openFd要求文件未被压缩且是 assets 路径。解决在build.gradle的aaptOptions里加noCompress tflite模型统一放src/main/assets/文件名大小写严格一致。改完记得 clean 再装增量打包有时不会重新处理 assets。5.2 现象推理不报错但所有图片输出同一个类别这是最高频的一类。原因按概率排通道顺序 RGB/BGR 反了归一化多做或漏做了一次校准集严重偏离真实分布导致 int8 模型塌缩。三者表现一模一样只能逐个排除。解决先用同一张图分别喂给 Python 端的model_fp32.tflite和model_int8.tflite看两者 top-1 是否一致。不一致是量化问题回去换校准集一致但 Android 端结果不同是预处理问题把 Android 端填入的 buffer 前 12 个字节 dump 出来和 Python 端x_uint8的前 12 个值逐字节比。我靠这个对比法定位过两次通道顺序问题比盲猜快得多。5.3 现象DataType mismatch或Cannot copy between a TensorFlowLite tensor原因几乎都是输入 buffer 的字节数和模型期望不符。uint8 模型期望224*224*3 150528字节如果按 float32 分配了 4 倍空间或者用putFloat往 uint8 张量里填就会抛这个错。解决先getInputTensor(0).dataType()拿类型再算bytesPerChannel不要写死。这个 demo 的预处理代码里用if (input.dataType() DataType.UINT8)分支处理两种类型就是为了让同一个分类器类能加载 fp32 和 int8 两个版本。5.4 现象预览流畅但识别结果滞后一两秒原因是对ImageAnalysis每帧都做了一次推理而推理耗时超过帧间隔CameraX 默认的背压策略会排队。STRATEGY_KEEP_ONLY_LATEST没设或者设了但imageProxy.close()在推理完成之前就被调用导致分析器以为处理完了实际结果还没用上。解决确认设置了KEEP_ONLY_LATEST并且在回调里先完成推理和结果读取最后再close()。另外可以在 UI 层做节流比如每 200ms 只处理一帧剩下的直接丢视觉上完全看不出差别。5.5 现象高端机正常低端机闪退或结果全零原因是低端机不支持某些委托或算子或者用了 float16 模型但设备 GPU 不支持 fp16。Interpreter加载失败时抛的异常信息往往很含糊只告诉你哪个算子不支持。解决先用 CPU XNNPACK 跑通确认所有机型都能出结果再逐步开 GPU 委托并做设备白名单。委托创建失败要能降级回 CPU代码里用 try-catch 包住Interpreter.Options().addDelegate(...)失败就换一个不带委托的 Interpreter 实例。这个降级逻辑建议一开始就写别等线上出问题再补。6. 进阶GPU 委托、线程数与一条可复现的精度回归模型能跑通只是及格线真正决定 demo 能不能变成产品的是延迟、功耗和精度的一致性。我一般在这三件事上收尾。第一件是 GPU 委托。对 float16 或 float32 模型GPU 能把单帧延迟压到 CPU 的三分之一到一半但 int8 全整型模型在 GPU 上不一定有收益因为很多设备对 int8 的 GPU 内核支持不完整。开关方式很简单val options Interpreter.Options().apply { setNumThreads(4) try { // GPU 委托对 float16 收益最大int8 模型建议实测后再决定 addDelegate(GpuDelegate()) } catch (e: Exception) { Log.w(Classifier, GPU 委托不可用降级到 CPU: ${e.message}) } }务必实测不要看文档拍脑袋。我在一台中端机上测过int8 模型走 GPU 反而比 4 线程 CPU 慢了 8ms原因是数据在 CPU 和 GPU 之间来回拷贝的开销吃掉了计算收益。判断标准很简单同一个模型、同一批图各跑 200 次取中位数差 5ms 以内就别折腾了。第二件是线程数。setNumThreads(4)在中端机上基本是拐点设到 8 收益很小还会和相机线程抢 CPU 导致预览掉帧。低端机大核少于 4 个建议设 2。这个参数不是越大越好属于典型的「调了才知道」项。第三件是精度回归。每次换模型、换量化策略我都会跑一份固定测试集记录 top-1 一致率和平均置信度和上一版对比回归项基线fp32int8判定top-1 一致率100%≥ 97%低于 97% 回退量化方案top-3 召回100%≥ 99%低于 99% 查校准集平均置信度偏差—≤ 0.05超了说明反量化有问题单帧延迟中端机45ms≤ 25ms不达标换 backbone这份表比任何口头结论都可靠。有一次我把校准集从 200 张加到 500 张模型体积没变top-1 一致率从 96.2% 提到 98.1%就是靠这张表发现的。最后说个习惯。从那以后我每次转完模型都强制先在 Python 端跑通「加载 → 打印张量契约 → 单图推理 → 反量化 → 和 Keras 对比」这一整套一步不省通过了才往 Android 里放。移动端联调的成本远高于 PC把问题挡在转换阶段比在真机上看 Log 猜原因划算得多。希望帮到你。本文还有配套的精品资源点击获取