简介这是一份基于TensorFlow Lite框架在Android手机上完成图像分类功能的可运行示例工程适用对象包括移动端应用开发者、计算机视觉初学者以及希望在项目中快速接入端侧推理模型的工程师。工程以Android Studio项目为载体把轻量级推理模型与Java代码、XML界面布局和资源文件整合在同一工程内完整展现了加载模型、对输入图像进行缩放与归一化预处理、执行推理运算以及解析输出结果并展示给用户的全部环节能帮助读者直观理解端侧AI应用的真实工作方式。压缩包共110个文件其中有64个XML用于界面、主题与配置4个Java源文件承担主要业务流程3个Gradle脚本负责构建依赖1个tflite文件存放训练好的分类模型其余还包括PNG图标资源、JAR库及属性文件等整体体积约3.76MB目录结构紧凑清晰便于定位模型、代码与配置文件。目前已有6820人学习下载这份入门级demo既可供零基础用户学习TFLite部署思路也可作为实际项目的开发起点在此之上替换模型、调整界面或扩展新的图像分类类别。1. 一张图片在 Android 上的分类旅程TF Lite demo 到底给了什么用 TensorFlow Lite 在 Android 手机上做图像分类最容易卡住的不是算法而是「第一步」。我第一次拿到这类 demo 时以为要自己训练模型结果打开工程发现训练好的 .tflite、Android 端的推理代码、预处理方法都齐了Build 完就能把 APK 装到手机上看效果。对刚入门的人来说这个 demo 解决的是「从哪下手」的问题先用最小代价跑通一条完整链路再沿着代码往回挖。这篇文章按我拆这套 demo 的顺序来写——模型怎么转、工程怎么接、参数怎么设、哪些地方会翻车尽量到细节为止。它适合两类人一类是想验证 TF Lite 在手机上到底能不能用的评估者另一类是已经跑通但识别效果差、想定位是哪里出错的开发者。2. 模型转换那一步把训练产物压成手机能跑的 .tflite2.1 为什么不能直接塞 SavedModel 进 Android训练好的模型常见产出是 SavedModel 目录或者单个 H5 文件体积大、格式里包含训练节点和没必要的调试信息。Android 端跑不了 SavedModel原因不只是体积还有算子差异训练用的算子集合比移动端 runtime 支持的宽得多而且运行时依赖 Python 环境。TF Lite 做的事情是把训练图重新解析一遍映射到TFLITE_BUILTINS里的算子集同时把权重重排成适合移动端读取的布局。所以整个链路的标准顺序是训练产出 → converter 转成 .tflite → 放 assets → Android 端 Interpreter 加载。demo 里的 .tflite 一般直接放在 assets但后续换自己的模型必须自己走一遍 converter这一节就是为此准备的。下面是从 SavedModel 转换的最简写法import tensorflow as tf converter tf.lite.TFLiteConverter.from_saved_model( saved_model_dir ) converter.optimizations [tf.lite.Optimize.DEFAULT] tflite_model converter.convert() with open(mobilenet.tflite, wb) as f: f.write(tflite_model)optimizations设置为DEFAULT表示允许转换器做权重压缩不设的话产出的就是完全未量化的 float32 模型体积和速度都不理想。这个版本转出来的模型还保留 float32 的输入输出对新手最友好Android 端喂 float 数据不用处理 int8 的额外细节。convert()失败时最常报错的是「某些算子没有对应 TFLite 实现」解法通常是换模型结构或者升级 runtime 版本后面避坑章节会细说。如果你手里只有 Keras 训练好的模型对象把from_saved_model换成from_keras_model(model)即可其余参数一致。转换失败的日志里如果出现算子名先别急着换模型去查这个算子是不是已经被新版本 TFLite runtime 支持——很多时候不是模型的问题而是转换器版本太老。真正让很多人在转换这一步翻车的是 int8 量化因为 int8 转换强制要求一个「代表性数据集」来做激活值范围统计def representative_dataset(): for _ in range(100): img load_sample_image(224, 224) # 从训练集/验证集抽取样本 yield [img.astype(np.float32)] converter tf.lite.TFLiteConverter.from_keras_model(model) converter.optimizations [tf.lite.Optimize.DEFAULT] converter.representative_dataset representative_dataset converter.target_spec.supported_ops [tf.lite.OpsSet.TFLITE_BUILTINS_INT8] converter.inference_input_type tf.int8 converter.inference_output_type tf.int8 tflite_int8_model converter.convert()representative_dataset里每个 yield 出来的数组shape 必须和模型输入完全一致np.float32类型也不能错。数量不一定要 1000 张100 张通常就够但类别要分布均匀不然统计出来的范围会偏向某几类像素。inference_input_type和inference_output_type设为 int8 后Android 端喂 ByteBuffer 也要按 int8 排布这一点几乎每次都会有人踩避坑章节会展开。2.2 三种量化方式怎么选量化方式选择其实就三档大多数场景用不到更复杂的混合量化。方案权重精度激活精度体积缩减精度损失适用场景不量化float32float32无无功能验证、效果对标动态范围int8 权重float32约 75%很小大多数 CPU 推理推荐首选float16float16float32约 50%很小配合 GPU delegate 跑全 int8int8int8约 75%需评估无 GPU 的嵌入式设备动态范围和全 int8 的代码差别就在representative_dataset和inference_input_type两处。如果只看体积动态范围和 int8 差不多但激活值仍是 float所以速度和功耗不如全 int8。我的建议是demo 验证阶段用不动配置的 float32 跑通链路然后直接换动态范围量化最后再用 benchmark 工具对比耗时而不是上来就 int8。如果目标设备确认有 GPU delegate 参与推理float16 才是最佳档。转换代码只需在 DEFAULT 优化基础上加一行converter.target_spec.supported_types [tf.float16]。这个模型在 CPU 上一般不会比 float32 快但上了 GPU 后数据传输带宽减半收益很明显。很多人误以为 float16 只是体积小实际它的价值在带宽而不是体积。「转换完模型变小了但精度掉了」是常态不是 bug。每转出一版我都会在 PC 上用测试集抽 100 张图算一遍 top-1 准确率对比转换前后的差距有没有超过 1 个点。如果超过了优先换 float16还不行就检查 representative dataset 的采样分布。曾有一次我图省事直接从训练集前 100 张取样本结果那 100 张全是同一个背景量化范围统计严重偏移准确率掉了 6 个点换成随机均匀采样后问题消失。2.3 转换完先做三个检查import numpy as np import tensorflow as tf interpreter tf.lite.Interpreter(model_pathmobilenet.tflite) interpreter.allocate_tensors() input_details interpreter.get_input_details()[0] output_details interpreter.get_output_details()[0] print(input_details[shape], input_details[dtype]) print(output_details[shape], output_details[dtype]) img load_preprocessed_image(224, 224).astype(np.float32) interpreter.set_tensor(input_details[index], img[np.newaxis, ...]) interpreter.invoke() logits interpreter.get_tensor(output_details[index])这段脚本验证的是「模型在 PC 上推理正常」。get_input_details()返回的 shape 和 dtype 是 Android 端喂数据时唯一准绳shape 通常是[1, 224, 224, 3]dtype 可能是float32也可能是int8以打出来的结果为准。set_tensor的第二个参数维度必须带 batch 维直接用img而不加np.newaxis是常见的低级错误会报 shape mismatch。确认 PC 端能出合理 logits 后再接 Android 端能隔离一大部分问题。提示转换后第一时间记录 input_details 的 shape 和 dtypeAndroid 端一切数据排布都以它为基准。3. Android 工程接入Task Library 与 Interpreter 两种姿势3.1 先分清两个入口别混着用TF Lite 在 Android 上有两层 API。高阶的ImageClassifier属于 Task Library它把模型加载、输入预处理、置信度过滤、按分数排序全包了代码量最小。底层的Interpreter是直接和 .tflite runtime 打交道从 Bitmap 到 ByteBuffer 的所有转换都得自己写。维度ImageClassifier (Task Library)Interpreter (底层)预处理内置按模型 metadata 自动做全手动输出封装好的 ClassificationResult原始 logits线程数控制通过 options 设置setNumThreads自定义程度低高demo 工程里如果两个入口都有代码新手最常见的翻车方式是用 ImageClassifier 加载模型又自己写了一套归一化结果置信度全部变成 0.9 以上看不出差别。Task Library 的 ImageClassifier 会读取模型里的 metadata自动做归一化和 resize再手动预处理等于做了两遍。所以原则是想快用 Task Library 并别动它的输入管线想完全控制用 Interpreter 并接受所有细节自己负责。3.2 依赖与模型放置第一步就把位置放对dependencies { implementation org.tensorflow:tensorflow-lite implementation org.tensorflow:tensorflow-lite-support }版本号一般跟随你下载的 demo 保持一致用 2.x 系列即可。注意tensorflow-lite-support不是 Interpreter 的必需依赖但 ImageClassifier 那套 Task Library 要用所以直接两个都加上省得后面补。模型文件统一放src/main/assets/目录不要放res/raw因为 assets 能用openFd拿到文件描述符做 mmapraw 资源读取大文件时的内存效率差很多。3.3 加载模型用 mmap 而不是读字节把模型加载成MappedByteBuffer的标准做法是private fun loadModelFile(context: Context, path: String): MappedByteBuffer { val fd context.assets.openFd(path) val fileChannel FileChannel.open( fd.fileDescriptor, FileChannel.MapMode.READ_ONLY ) return fileChannel.map( FileChannel.MapMode.READ_ONLY, fd.startOffset, fd.length ) }assets.openFd能拿到文件偏移和长度FileChannel.map把模型文件映射成只读的 mmap模型并不会真正全部加载进内存加载速度和内存占用都优于assets.open(path).readBytes()。这段代码里最容易漏的是fd.startOffset因为 assets 文件可能被 zip 压缩过直接从文件头映射会读到无关字节打开模型时会报file is corrupt。避坑章节会讲怎么让 Gradle 不压缩 .tflite。3.4 第一次推理跑通它val options Interpreter.Options().apply { setNumThreads(4) } val interpreter Interpreter(loadModelFile(context, mobilenet.tflite), options) val inputSize 1 * 224 * 224 * 3 * 4 // batch * h * w * channels * float字节 val inputBuffer ByteBuffer.allocateDirect(inputSize) inputBuffer.order(ByteOrder.nativeOrder()) val outputSize 1 * 1000 * 4 // batch * 标签数 * float字节 val outputBuffer ByteBuffer.allocateDirect(outputSize) outputBuffer.order(ByteOrder.nativeOrder()) interpreter.run(inputBuffer, outputBuffer) interpreter.close()ByteBuffer.allocateDirect必须是 direct bufferJVM 堆内 buffer 会导致 JNI 层复制或直接报错order(ByteOrder.nativeOrder())设置字节序也不能省手机几乎都是小端不设默认大端会把 float 全读反。run()是同步阻塞调用单次推理在 CPU 上大约几十到几百毫秒绝不能放在主线程。close()释放的是 Interpreter 持有的 native 内存要在推理全部结束后调用别在每帧推理后反复创建和销毁实例。如果是走 Task Library 入口加载和推理缩短成三行val classifier ImageClassifier.createFromFile(context, mobilenet.tflite) val results classifier.classify(bitmap) val first results[0].categories[0]classify()入参直接接收 Bitmap不用自己转 ByteBuffer前提是你的 .tflite 带 metadata。如果模型是不带 metadata 转出来的ImageClassifier 会直接报错找不到输入 tensor 的元信息这种情况要么用原生 Interpreter要么给模型加 metadata没有捷径。加载模型失败时logcat 里通常会打Could not open xxx.tflite或Didnt find tensor前者先查路径和压缩后者查模型和代码的输入签名不一致。4. 图像预处理与推理参数影响结果的不只是模型4.1 先对齐模型输入要求再谈参数Android 端拿到 Bitmap 之后必须按模型的输入要求做 resize 和归一化。不同模型的输入尺寸不一样MobileNetV2 这类常用的是 224×224但也有 128×128 的轻量模型和 256×256 的高精度模型。不要看 demo 里的尺寸就照抄正确做法是先用第 2 章的脚本打印input_details[shape]拿到当前 .tflite 真正期望的宽高和通道顺序再往下写代码。4.2 Bitmap 到 ByteBuffer 的完整转换private fun bitmapToInput(bitmap: Bitmap): ByteBuffer { val resized Bitmap.createScaledBitmap(bitmap, 224, 224, true) val pixels IntArray(224 * 224) resized.getPixels(pixels, 0, 224, 0, 0, 224, 224) val buffer ByteBuffer.allocateDirect(224 * 224 * 3 * 4) buffer.order(ByteOrder.nativeOrder()) for (pixel in pixels) { val r ((pixel shr 16) and 0xFF) / 255.0f val g ((pixel shr 8) and 0xFF) / 255.0f val b (pixel and 0xFF) / 255.0f buffer.putFloat(r) buffer.putFloat(g) buffer.putFloat(b) } return buffer }这段代码有三个容易出问题的点。第一个是缩放用createScaledBitmap默认的 FILTER_BITMAP 会做双线性过滤比关闭过滤直接取样效果好别为了省时间用 false 参数。第二个是通道顺序Android 的getPixels返回 ARGB 格式但 MobileNet 系列是按 RGB 通道训练的所以提取顺序是 r、g、b如果换到按 BGR 训练的模型顺序就得反过来否则识别结果会离奇地差。第三个是归一化方式这里用的是[0, 1]缩放也有模型训练时用的是[-1, 1]也就是(value / 255.0f) * 2.0f - 1.0f两个写错一个模型就废了具体看训练时的标准化配置不能靠猜。4.3 直接拉伸还是保持宽高比裁剪很多 demo 直接createScaledBitmap(bitmap, 224, 224, true)把任意宽高比的照片硬拉成正方形。这种做法能用但细节丰富的物体常常被拉变形模型没见过这种分布时准确率会下降一两个点。MobileNet 系列训练时就用了中心裁剪推理也走中心裁剪效果更稳定val ratio min( 224f / bitmap.width, 224f / bitmap.height ) val scaledW (bitmap.width * ratio).toInt() val scaledH (bitmap.height * ratio).toInt() val scaled Bitmap.createScaledBitmap(bitmap, scaledW, scaledH, true) val startX (scaledW - 224) / 2 val startY (scaledH - 224) / 2 val cropped Bitmap.createBitmap(scaled, startX, startY, 224, 224)这段代码先把图片等比缩放到短边刚好覆盖 224再从中间裁出正方形。代价是丢了边缘信息但对大多数分类场景中心和主体才是关键边缘丢一点比整体变形影响小。如果你的任务靠边缘特征识别比如文档拍照分类那反而用拉伸更合适这是个需要实际对比的选择。4.4 线程数、buffer 复用与单次推理setNumThreads不是越大越快。移动端 CPU 大核通常只有 24 个线程开 8 个反而因为线程切换开销变慢。我一般先设 4跑 benchmark 看 P50 耗时再试 2 和 6选最小的。输入 batch 维基本固定为 1Interpreter 不支持推理中途改 batch size所以别想着一个 buffer 塞多张图。每次推理都allocateDirect一次是典型的浪费。正确做法是在初始化时把 input/output buffer 建好推理循环里重复使用。getPixels返回的IntArray也可以复用这三个对象的分配对 GC 的影响在实时识别场景下比模型推理本身还要明显。4.5 输出 logits 如何变成可读标签Interpreter 方式拿到的outputBuffer是原始 logits还得自己找出最大值对应的下标val scores FloatArray(1000) outputBuffer.asFloatBuffer().get(scores) val argmax scores.indices.maxByOrNull { scores[it] } ?: -1 val label labels[argmax]labels数组从assets/labels.txt按行读取顺序必须和模型训练时的类别顺序一致。这个文件跟 .tflite 是一一对应的换模型必须同时换 labels只换模型不换 labels 会出现「识别出一堆乱标签」的怪现象原因其实简单下标和类别对不上。5. 避坑指南TF Lite 图像分类最常见的五个坑5.1 模型放 assets 后报「Could not open」现象APK 装到真机上加载模型直接从openFd抛异常日志提示 assets 文件找不到或损坏但 PC 上模型文件明明能打开。原因.tflite 超过 1MB 后被 AAPT 压缩openFd拿到的文件描述符指向压缩后的存储位置FileChannel.map映射了一段无效数据并不真的代表模型文件坏了。解决在 app 模块的 Gradle 配置里关闭对 .tflite 的压缩android { androidResources { noCompress tflite } }加完重新 Build 再安装问题消失。如果你用assets.open按字节流读也可能不报这个错但 mmap 方案加载大模型的内存优势就没了二选一别混着用。5.2 输入 shape 对不上模型不报错结果全是垃圾现象推理能跑完返回的 logits 数值不小softmax 后也有明显的最大值但对应到标签完全是乱的不同图片的 top-1 几乎固定。原因模型训练时输入是 NCHW 排布转成 TFLite 后 Android 端按 NHWC 喂数据数据排列和模型期望不一致logits 看起来「正常」实际全是错位计算的结果。解决转换后第一件事就是打印interpreter.get_input_details()[0][shape]。如果是[1, 3, 224, 224]说明模型期望 NCHWAndroid 端要把像素循环改成先遍历通道再遍历空间位置或者转换时加参数强制排布成 NHWC。这类问题最玄学的地方在于它不崩溃、不报错只是结果不可信所以我把检查 shape 排在一切调试的第一步。5.3 int8 量化模型在 CPU 上跑得比 float32 还慢现象按第 2 章转了全 int8 模型体积确实小了很多装到真机上测耗时反而比原 float32 版本慢 20% 以上。原因int8 推理要发挥速度优势依赖 CPU 对 int8 指令集的支持以及相应 delegate 的加载。不少手机没有对应的向量扩展TFLite 会退化成逐元素转换再加上模型输入输出如果仍是 float32每帧推理都要做两次类型换算成本反而更高。解决别一上来就追求全 int8。先在 Android 端用动态范围量化模型跑同一组 benchmark 数据对比耗时和精度。如果动态范围已经满足需求就没必要上 int8如果确实要 int8用 benchmark 工具确认目标机型的类型转换开销和算子耗时再决定是否保留。5.4 相机照片识别效果差方向与 EXIF现象从相册选一张竖着拍的照片识别准确率明显低于横拍的图片同一个物体换个角度就分错。原因BitmapFactory 解码时不会读取 EXIF 里的旋转信息竖拍照片在 Java 层表现为宽高颠倒直接缩放到 224×224 就把内容压扁了模型从没见过这种「压扁」的分布结果自然不对。解决解码后用ExifInterface读ORIENTATION标签按角度做旋转再 resizeval ei ExifInterface(inputStream) val orientation ei.getAttributeInt( ExifInterface.TAG_ORIENTATION, ExifInterface.ORIENTATION_NORMAL ) val matrix Matrix() when (orientation) { ExifInterface.ORIENTATION_ROTATE_90 - matrix.postRotate(90f) ExifInterface.ORIENTATION_ROTATE_180 - matrix.postRotate(180f) ExifInterface.ORIENTATION_ROTATE_270 - matrix.postRotate(270f) } val rotated Bitmap.createBitmap(bitmap, 0, 0, bitmap.width, bitmap.height, matrix, true)这一步经常被忽略因为测试时用设备自带的横屏截图几乎不会暴露一旦真实用户用竖拍或者翻转图识别率立刻雪崩。我现在的习惯是预处理函数的第一个步骤永远是「矫正方向再缩放」不管图片来源是相机还是相册。5.5 推理不挪出主线程ANR 跑不掉现象demo 里点击识别按钮后界面卡住过几秒系统弹出「无响应」对话框日志里能看到 ANR 记录。原因interpreter.run()是同步阻塞的模型推理耗时从几十到几百毫秒长时间占用 UI 线程必然触发 ANR。解决用一个单线程 executor 隔离推理UI 线程只负责发起和收结果private val executor Executors.newSingleThreadExecutor() executor.execute { val result predict(bitmap) runOnUiThread { showResult(result) } }注意推理用的Interpreter实例不能被多个线程同时调用单线程 executor 顺带解决了并发访问问题。比较稳妥的做法是把这个 executor 和应用生命周期绑定页面销毁时shutdown()不然旋转屏幕重建 Activity 时会攒下多个推理任务排队。6. 把 demo 从「能跑」提升到「能用」benchmark 与 GPU delegatedemo 跑通只是起点真机测试时你会发现不同机型的耗时差异极大。第一步是上 benchmarkTF Lite 自带的 benchmark_model 工具可以直接在 PC 上模拟移动端推理耗时命令行参数很直白指定模型路径、线程数、预热次数和正式跑的次数最后输出平均耗时和单算子耗时排名。我用它来对比「float32、动态范围、float16、int8」四版模型在同一台机器上的延迟数据出来后就知道该不该折腾量化。第二步是 GPU delegate。接入代码很简洁在创建 Interpreter 前加一个 delegate 即可val gpuDelegate GpuDelegate() val options Interpreter.Options().apply { addDelegate(gpuDelegate) setNumThreads(4) } val interpreter Interpreter(modelBuffer, options)GPU delegate 对 float16 模型尤其友好卷积和全连接层在 GPU 上能跑出比 CPU 好几倍的吞吐率。但它有两个边界不是所有算子都能在 GPU 上执行遇到不支持的算子会抛错或回退另外第一次初始化有几百毫秒的预热必须在页面进入时就创建 delegate而不是第一次点击才创建。从那以后我每次拿到一个 TF Lite 图像分类工程都强制走一遍同样四步打印 input details 核对 shape 和 dtypePC 端先跑一次推理对比 logits真机上 benchmark 四版模型最后再决定加不加 GPU delegate。这套流程挡住了我过去几个月里至少三处暗坑也希望帮到你。本文还有配套的精品资源点击获取