简介：这份资源是一套面向 Android 开发者与移动端机器学习入门者的 TensorFlow Lite 图像分类实战 Demo，解决的是“模型在手机上如何训练推理、工程如何搭建、端侧识别如何用起来”的问题。压缩包共 110 个文件，约 3.76MB，包含 64 个 xml 布局与配置、4 个 Java 源码文件、3 个 gradle 构建脚本，以及 1 个 tflite 模型文件，另有 png 图标素材、bin 与 lock 等构建缓存和 properties 配置，工程结构完整，可直接导入 Android Studio 编译运行。目前已有 6821 人学习下载，属于较受关注的端侧推理入门样例。读者可从中了解 TFLite 模型的加载与调用流程、相机或图片输入的预处理、分类结果的输出与展示，以及 Gradle 依赖配置和资源文件组织方式，适合作为课程实验、毕业设计或移动端 AI 功能原型的起步参考，也便于对照排查模型路径、依赖版本等常见问题。

1. 一张图进手机到出结果：这个 TFLite 图像分类 Demo 到底解决了什么

模型在训练机上跑出 0.92 的准确率，塞进 Android 手机却吐出一堆看不懂的概率数组——这种落差我见过不止一次。这个 TensorFlow Lite 图像分类 Demo 处理的正是中间那段很少有人愿意写文档的路：把训练好的模型压进 APK 的 assets 目录，用 TFLite 解释器在端侧完成一次前向计算，再把输出张量翻译成标签和置信度。它面向两类人，一类是手里已经有模型、想搬到手机上的算法同学，另一类是接需求时要在一周内做出识别功能、又不想引入云端接口的 Android 开发。工程规模不大，但相机采集、图像归一化、线程调度、结果排序这几块凑齐了端侧推理的完整闭环，是少数能直接照着改的骨架工程。

2. 架构与选型：TFLite 在端侧推理链路里站哪个位置

2.1 训练侧与端侧的分工边界

端侧推理的第一条纪律是：手机不做训练，也不做特征工程，它只负责把一张图变成一维数组。TFLite 在这里承担的是解释器角色——读取.tflite文件里的算子图和权重，按顺序在 CPU 或 GPU 上执行，输入输出都是张量（Tensor），中间过程对上层完全封闭，某种意义上就是个黑匣子。所以架构上真正需要设计的是这个黑匣子的两侧：进它之前怎么把 Bitmap 变成它认识的形状，出它之后怎么把概率数组变成人能看懂的结果。

导出环节的约定必须在动手写代码之前钉死。一张 224×224 的 RGB 图，进入模型前的形状是[1, 224, 224, 3]，其中的 1 是 batch，端侧一次只处理一张。输出形状常见两种：ImageNet 1000 类加一个背景类是[1, 1001]，纯自定义 N 类是[1, N]。这两个数字如果不提前确认，后面所有代码都只能靠猜，而猜错的代价是排查时同时怀疑模型、预处理和标签映射三件事。

量化格式直接决定预处理代码长什么样，这个在项目开工前就得定下来。

我一般先用 float32 跑通整条链路，确认标签对得上，再换 int8 量化版本对比准确率。反过来做的话，一旦结果不对，你会同时怀疑量化和预处理两件事，排查成本翻倍。这个顺序看着笨，但能省掉一整天的瞎猜。

2.2 工程目录与模块职责

这套 Demo 的分层很朴素，没有引入 MVVM 或者依赖注入，好处是任何一段都能单独拎出来看。目录大致长这样：

app/src/main/ ├── assets/ │ ├── mobilenet_v1_1.0_224.tflite # 模型本体 │ └── labels.txt # 每行一个标签，顺序与输出索引严格对应 ├── java/com/example/classifier/ │ ├── MainActivity.java # 入口，处理相册选图和预览 │ ├── CameraActivity.java # 相机预览 + 逐帧送入分析器 │ ├── ImageClassifier.java # 模型加载、预处理、推理、后处理 │ ├── ImageProcessor.java # Bitmap 裁剪缩放的辅助类 │ └── Recognition.java # 结果实体：标签 + 置信度 + 索引 └── res/layout/activity_main.xml

ImageClassifier是整份工程的重心，它同时承担了四件事：加载模型、把 Bitmap 塞进 ByteBuffer、调用interpreter.run()、对输出做 Top-K 排序。这种把四段逻辑塞进一个类里的写法在 Demo 阶段没问题，真要上生产，我建议至少把预处理拆成独立的ImageProcessor，因为换模型时改的往往只有归一化那几行，而推理流程是不动的。

Recognition这个实体看着可有可无，但它在两处帮了忙：一是 Top-K 排序需要一个可比较的对象，二是 UI 层只消费字符串和浮点数，不需要知道模型的存在。这种隔离做得越早，后面把分类换成检测、换成关键点，改动面就越小。

2.3 构建依赖与关键配置

Gradle 这块有两处必须写对，写错了就是直接崩，不是性能问题。

android { // 关键：禁止 aapt 压缩 tflite 文件 // 压缩后 AssetManager.openFd() 会直接抛异常，模型只能整包读进内存 aaptOptions { noCompress "tflite" } } dependencies { implementation 'org.tensorflow:tensorflow-lite:2.14.0' implementation 'org.tensorflow:tensorflow-lite-gpu:2.14.0' implementation 'org.tensorflow:tensorflow-lite-support:0.4.4' }

noCompress "tflite"是这套工程里最容易漏的一行。openFd()要求 assets 里的文件能以文件描述符方式打开，如果被 aapt 压缩过，它会抛This file can not be opened as a file descriptor; it is probably compressed。另一种做法是用AssetManager.open()把整个模型读成字节数组再喂给 Interpreter，但这样模型会在 Java 堆里多留一份副本，几十 MB 的模型在低端机上很容易触发 GC 抖动。用openFd()+FileChannel.map()走内存映射，模型页由系统按需加载，对内存更友好。

GPU Delegate 那一行依赖看情况加。它在中端以上的机型上能把单帧推理耗时压下来一截，但老设备或者某些驱动上会直接返回错误的结果，或者首次初始化就崩。Demo 里通常留一个开关，默认关闭，需要时再打开对比耗时，比一上来就用 GPU 稳妥得多。

2.4 数据流：一次识别经过的六次形态转换

把整条链路摊平看，一张图从相机到屏幕要经过六次形态变化，每一步都有对应的出错点。

这张表我建议贴在调试时对着看。大多数"识别不准"的问题，落点都在第三行和第四行——图片被拉伸变形，或者归一化方式跟训练时不一致。模型本身很少是元凶，它只是忠实地把输入的错误放大出来。

3. 跑通第一张图：从 Gradle 配置到 assets 模型加载的完整步骤

3.1 环境准备与工程导入

Android Studio 用任意近两年的稳定版都行，SDK 上minSdkVersion设 21 足够，TFLite 的 Java API 本身要求不高；如果打算开 GPU Delegate，机型侧的 OpenGL ES 版本要够，这个只能靠真机测。工程不需要 NDK，也不需要 CMake，除非你要自己编译自定义算子，那种情况另说。

导入之后先别急着跑，把三件事确认一遍：local.properties里的 SDK 路径、Gradle 版本与 AGP 版本是否匹配、aaptOptions那行有没有被模板覆盖掉。我第一次拉这类工程时就是因为 AGP 版本太新，aaptOptions语法变了导致编译报错，折腾了半天才反应过来是构建脚本的问题而不是代码问题。

编译命令很简单：

# 只编译 debug 包，确认构建链路没问题 ./gradlew :app:assembleDebug # 装机并直接启动 ./gradlew :app:installDebug

如果assembleDebug阶段就失败，问题基本在依赖解析或者构建脚本；能编译但装上一启动就闪退，才轮到看 Logcat。这个区分能省不少时间。

3.2 模型与标签文件的放置约定

assets目录下的模型文件名没有强制规范，但labels.txt的顺序是硬约定：第 0 行对应输出张量的索引 0，第 1 行对应索引 1，依此类推，中间不能有空行或者注释行。这份文件错一位，整个识别结果的对应关系就全乱了，而且乱得很有迷惑性——置信度依然很高，只是标签全错。

读取标签的代码不复杂，但要注意编码和空白字符：

private List<String> loadLabels(Context context, String fileName) throws IOException { List<String> labels = new ArrayList<>(); // 用 UTF-8 显式指定编码，避免部分机型默认编码不同导致中文标签乱码 try (BufferedReader reader = new BufferedReader( new InputStreamReader(context.getAssets().open(fileName), StandardCharsets.UTF_8))) { String line; while ((line = reader.readLine()) != null) { String trimmed = line.trim(); // 跳过空行，但不跳过任何有效标签 if (!trimmed.isEmpty()) { labels.add(trimmed); } } } return labels; }

参数上只有一个坑值得说：context.getAssets()拿到的 AssetManager 是全局共享的，读完之后不用手动关，但InputStream一定要用 try-with-resources 关掉，否则连续多次加载（比如切换模型）会泄漏文件句柄。标签文件一般很小，几 KB，但习惯要养成。

模型文件建议连同一个版本号一起命名，比如mobilenet_v1_224_v2.tflite。换来换去的时候，没有版本号的model.tflite是灾难，你会分不清手机上跑的是哪一版。

3.3 首次运行的调用链验证

跑通的最小闭环只有三行调用：

// 1. 初始化，内部完成模型加载和输入形状探测 ImageClassifier classifier = new ImageClassifier(context, "mobilenet_v1_224_v2.tflite", "labels.txt"); // 2. 传一张 Bitmap 进去，内部做缩放、归一化、推理、排序 List<Recognition> results = classifier.classify(bitmap); // 3. 取第一条展示 Recognition top1 = results.isEmpty() ? null : results.get(0);

classify()内部是同步的，这一点很重要。Demo 里通常在相册选图之后调用，一帧几百毫秒，用户感觉不到卡顿；但一旦接到相机预览上逐帧调用，主线程立刻就被堵死，预览会一顿一顿的。这个转换点是从 Demo 走向可用产品的分水岭，后面第 6 章会细说。

调用之前建议先打一行日志，把模型的实际输入形状和数据类型打出来：

int[] shape = interpreter.getInputTensor(0).shape(); DataType type = interpreter.getInputTensor(0).dataType(); Log.d("TFLITE", "input shape=" + Arrays.toString(shape) + ", type=" + type);

shape一般是[1, 224, 224, 3]，type是FLOAT32或者UINT8。这两个值决定了预处理代码怎么写，硬编码 224 而不读它，是换模型时最常见的翻车原因。

3.4 结果核对：怎么确认跑对了

验证不能只看"有输出"，得看输出合不合理。我的做法是拿一张内容明确的图——比如一只猫、一辆车——跑一遍，然后人工检查 top-1 标签是不是对的，top-3 里有没有合理的近义类别。如果 top-1 是某个毫不相干的类，但置信度 0.99，那基本可以断定是归一化或者标签索引出了问题。

再补一步，把原始的输出数组前几位打出来：

float[][] output = new float[1][labels.size()]; interpreter.run(imgData, output); for (int i = 0; i < 5; i++) { Log.d("TFLITE", "idx=" + i + " label=" + labels.get(i) + " score=" + output[0][i]); }

如果这五个分数加起来离 1 很远，说明模型输出没有经过 softmax，或者你读错了张量下标；如果分数全是 0 或全是 NaN，说明输入张量根本没填进去，大概率是 ByteBuffer 的 position 没复位。这些现象比"结果不准"具体得多，定位起来快。

4. 核心代码拆解：ImageClassifier 里从 Bitmap 到 Top-K 的四段实现

4.1 Interpreter 初始化：线程数与 Delegate

初始化阶段做两件事：把模型映射进内存，配置解释器参数。

public ImageClassifier(Context context, String modelFile, String labelFile) throws IOException { this.labels = loadLabels(context, labelFile); Interpreter.Options options = new Interpreter.Options(); // 线程数一般取 2～4，超过物理大核数量反而会因为调度开销变慢 options.setNumThreads(4); // XNNPACK 对常见卷积有优化，浮点模型建议开 options.setUseXNNPACK(true); if (useGpuDelegate) { gpuDelegate = new GpuDelegate(); options.addDelegate(gpuDelegate); } interpreter = new Interpreter(loadModelFile(context, modelFile), options); // 从模型里读输入尺寸，而不是硬编码 224 int[] shape = interpreter.getInputTensor(0).shape(); imageSize = shape[1]; }

setNumThreads(4)这个值不要拍脑袋往大了写。推理的并行粒度有限，线程数超过设备的大核数量之后，线程切换的开销会盖过并行收益，实测反而更慢。我一般在 2 和 4 之间各测一次，取快的那个。

模型加载走内存映射：

private MappedByteBuffer loadModelFile(Context context, String name) throws IOException { AssetFileDescriptor afd = context.getAssets().openFd(name); try (FileInputStream fis = new FileInputStream(afd.getFileDescriptor())) { FileChannel channel = fis.getChannel(); // 映射区间必须用 startOffset + declaredLength，不能从 0 开始 return channel.map(FileChannel.MapMode.READ_ONLY, afd.getStartOffset(), afd.getDeclaredLength()); } }

startOffset和declaredLength两个参数不能省。assets 里的多个文件在 APK 内部是连续存放的，如果从 0 开始映射，你拿到的可能是前一个文件的尾部拼接上模型的前半段，Interpreter 会在解析阶段直接报ByteBuffer is not a valid flatbuffer model。这个报错看着吓人，原因其实很单纯。

4.2 预处理：Bitmap 到 ByteBuffer 的字节序陷阱

这一段是整份代码里最容易写错、也最难从报错信息里看出问题的地方。

private ByteBuffer convertBitmapToByteBuffer(Bitmap bitmap) { // 复用 ByteBuffer，避免每帧都分配几十 MB 触发 GC if (imgData == null) { imgData = ByteBuffer.allocateDirect(4 * imageSize * imageSize * 3); // 必须设成本机字节序，否则 putFloat 写进去的字节顺序是反的 imgData.order(ByteOrder.nativeOrder()); } imgData.rewind(); Bitmap resized = Bitmap.createScaledBitmap(bitmap, imageSize, imageSize, true); int[] pixels = new int[imageSize * imageSize]; resized.getPixels(pixels, 0, imageSize, 0, 0, imageSize, imageSize); int offset = 0; for (int i = 0; i < imageSize; i++) { for (int j = 0; j < imageSize; j++) { int val = pixels[offset++]; // ARGB_8888 里 R 在高 8 位，G 在中间，B 在低 8 位 float r = (((val >> 16) & 0xFF) - 127.5f) / 127.5f; float g = (((val >> 8) & 0xFF) - 127.5f) / 127.5f; float b = ((val & 0xFF) - 127.5f) / 127.5f; imgData.putFloat(r); imgData.putFloat(g); imgData.putFloat(b); } } imgData.rewind(); // 复位，让 Interpreter 从头读 return imgData; }

三个参数值得单独说。127.5f这个均值方差是 MobileNet 系列的标准配置，换成别的模型可能要用0～1的简单归一化或者 ImageNet 的均值方差，具体得看训练脚本，不能想当然。ByteOrder.nativeOrder()不加的话，float 的四个字节会以大端顺序写进去，而 ARM 是小端，读出来的数值完全是乱的——但程序不会崩，只会输出一堆无意义的概率，这才是最难受的那种 bug。

最后的rewind()漏掉的话，Interpreter 会从 buffer 的当前 position 开始读，读到的是空的尾部，表现是输出恒定值。这个坑我踩过一次，对着模型怀疑了两小时，最后发现是少了一行复位。

4.3 推理执行与张量形状核对

推理本身只有一行，但周边的形状核对不能省。

public List<Recognition> classify(Bitmap bitmap) { ByteBuffer input = convertBitmapToByteBuffer(bitmap); // 输出数组的大小必须等于标签数量，否则 run() 会抛异常 float[][] output = new float[1][labels.size()]; interpreter.run(input, output); return postProcess(output[0]); }

run()是同步阻塞的，返回时结果已经写进output。如果模型有多个输出，这里要传对应的数组个数，少传一个就会报Output error: number of outputs mismatch。对于分类模型只有一个输出，形状是[1, N]，用二维数组接住是为了保持 batch 维度。

有个细节容易忽略：interpreter.run()不做输入校验，你给的 ByteBuffer 大小如果跟模型期望的不一致，它会截断或者读取越界，表现是结果乱或者直接 native crash。所以在调试阶段我习惯加一句断言，把 buffer 容量和imageSize * imageSize * 3 * 4比一下，早发现早省事。

4.4 Top-K 后处理与标签映射

输出是一维概率数组，长度等于类别数，后处理要做的是排序取前 K 个，并且过滤掉低于阈值的。

private List<Recognition> postProcess(float[] scores) { PriorityQueue<Recognition> pq = new PriorityQueue<>( 5, (a, b) -> Float.compare(b.getConfidence(), a.getConfidence())); for (int i = 0; i < scores.length; i++) { // 阈值默认 0.1，低于它的结果对用户没有意义，还会挤占榜位 if (scores[i] < 0.1f) continue; // 索引越界保护：标签数少于输出数时跳过，避免崩溃 if (i >= labels.size()) break; pq.add(new Recognition(i, labels.get(i), scores[i])); } List<Recognition> result = new ArrayList<>(); while (!pq.isEmpty() && result.size() < 3) { result.add(pq.poll()); } return result; }

这里有个真实存在的偏差要提前知道：ImageNet 的浮点模型输出往往是 1001 维，多出来的那一维是背景类，而labels.txt通常只有 1000 行。两者差一位，如果你不做保护，最后几类的标签会整体错位。稳妥的做法是在导出模型时确认清楚，或者在读取标签时判断数量并打一条警告日志，让问题显式暴露出来，而不是默默错下去。

5. 排查笔记：端侧推理最容易犯的五个错误

5.1 输出全是同一类，置信度还接近 1.0

现象：不管喂什么图，top-1 永远是同一个标签，分数稳定在 0.98 以上，看起来"特别自信"。

原因：输入张量根本没被正确填充，或者填充方式与模型的dataType不匹配。最常见的是模型已经是 int8 量化版本，代码里还在用putFloat()往里写四字节浮点，导致 Interpreter 读到的是一堆错位的字节；另一种是imgData.rewind()漏了，buffer 的 position 停在末尾。

解决：先打印interpreter.getInputTensor(0).dataType()，是UINT8就改成put((byte) value)，是FLOAT32才用putFloat。然后把 buffer 的capacity()和模型期望的字节数对一遍。这类问题没有玄学成分，全是字节层面的对不上。

5.2 一进相机就崩，日志指向 openFd

现象：应用启动没问题，点开相机或者第一次识别瞬间崩溃，堆栈里是AssetManager.openFd抛出的 IOException，提示文件可能被压缩。

原因：aaptOptions里没有排除.tflite，模型被 aapt 压缩进了 APK，无法以文件描述符方式打开。

解决：在android块里补上aaptOptions { noCompress "tflite" }，重新 clean 构建。注意改完必须 clean，增量构建有时不会重新打包 assets，你会以为改了没用。

5.3 换了自己的模型，报形状不匹配

现象：Cannot copy from a TensorFlowLite tensor with shape [1,224,224,3] to a Java object with shape [1,192,192,3]，或者直接 native crash。

原因：代码里把输入尺寸硬编码成了 224，而新模型是 192；或者新模型的输入是灰度单通道，代码还在按三通道写。

解决：在构造函数里从getInputTensor(0).shape()读尺寸，通道数也从 shape 的最后一维取，预处理的循环条件跟着改。硬编码在 Demo 阶段方便，在换模型阶段就是纯粹的负债。

5.4 连续识别几十次之后内存一路涨

现象：单张图识别没问题，接到相机预览上跑一两分钟，内存曲线持续上升，最后 OOM 或者被系统杀掉。

原因：每帧都Bitmap.createScaledBitmap()新建一张图，每帧都ByteBuffer.allocateDirect()新分配一块直接内存，两者都不在 GC 的快速回收路径上，尤其直接内存要等 full GC 才释放。

解决：ByteBuffer 提到成员变量里复用，尺寸变了才重新分配；缩放后的 Bitmap 用完立刻recycle()，或者干脆用Bitmap.createScaledBitmap之外的方案，比如先画到一块复用的 Canvas 上。GPU Delegate 也要在onDestroy里显式close()，它持有的 native 资源不受 Java 内存管理约束。

5.5 模拟器上识别正常，真机完全不准

现象：同一张图，模拟器 top-1 正确，装到手机上结果离谱，但程序不崩。

原因：大部分情况是图片方向问题。手机拍的照片在 EXIF 里记录了旋转角度，BitmapFactory.decodeFile默认不会自动旋转，你拿到的是横向的图，缩放成 224×224 之后内容被拉伸变形，模型自然认不出。少数情况是 GPU Delegate 在特定驱动上算错了结果。

解决：读 EXIF 的TAG_ORIENTATION，按角度做一次矩阵旋转再送进模型。排查时可以先关掉 GPU Delegate 用纯 CPU 跑一遍，两边结果一致就说明是预处理问题，不一致才去怀疑 Delegate。

6. 二次开发：换模型、接实时相机、做批量识别的三条改造路径

换模型是最常见的一步，难度取决于新模型和旧模型的接口差异。如果输入形状和数据类型都一致，改assets里的文件名和labels.txt就行，代码一行不用动。如果不一致，要同步改三处：imageSize已经在构造函数里从 shape 读了，但归一化的均值方差是写死的，得跟着训练脚本改；输出维度也从labels.size()改成了动态读取；如果模型带多个输出，run()的参数要跟着变成数组。我习惯在换模型之后先跑一张已知答案的图，把 top-3 打出来人工确认，再往下做功能。

接实时相机是第二个坎。相机的ImageAnalysis回调频率通常是 30fps，同步推理肯定跟不上，标准做法是把分析器设成STRATEGY_KEEP_ONLY_LATEST，并且限制回调节奏，比如每 300ms 才送一帧进模型。

ImageAnalysis analysis = new ImageAnalysis.Builder() .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST) .setOutputImageFormat(ImageAnalysis.OUTPUT_IMAGE_FORMAT_RGBA_8888) // 绕开 YUV 手动转换 .build(); analysis.setAnalyzer(executor, image -> { long now = System.currentTimeMillis(); if (now - lastInferTime < 300) { image.close(); return; } // 主动丢帧 lastInferTime = now; Bitmap bmp = Bitmap.createBitmap(image.getWidth(), image.getHeight(), Bitmap.Config.ARGB_8888); bmp.copyPixelsFromBuffer(image.getPlanes()[0].getBuffer()); // 推理放到独立线程，结果通过 Handler 回主线程 image.close(); });

OUTPUT_IMAGE_FORMAT_RGBA_8888这个设置能省掉一整段 YUV 转 RGB 的代码，代价是内存占用略高，在中端机上完全可接受。image.close()必须每帧都调，漏一次就会让相机管线卡住，表现是预览画面冻住不动。

第三条路是做批量识别，比如从相册一次选十张图。这时候可以在一个固定线程池里串行跑推理，复用同一个 Interpreter 实例，不要每次new，因为 Interpreter 的构造本身就要解析模型图，开销比一次推理还大。如果想省掉自己写前后处理，也可以换成 Task Library 里的ImageClassifier，它把标签加载、归一化、Top-K 都封装好了，代价是灵活性下降，自定义归一化方式时会比较别扭。

关于验证，我有个固定习惯：每次改完预处理相关代码，都拿同一张"标准图"跑一遍，把 top-3 结果和置信度记在笔记里，改前改后对比。这套流程听起来笨，但确实救过我一次——某个版本我调了缩放算法，视觉上看不出区别，结果置信度从 0.91 掉到 0.62，靠对比才发现是插值方式变了。从那以后我每次动 Bitmap 相关代码都强制走一遍这个对照，不敢再凭"看起来差不多"下判断。希望帮到你。

本文还有配套的精品资源，点击获取