Showing Posts From

Tflite

如何把PT格式的模型转换为TFLite/LiteRT模型？

之前在尝试把Ultralytics的YOLOv8模型运行在Android手机上的过程（参考总结Android Flutter项目中YOLO模型的执行流程）中，直接使用了YOLO模型的export接口即可实现把该模型导出为ONNX、TFLite等格式。但是如何我们在开发过程中遇到的模型没有官方所提供的export接口，如何能够把pt格式的模型文件转换为TFLite，从而方便的部署在Android手机上呢？ 因此，本文尝试解决这样的问题：如何把一个通用的 PyTorch 模型权重（.pt）文件，通过模型转换处理，变成在 Android 端侧能跑的 TFLite 模型文件（.tflite）？ Google的AI Edge Torch/Litert 针对以上所提出的问题，一个比较流行的解决方案是： - PyTorch (.pt) → ONNX: ONNX 是模型交换的通用格式，所以这一步转换相当于是把模型文件脱离了 PyTorch 的框架限制。 - ONNX → TensorFlow (SavedModel): 这是一个转译过程，从ONNX的生态语言转换为TensorFlow生态，确保目标平台（即Google 手机APP）能正确的识别模型文件中的算子。 - TensorFlow → TFLite: 这有点类似于 Linux 下的 strip 和 objcopy，这一步操作会进行常量折叠、算子精简以及最重要的量化操作（Quantization），把默认的 FP32 的权重参数变成 INT8，以适应移动端 CPU/NPU 的算力和存储方面的限制。 但是，以上这个传统的 PT -> ONNX -> TF -> TFLite 路径并非是一个完美的解决方案。这是由于， PyTorch 坚持使用 NCHW (即所谓的Channel First) 而 TensorFlow 则默认使用 NHWC (即所谓的Channel Last)，那么转换工具在以上传统的转换路径中为了保住数学上的等价性，会疯狂插入 Transpose 算子。这在手机 CPU/GPU 上运行过程中，会导致频繁的内存重排，严重拖慢推理速度。 因此，Google 在2024年4月推出了一个AI Edge Torch的工具，用于实现从 PT 模型文件向TFLite格式模型文件的直接转换。这个工具利用了 torch.export（PyTorch 2.x 的核心特性）直接捕获计算图，并将其映射为 TFLite 算子，更重要的是，它可以直接在模型转换过程中对齐推理过程中的数据格式，这样就消除了大量不必要的 Transpose 算子，避免后续推理过程要执行的大量内存重排。 到了2025年，Google 对移动端 AI 生态进行了一次品牌重塑：之前的TensorFlow Lite被重新命名为LiteRT。这主要是因为，Google 认为 TensorFlow Lite 这个名字太受限于 TensorFlow 框架了。现在整个AI模型生态的趋势是 PyTorch 统治科研与训练，而 TFLite 统治移动端部署。因此为了吸引 PyTorch 用户，Google 强调 TFLite 这个 Runtime 是通用的端侧AI部署工具，不只是给 TensorFlow 用的。所以现在新的品牌叫 LiteRT (Lite Runtime)。 !image.png 环境安装 要在PC端把一个Pytorch的模型转换为 TFLite/LiteRT 格式，主要是需要依赖于litert-torch和ai-edge-litert 这两个包。 - litert-torch：对应之前的 ai-edge-torch，负责将 PyTorch 算子映射到 LiteRT。 - ai-edge-litert: 对应之前的 tflite-runtime，是推理引擎，负责在 Android 或 PC 上执行生成的 .tflite (LiteRT) 文件。 截至目前（2026年3月份），litert-torch和ai-edge-litert 这两个包的接口变动仍然非常剧烈，导致其对环境的要求非常苛刻。所以一定要创建一个独立的Python环境，并且提前安装好其指定的torch版本，否则后面安装这两个包的过程中很容易出现包冲突的情况。经过仔细检查，目前比较稳定的环境安装步骤为（在Windows的WSL2环境中安装）： 注意：这个模型转换和PC端推理的环境必须安装在Linux环境中，我自己在Windows中安装环境总是会以下错误。从报错信息上看，litert-torch依赖于ai-edge-tensorflow，而ai-edge-tensorflow 目前主要发布在 Google 的 Nightly/Experimental 仓库中，对 Windows 平台的原生支持非常滞后。所以这个转换工具最好还是在Linux或者Windows的WSL2环境中来安装。 模型转换 环境安装好以后，就可以开始把Pytor下的预训练pt格式的模型文件转换为TFLite格式了。我这里直接使用Ultralytics/YOLO项目中的yolov8s.pt这个文件做转换测试。 以上模型导出脚本能够成功的导出 FP32 的模型文件，FP32 虽然精度最高，但由于其对内存带宽和存储空间的占用比较大（对于YOLOv8s这个模型而言，转换后的模型文件大小为44MB），在端侧 CPU/NPU 上运行肯定不是性能最优选，因此接下来还需要进行量化（Quantization）处理。 量化 对于YOLO模型自带export接口而言，量化是一个很简单的事情，只需要设置导出时的fp16、int8等导出格式就可以了。但是使用litert_torch 完成模型导出之后，对TensorFlow Lite模型文件进行量化操作的接口发生的变化非常剧烈，导致现在在网上看到的几乎所有量化参考代码在最新的litert-torch 都无法正确、成功的完成量化操作。 通过学习https://github.com/google-ai-edge/litert的ReadME文件： > > > I have a PyTorch model... > > - Goal: Convert a model from PyTorch to run on LiteRT. > - Path1 (classic models): Use the LiteRT Torch Converter to transform your PyTorch model into the .tflite format, and use AI Edge Quantizer to optimize the model for optimal performance under resource constraints. From there, you can deploy it using the standard LiteRT runtime. > - Path2 (LLMs): Use LiteRT Generative Torch API to reauthor and convert your PyTorch LLMs into Apache format, and deploy it using LiteRT LM. > 可以看到对于目前比较新的LiteRT实现而言，量化需要用一个新的工具ai-edge-quantizer（https://github.com/google-ai-edge/ai-edge-quantizer）。这个工具是 Google 专门为了对LiteRT模型进行 INT8/INT4 权重压缩打造的新一代利器。在最新的 Edge AI 理念中，单纯的文件体积 FP16 截断已经不再流行，权重 INT8 + 激活值浮点 (即所谓的Dynamic Quantization) 才是能在手机等端侧设备上上平衡速度、体积和精度的终极王者。 以上的量化流程中选择了wi8-afp32的模式（即权重参数使用INT8量化，激活值仍然使用FP32量化），最终得到的量化后的模型文件只有11MB的样子，是量化前的FP32模型文件的1/4。 除了以上的wi8-afp32量化模式，ai-edge-quantizer还支持其他的量化模式，如下图所示，Google 的工程师用了一种非常直白的命名约定来定义这些量化模式： - w = Weight（权重参数，即模型训练出来的固定参数） - a = Activation（激活值，即模型在推理时流动的中间特征图） - i8 / i4 = 8位 / 4位整数（Integer） - fp32 = 32位浮点数（Float） !8a772873-2af8-4892-8f32-b1998f10d39e.png 推理测试 基于 LiteRT模型文件已经转换并量化完成，下一步就是在PC端的LiteRT runtime中对其进行推理测试。 如上所述，在 LiteRT生态中，ai-edge-litert包对应于之前的 tflite-runtime，也就是负责在 Android 或 PC 上基于LiteRT模型文件执行前向推理的运行时框架。因此，在PC端进行前向推理的流程大致也就是：加载模型以及推理的图片文件→数据预处理→执行推理→对推理结果执行NMS后处理→把NMS过滤的结果叠加在输入图像上。 参考资料 - AI Edge Torch: High Performance Inference of PyTorch Models on Mobile Devices - Google Developers Blog - Convert Models From Pytorch to TFLite With AI Edge Torch | by David Cochard | ailia Tech BLOG (EN) | Medium - https://github.com/google-ai-edge/litert-torch/blob/main/docs/pytorch_converter/README.md - https://github.com/google-ai-edge/ai-edge-quantizer

TFLite如何处理算子版本和兼容性的问题？

在瑞芯微NPU平台上进行模型板端适配的时候，在进行模型板端转换的时候，ONNX 导出时设置的 Opset 版本，与板端模型转换工具（RKNN-Toolkit2）能够支持的 Opset 版本的一致性非常重要，如果板端模型转换工具不支持onnx文件中的某些算子类型的话，这个转换过程就会报错。那么，TFLite是否也存在 Opset 版本的问题，也就是模型导出为 TFLite 格式的时候也应该有个 Opset Version，这个 Opset 的版本需要与 interpreter 能够支持的 Opset 版本相对应，否则也会出现以上瑞芯微平台模型转换的问题？以及在TFLite的工作流程中，究竟是处理Opset版本一致性问题的？本文尝试总结以上问题的答案。 相关的背景信息可参考： - ONNX的Opset版本： 如何理解ONNX模型导出的Opset版本？ - TFLite框架的核心概念和工作流程： 如何理解TFLite/LiteRT的核心概念和框架流程？ TFLite的Opset版本信息 针对TFLite框架下，是否也有与ONNX相同的OpSet版本的概念和处理这个问题，简单的答案是：TFLite同样有算子版本的概念，但是与算子版本的处理流程与ONNX有较大的差异。 .tflite 文件本质上是一个序列化后的 FlatBuffer 二进制文件。在这个文件头部，有一个专门的 OperatorCode 数组（也就是所谓的算子注册表）。当模型被导出时，TFLite 转换器会把这个模型文件中用到的所有算子登记在这个表里，并且每个算子独立记录其算子版本号，而不是像ONNX那样有一个统一的算子集版本号。 如下图所示的两者的显著差异：TFLite采用的是细粒度的基于各个算子的独立版本号，模型文件本身没有算子集版本的概念；而ONNX采用的这是全局的算子集版本号，通过模型文件来规范和管理整个算子集的版本。 !%E6%97%A0%E6%A0%87%E9%A2%98-2026-03-26-1350.png 为什么TFLite要采用这种单个算子集别的版本管理模式，而不是采用ONNX这样的全局算子集Opset版本的方式？ 最主要的原因是，算子级别的版本管理方式可以更好的向前兼容性，这一点对于软硬件碎片化非常严重的Android生态系统非常重要。假设我们的模型中仅包含有最基础的 Conv2D 和 Relu 算子，使用最新版本的模型转换器导出的时候： - 如果是 ONNX的全局Opset模式：模型转换器会将这个ONNX文件标记为比较新的 Opset 18。这样的话，即使 Conv2D 这个算子在 Opset 1 到 18 里没有发生任何变化，那么一个老版本的 ONNX Runtime 在看到 Opset 18 版本的情况下，可能就会直接报错并拒绝加载。 - 而在 TFLite 这种单算子版本的管理模式中：模型转换器在转换过程中，发现该模型没用到 Conv2D 的新特性，就会在TFlite模型文件里将 CONV_2D 这个算子标记为 Version 1。这种情况下，即使用户的Android手机里包含的是很早版本的 TFLite Interpreter，也能完美加载并运行这个最新导出的模型。 算子版本的匹配 与其他嵌入式平台的模型导出、适配以及板端的加载运行相同，在Android系统上运行TFLite格式的模型，在算子的版本匹配上，需要关注三个环节：模型导出和转换工具的算子版本（Converter），Interpreter支持的算子版本，以及delegate支持的算子版本。只有以上三者的算子版本信息相互匹配，才能确保这个TFlite模型在Android系统上成功的跑起来。 - TFLite 模型转换工具、Interpreter以及Delegate等相关的概念及其在Android系统中的结构，可以参考如何理解TFLite/LiteRT的核心概念和框架流程？ 这一篇笔记。 Converter TFLite 模型的 Converter 工具内部有一套算子版本试探的算法，来自动检测模型文件中各个算子的版本信息。例如对于 FullyConnected 这个算子，在没有开启 Keep_num_dims 特性的情况下，Converter 在进行模型转换的时候，就会给这个算子打上 Version 1 的标签；而如果模型的推理计算过程需要开启这个新特性，Converter 才会给该算子打上 Version 2。这就相当于是一个“能用低版本绝不用高版本”的算子版本决定策略，这个策略是保证模型和 App 拥有最广设备兼容性的核心所在。 总结起来，对于Converter而言，无论这个Converter工具有多新，它的工作逻辑都是：在进行模型TFLite格式转换的过程中，它会扫描和试探出来每个算子在模型计算图中所要求的最低版本，然后把这个最低版本作为该算子的版本，以此来尽量保证后续这个算子以及模型能够支持到范围最广的设备。 Interpreter Interpreter 也有自己的版本支持情况，那么它在加载TFLite模型文件和构建模型的计算图的过程中，同样会去扫描各个算子的版本信息，并检查该版本与自己支持版本的适配情况。 Interpreter 在加载 TFLite 模型文件的 FlatBuffer 结构的过程中，提取每个算子的版本信息，与自己内部的 OpResolver（算子注册表）进行比对。对于一个算子而言，如果在TFLite文件中该算子需要的版本是 Version 5，而 Interpreter 的代码库里算子注册表只实现了 Version 4，它会立即抛出 Unresolved builtin op 异常，并拒绝执行。 因此，一个模型究竟能否在Android系统中跑起来，Interpreter 对于算子版本的支持情况非常关键，这就是为什么在使用 Flutter 框架开发Android App 时，应该尽量使用最新版本的 tflite_flutter 插件。 > 💡 Interpreter本身就是一个普通的 C++ 动态链接库（比如 libtensorflowlite_c.so），它是被硬打包进 APK 里的，而不是由 Android 系统底层提供的。这样的好处是，Interpreter与APP里面的模型强绑定，只要APP完整测试通过，就可以确保运行在不同硬件平台和Android系统版本上。因此，如果系统中包含有多个跑不同模型的APP，也就有多个各自独立的Interpreter副本。当然，TFLite 的核心解释器被设计得极其精简，去除了所有训练相关的代码。一个基础的 C++ Interpreter 库通常只有 1MB 到 2MB，对现代 App 的体积影响微乎其微。 在 Interpreter 中实际上包含了其所支持的所有算子的CPU实现，这样的话，如果 Delegate 不支持某个算子的话，Interpreter 就会自动调用其内部实现的CPU算子。 Delegate 而在 Delegate方面，同样有自己所支持的各个算子的版本信息，在Delegate与Interpreter握手的过程中，Interpreter会拿到了Delegate所支持的各个算子的版本信息。在这种情况下，Interpreter 在模型前向推理的算子调度过程中，就能够清楚的知道哪些算子 Delegate 能够支持，哪些算子Delegate不支持必须要放在CPU中执行。 当然，不同于 Interpreter 是内置在Android APP层面中，Delegate 对于算子的支持是固定在Android系统中的。这也很好理解，因为 Delegate 之下的 NPU 驱动的实现需要依赖于SOC厂家的实现，是不可能放在APP层面来解决这个问题的。因此，除非升级整个系统，Delegate层面对算子版本的支持情况就是固定的，Delegate没法支持的算子就只能被Interpreter调度到CPU上去执行。 TFLite前向推理与算子版本相关的完整流程 至此，对于TFLite的算子版本管理，TFLite模型文件导出时的算子版本推定，在Android系统中Interpreter和Delegate进行算子版本匹配和调度的完整流程就呼之欲出了： !TFLite_Architecture_Flowchart.png

总结Android Flutter项目中YOLO模型的执行流程

之前基于 Flutter 实现了一个在Android APP中调用YOLO模型来实现图像目标检测功能，本文的 YOLO 模型的 TFLite 导出以及在 Android Flutter 项目中进行调用的完整执行流程进行总结。 在Android上跑AI模型，标准的做法是导出模型文件为 TFLite 格式，然后在 Android 的 TFLite+Interpreter+NCAPI 框架下执行AI模型的推理流程，与该框架相关的知识可参考 如何理解TFLite/LiteRT的核心概念和框架流程？一文。 YOLO模型的TFLite导出 因为 Ultralytics 项目中的模型导出的实现已经非常完备，所以可以直接在ultralytics项目中通过其export接口导出 tflite 模型文件即可，此处选择导出为half即float16的格式： 此外，后续在Flutter项目中调用以上模型文件进行推理，还需要创建一个与模型对应的label.txt文件，其中包含有模型检出类别对应的类别名称字符串，按顺序每行一个。因为我测试中直接使用的是YOLO的预训练pt文件，预训练模型文件对应的是COCO数据集，所以这里的label.txt中包含的类别名称字符串大致就是如下80个类别： 依赖管理 因为要在 Android Flutter APP 增加跑AI模型的的能力，首先需要在项目根目录下的pubspec.yaml和 android/app 目录下的build.gradle.kts增加相关的依赖项。 flutter项目中的pubspec.yaml是该项目的元数据中心（Metadata Center）和依赖管理器（Dependency Manager）。其中包含的主要内容是：项目的基本配置信息，生产环境的依赖库，开发/测试阶段的依赖库，资源与资产等。对于以上提到的依赖项，每次在构建项目时，都会自动调用 flutter pub get 从pub.dev下载指定依赖库的源代码到本地。 该项目中需要对手机camera和本地图片的图像调用YOLO模型进行检测，所以pubspec.yaml中相关的设置项包括： 因此，对于在 Android 项目中跑YOLO模型而言，以上配置文件最关键的就是其中导入了 flutter_vision 这个插件。该插件内置了 TensorFlow Lite C SDK，并针对 YOLO 这种特定模型，包含了输入输出的 ByteBuffer、维度转换（Tensor Shape）和 NMS（非极大值抑制）等的相关处理，对于应用层程序而言，只需要调用 vision.loadYoloModel() 接口，它就可以在 Android 原生层创建 TFLite 的 Interpreter并执行推理任务。 模型在Flutter中的完整推理流程 与其他板端模型的完整推理流程类似，在Android Flutter项目中调用YOLO模型执行推理任务同样包含模型加载、前向推理以及后处理这三个环节。 模型加载 基于flutter_vision插件对AI模型进行加载的整体流程如下： 整体的模型加载过程很简单，调用flutter_vision的loadYoloModel接口创建一个模型加载的异步任务，传递模型文件和label文件等参数，然后等待这个异步任务执行完成即可。 需要注意的是，flutter_vision 插件只能够支持ultralytics项目export接口直接以tflite格式导出的YOLOv5，YOLOv8，YOLOv11这几个模型，而且参数中指定的模型文件与modelVersion的参数必须设置正确，否则后续的后处理流程会出错： !074e2e0e-d2b9-48e6-b0b2-4a1f06769c23.png 那么如果我们要在 Android APP 中跑其他模型呢？那就只能使用 tflite_v2 插件、flutter_tflite插件或者底层 TensorFlow Lite API。 前向推理和后处理 flutter_vision插件的前向推理过程主要就是调用其yoloOnFrame（针对摄像头的图像）和yoloOnImage接口（针对本地图片）。 以上的推理接口执行中本身已经包含了YOLO不同版本的后处理流程，所以其输出结果是一个的数组。这个数组中的每一项都对应于一个最终检测框的类比和坐标+置信度，如下所示： 应用层拿到以上的这个数组以后，就可以对其中的内容进行解析并在图像上画框标注了。因为 yoloOnFrame 和 yoloOnImage 接口中已经包含了后处理的NMS等环节，所以不需要在应用层再执行后处理了。 参考资料 - flutter_vision | Flutter package

如何理解TFLite/LiteRT的核心概念和框架流程？

本文整理了TFLite的核心概念，与ONNX框架的对比，及其内部各个组件的关键工作流程，尝试建立对这个Android系统下的标准AI推理框架的整体概念和工作流程建立完整的理解。 TFLite是什么？以及与ONNX的比较 Google推出的 TensorFlow Lite 是一个专为移动、嵌入式和边缘设备设计的开源深度学习框架。它能够支持开发者在手机（Android/iOS）、微控制器（MCU）及各类物联网设备上，以极低的延迟和较小的二进制体积运行高性能的推理任务。 !image.png 众所周知，在边缘侧的板端设备上运行各种 AI 模型，已经有一个非常流行的 ONNX 框架，那为什么不在 Android 上直接使用 ONNX？原因主要还是 Facebook的 Pytorch/ONNX 与Google的 TensorFlow 之间生态竞争的问题。 虽然 ONNX Runtime 现在也能够支持在 Android上运行，但在 Android APP 中跑AI Model还是应该首选使用 TFLite，原因如下： - 兼容性的问题：在 Android 系统的实现中，Google 提供了一层 NNAPI (Neural Networks API) 的封装。TFLite 是 Google 主推的端侧机器学习框架，它对 NNAPI 的支持是第一优先级的。如果用 ONNX 的话，在调用不同 SOC 厂家的 NPU 时，可能会遇到各种驱动不兼容或性能折损的情况，兼容性的处理会非常头疼。 - 内存与包体积的问题：要在 Linux 或者 Android 系统中使用ONNX来运行模型，就需要把 ONNX Runtime 内置进去，相关的库文件通常很大（几十 MB），这样就会直接增加 App 的安装包大小和内存占用情况。而如果使用TFLite的话就没有这个问题，TFLite 的核心解释器非常小（只有几百 KB），而且 Android 系统中已经内置了相关的运行时环境。 TFLite模型部署的整体工作流程 将一个复杂的深度学习模型部署到手机上，通常需要经历从训练、精简/格式转换/量化再到板端执行的完整的过程。这个流程对于所有的设备端 AI 框架的工作流程而言都是大致相同的。 例如对于瑞芯微平台上的模型适配而言，其整体的适配流程如下： - 首先在PC/AI服务器端完成模型训练，导出为ONNX格式的模型； - 把以上导出的ONNX模型再利用瑞芯微的RKNN-Toolkit工具转换为RKNN格式的板端模型； - 在瑞芯微的处理器中，板端模型与其运行时库librknnrt.so、应用程序相互配合完成板端的推理任务。 以上的这个流程，对于在手机的的 Android 系统中使用 TFLite 框架来运行 AI 推理的流程是完全相同的，只不过整个过程稍微简化了一些而已： - 模型转换部分：首先把原始的训练好的 PyTorch 模型（通常是 .pt 或 .pth）使用 TFLite Converter 之类的工具转换为扁平缓冲区格式的 .tflite 文件。与其他板端模型转换工具的工作流程类似，在这个转换过程中，它会进行算子融合（将多个连续的操作合并为一个，以减少内存访问次数和量化（将原始模型文件中的 32 位浮点数权重转换为 16 位浮点数 FP16 或者 8 位整数 INT8，在微弱损失精度的前提下可换取数倍的速度提升同时降低对模型大小和显存的需求）等操作。 - 板端推理执行部分：在 Android App 运行时，内置在Android 系统中的 TFLite 解释器（Interpreter）会负责加载模型、管理内存缓存并调度计算算子。 > 💡 注：在模型转换部分，Pytorch 框架下训练出来的模型，一般需要先转换为 ONNX 模型，再利用类似 onnx2tensorflow 之类的工具转换为 tflite 格式。不过 Goggle 在2024年也出了一个 AI edge torch的工具可以实现直接的转换。 !image.png TFLite模型在Android框架下是如何运行的？ 从以上的框架图中可以看到，模型转换为 TFLite 格式后再Android APP中的运行，需要依赖于两个关键的组件：Interpreter 和 Android Neural Networks API（NNPI）。 其中的Interpreter (解释器)是 TFLite 模型在系统中运行的核心控制中枢。它负责加载模型，解析模型的计算图（Graph），并管理内存缓冲区。在整个模型的工作流程中，Interpreter 并不直接做复杂的浮点和算子运算，而是负责将模型中定义的计算任务分发出去。 - 其实这个Interpreter有些类似于瑞芯微的librknnrt.so，负责辅助应用程序加载模型，解析模型的计算图和管理内存，然后在接收到输入数据的时候，对模型每一层的计算任务进行调度管理，分配到合适的处理器（CPU/GPU/NPU）上，并根据具体的计算调度情况不同的处理器上在处理器之间管理好内存的拷贝。所以其任务就是：加载并解析模型，分发计算任务，管理不同计算任务和处理器上的内存。 而 NNAPI 则是 Android 系统提供的一个 C API。它的存在是为了屏蔽底层 NPU、GPU、DSP 硬件的碎片化。Google 在 Android 系统中所提供的 NNAPI 只是一个与 Interpreter 相互配合的API调用接口的框架，而对于瑞芯微、高通、联发科等 SoC 厂商，要让 Android 手机能流畅地使用 TFLite 执行模型的推理任务，他们的核心工作就在其SOC的设计中进行 NNAPI 接口的具体实现。 具体来讲，这些 SOC 厂商需要根据 Android NNAPI 模块所提供的 NeuralNetworks.h 标准，编写对应的 NPU 驱动指令。这些驱动指令的关键任务就是实现模型的算子映射（将 Android 定义的 ANEURALNETWORKS_CONV_2D 等标准算子，翻译成自己的 NPU 能理解和执行的具体指令）和内存管理（实现不同类型和区域的内存共享控制，尽量避免模型在执行推理过程中数据在 CPU 和 NPU 之间来回拷贝）。 总结起来，就形成了这样的调用关系和流程： !5a379fcc-72eb-471f-9001-bf892b8a6120.png - 首先是APP的应用程序逻辑代码调用 Interpreter 加载和解析模型文件； - 在 Interpreter 对输入数据执行推理流程的过程中，会通过 Delegate 机制调用 Android系统中的 NNAPI 框架中所定义的API。NNAPI中定义了不同的标准算子，Interpreter 在推理中针对具体不同的算子调用 NNAPI 中与之对应的API接口。 - NNAPI之下则是不同 SOC 针对算子的具体实现，这部分由各个 SOC 厂家根据自己SOC中 CPU/GPU/NPU 的能力来进行实现。相当于 NNAPI 定义了一层标准的算子接口，屏蔽了不同 SOC 厂商在其硬件上实现这些算子的差异性，这样的话，对于应用程序和Interpreter而言，看到的就只是 NNAPI 所定义的标准接口。 Interpreter 调用 NNAPI框架的Delegate机制 以上所描述的 Interpreter 和 NNAPI 框架的调用流程只是一个简化的解释，实际上Interpreter并不是直接调用NNAPI所定义的API接口。如果 Interpreter 直接以硬编码的方式去调用 NNAPI的话，会产生两个问题： - 某些算子可能不支持 (Fallback)：NNAPI 并不一定能够支持 TFLite 模型文件中的所有算子。如果直接调用的话，遇到不支持的算子程序就崩溃了。 - 跨平台的兼容性问题：TFLite 所谋甚大，不仅要运行在 Android 上，还能够支持在 Windows、Linux、iOS 上跑，而这些系统中根本就没有NNAPI（例如上面架构图中的iOS APP部分根本就没有 NNAPI）。 所以 Interpreter 在 Android 中对于 NNAPI 框架的调用，采用了一种 delegate 的机制。 本质上，Delegate 就是 Interpreter 为了实现跨平台兼容性而设计的一个抽象插件接口。 - 对上（与Interpreter之间），它通过TfLiteDelegate 定义了一个标准的 C API，通过这个C API屏蔽了不同硬件平台、SOC、NPU的差异性。Interpreter始终只需要调用这个C API接口来实现对下层不同算力的调用，实现完整的推理过程。 - 而对下（各种平台不同的NPU实现），它作为客户端，负责调用各个不同系统和硬件平台上特有的深度学习算子运算的加速库（如 Android 的 libneuralnetworks.so 或 iOS 的 Metal.framework）。 至此，TFLite 框架得到完整结构及其调用流程就比较清楚了： !%E6%97%A0%E6%A0%87%E9%A2%98-2026-03-26-1350.png 参考资料 - Google Play 服务 C 和 C++ API 中的 LiteRT  |  Google AI Edge  |  Google AI for Developers - TFLite基础知识 - VitoYeah - 博客

手部特征点检测模型MediaPipe Hand Landmarker

MediaPipe Hand Landmarker模型简介 Google 的 MediaPipe Hand Landmarker（基于Mediapipe推理框架的手部特征点检测模型）是目前计算机视觉领域最流行、最高效的实时手部特征点检测和追踪解决方案之一。它能够运行在移动设备（Android/iOS）、网页端甚至算力受限的边缘设备上，以实时帧率输出手部的 21 个 3D 关键点（Landmarks）在图像中的坐标位置。 下图是该手部特征点模型软件包可以检测检测到的手部区域内 21 个手指关节坐标的关键点定位索引。该模型是基于约 3 万张真实图片以及叠加在各种背景上的多个渲染合成手部模型进行训练的。 !image.png Google 针对Hand Landmarker模型提供了iOS/Android/Web/Python这四种平台的官方实现，所以如果是在这四种平台中使用这个模型的话，可以直接参考官方的示例代码方便的调用模型来实现应用需求。 那么如果希望把这个模型运行在其他平台和语言，例如在其他的嵌入式平台上使用C/C++语言来调用呢？ 答案是完全可以，只不过稍微复杂一点。Hand landmarker模型的运行需要依赖于Google开源的 MediaPipe 推理框架，而这个推理框架的底层本质，是一个以 C++ 为核心底座，以 TensorFlow Lite为推理后端，通过图计算（Graph）管理数据流的流媒体 ML 框架。 MediaPipe本身是开源的，而且对商业应用极其友好，其代码仓库托管在 GitHub 上：https://github.com/google-ai-edge/mediapipe。开源协议采用 Apache 2.0 License，可以自由使用、修改、分发，甚至将其闭源集成到自己的商业软件中，而无需开源业务代码。 所以要使用C/C++语言运行这个模型，就需要先把 MediaPipe 框架交叉编译到自己的系统中，然后在这个框架的基础上调用模型的推理能力。 模型的工作流程及其输出数据解析 MediaPipe Hands Landmarker模型在运行中之所以能做到极高的性能和检测帧率，其核心在于，它采用了一种级联的两阶段网络架构： 1. 手掌检测模型 (Hand Detector): - 该模型是一个极其轻量级的 SSD（Single Shot Detector）架构模型，其任务是在整张图像中快速找到整个手掌的边界框（Bounding Box），返回一个带方向的矩形框（Oriented Bounding Box）。 - 因为在视频图像中，手部的形变极大（手指可以弯曲、交叉），如果直接检测整只手的话难度很高。而手掌是一个相对刚性的结构，正方形特征明显，极其容易被网络捕获。 2. 手部特征点检测模型 (Hand Landmark Detector): - 一旦第一阶段的 Hand Detector 模型找到了手掌的区域，整个系统会将该区域（第一阶段模型返回的矩形框）裁剪并旋转对齐，然后送入第二阶段的 Landmarker 模型，这个模型专门在裁剪后的小图上精确检测出来 21 个 3D 坐标。 - 因为第二阶段模型只需要在裁剪后的局部区域进行推理检测，这样就极大地减少了计算量，过滤了无关的背景干扰，这是该模型能够跑得又快又准的根本原因。 !mediapipe_architecture.png 在模型的接口设计和执行流程中，MediaPipe Tasks API 包含有中三大运行模式（IMAGE、VIDEO、LIVE_STREAM），分别对应于单图、视频文件中的图像帧、带回调的实时流这三种应用场景。相应的也就对应于以下三个 API 调用接口： - detect(image)：单图模式 (IMAGE)。 执行流程没有任何记忆，每一张图片输入后都需要先在整个图片中找手，然后再检测手部的21个特征点，适用于处理磁盘里的静态照片集。 - detect_for_video(image, timestamp_ms)：视频模式 (VIDEO)。 带有记忆且在执行过程中同步阻塞，在执行推理的过程中其内部会维护了一个 ROI 缓存。上一帧找到了手部区域后，下一帧可直接找到那个区域跑轻量级的 Landmark 检测关键点。适用于处理本地录制好的视频文件。 - detect_async(image, timestamp_ms)：异步直播流模式 (LIVE_STREAM)。 带有记忆且异步非阻塞，为摄像头的实时图像量身定制的。主线程发图像给模型推理框架后立刻返回，不等待结果。推理框架中的底层 C++ 线程池算完后，通过 Callback（回调函数）把结果返回给主线程。因此，使用这种模式需要在初始化 HandLandmarkerOptions 的时候传入一个 result_callback 参数，指明哪个函数负责接收 C++ 传回来的异步结果。 下图为通过以上接口对图像中手部及其关键点检测后的返回结果的数据结构： !MediaPipe_Result_Structure.png 以下是对接口返回结果进行解析和调用的代码示例： 模型运行示例 要在本地PC上使用 Python 运行这个模型，需要安装Google的mediapipe支持包以及下载一个hand_landmarker.task的模型包文件。 hand_landmarker.task模型包的下载地址为：https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task 这个hand_landmarker.task模型包文件以task为后缀名，但是本质上是一个压缩包，其中包含有两个模型文件：hand_detector.tflite（手掌检测模型）和hand_landmarks_detector.tflite（手部特征点检测模型）。只需要把这个模型加一个zip后缀名然后打开即可看到： !f15c88bc-9cbc-4f6a-937d-bb545d301cb6.png 以下提供的代码实现了使用opencv对本地PC摄像头的图像进行手部及其特征点检测并标记的应用案例： 参考文档 - https://ai.google.dev/edge/mediapipe/solutions/vision/hand_landmarker?hl=zh-cn - hand_landmarker.ipynb - Colab - mp.tasks.vision.RunningMode  |  Google AI Edge  |  Google AI for Developers

在Android Flutter项目中flutter_litert插件运行TFLite模型

在之前的一篇笔记（总结Android Flutter项目中YOLO模型的执行流程）中，我详细总结了基于flutter_vision插件在一个Android Flutter项目中把Ultralytics项目中导出的YOLOv8模型运行起来的完整流程。 但是Flutter_Vision插件的使用有诸多限制，例如只能运行YOLO的几个模型，并且只能配合Ultralytics的export接口导出的TFLite模型文件来使用。那么如果想要在Android上跑YOLO之外的模型，就没有办法是用Flutter_Vision插件了。 因此，要把一个自定义的模型转换为TFLite格式并且能够在Android APP中跑起来，就需要一个更灵活的应对方式。而这个过程分为两个步骤： - 把自定义模型的pt文件转换为TFLite格式。这部分在如何把PT格式的模型转换为TFLite/LiteRT模型？已有详细总结。 - 把以上转换的TFLite格式的模型文件在Android Flutter项目中跑起来，避免受到FlutterVision插件所带来的限制。这一点就是本文要解决的问题。 flutter_litert vs tflite_flutter 在Android Flutter项目中跑 TFLite模型，目前比较常用的是flutter_litert和tflite_flutter这两个插件。 - tflite_flutter：这个插件是 Flutter 社区中最经典、最老牌的 TFLite 插件，目前搜到的信息大部分都是使用这个插件在Android上跑AI模型。它通过 Dart FFI 直接封装了 C 语言的 TFLite 解释器。目前仍有社区维护版（如tflite_flutter_plus），但配置分散，社区维护分散，在新的项目中不建议使用。 - flutter_litert：这个插件是为了响应 Google 对 TensorFlow Lite 品牌的正式更名和升级 (LiteRT) 而推出的现代继任者。它也是目前推荐的、更符合 Google 最新人工智能路线图的插件，其本质上是 tflite_flutter 的演进版本，旨在解决旧插件的维护痛点。因此强烈建议在新的项目中使用flutter_litert这个插件。 !image.png flutter_litert 这个插件本质上就是一个工作在 Flutter（Dart 语言）层级的硬件抽象层 (HAL) Wrapper。这个插件总的特点是： - 底层机制： 该插件并不是用 Dart 重写模型的推理逻辑，而是通过 Dart FFI (Foreign Function Interface) 接口极其轻量地绑定了 Google 已经预编译好的 C++ LiteRT Native 二进制库（.so 文件），这样的好处当然是可以利用底层的C/C++语言的执行达到最高的效率。 - 零拷贝理念： 其核心思想是在内存里开辟一段连续的 Buffer（如 Float32List），使用Dart 语言往里填数据，C++ 引擎则会直接读取这段物理内存进行模型的矩阵运算，避免了跨语言传值所带来的性能损耗。 flutter_litert 插件运行的整体架构与数据流程 下图是在Android Flutter项目中使用flutter_litert 插件运行AI模型的整体架构与数据流程图： !litert_architecture_high_res.jpg 从以上的整体流程图中，模型的前向推理过程中的数据流动可以大体分为四个层次和阶段。 1.采集与调度层：Flutter Dart Zone (User Space) 这部分运行在 Flutter 的 Dart 虚拟机中，相当于系统的用户态应用程序。它的首要任务是协调前端 UI 显示与模型检测结果的时序、图像预处理这两部分工作。 当然在模型能够对图像进行检测和识别之前，首先要把模型加载到内存中，模型及其label文件一般整合在app的assets中，因此采用assets对应的API加载模型： 对于手机的摄像头而言，在打开的情况下，其以 30/60fps 的帧率向主线程推送高分辨率的 YUV420 裸流数据并显示在屏幕上。而一般情况下，手机所具备的算力无法支持以这么高的算力实现对每一帧图像的检测，可能1秒钟只能完成10帧图像的处理，这样的情况下，Camera采集图像与Model处理图像这两部分的工作就不是同步的。因此需要分开两个线程同时进行处理，主线程按照Camera的采集帧率刷新显示实时图像，而针对模型对图像的处理而言，就必须开辟一个独立的 Isolate（类似后台高优先级线程），执行 YUV 转 RGB、图像缩放等预处理后送入litert_flutter插件进行识别和检测 。 众所周知，图像在送入YOLO等模型中进行前向推理之前，还必须要进行一系列的预处理流程，以符合模型对输入图像数据在各个维度上的要求。因此，对于每一帧从摄像头中取出的YUV420数据，其分辨率可能是1280x720，那么要进行的预处理过程就至少要包括：分辨率缩放到640x640、YUV转RGB、图像归一化到0-1.0之间、图像数据排列格式调整为NCHW（Pytorch模型的数据排列格式默认为NHWC）等。 以上经过预处理以后，输入图像就准备好了，下一步就是调用flutter_litert插件的API接口进行处理了： 2.跨语言函数接口与内存零拷贝机制 在 Interpreter 对输入图像数据所进行的前向推理的执行流程中，图像数据要从APP应用层的Dart语言传递到模型推理代码的C++语言，而且为了在两种语言之间高效的传递大片的图像内存数据，最好能够直接通过类似内存指针的方式来实现零拷贝的图像内存传递机制，这就是 Flutter 框架为了提升应用程序性能的 Dart FFI (Foreign Function Interface)的用武之地了，它可以允许 Dart 直接与底层 C/C++ 共享同一块物理内存的指针，从而避免在调用者和被调用者之间反复拷贝大片的内存。 如上图所示，无论是在 Dart 语言所写的 interpreter 的函数调用，还是最终 interpreter 把模型的运行结果从底层的C++语言返回给用户态的Dart语言层，都采用了 Dart FFI所提供的内存零拷贝机制。 3.底层算力的执行：Native C++ Zone 这部分是模型使用C/C++语言真正执行前向推理的部分。 在如何理解TFLite/LiteRT的核心概念和框架流程？ 一文中，已经详细总结了在Android的TFLite/LiteRT框架下运行AI模型的关键概念和执行流程，Google 使用 C++ 语言写了一个 LiteRT Runtime运行时环境（实际上也就是所谓的interpreter），负责执行和调用 TFLite\LiteRT 格式模型在Android系统中的运行和算子的调度。 具体的算子调度执行过程中，Interpreter 进一步 通过Delegates 来决定把具体的运算算子派发给谁： - GpuDelegate (Adreno GPU)： 适合处理模型中大规模并行的浮点矩阵乘法。 - NnApiDelegate (Hexagon NPU)： 针对 Android Neural Networks API 设计的专用 NPU。如果模型完全量化为 INT8，交给 NPU 跑不仅极快，而且功耗极低。 - XNNPACK (CPU SIMD)： 最底层的兜底方案。如果某个算子 GPU/NPU 不支持，就会退回到 CPU 用向量指令硬算，当然这通常是模型运算速度慢导致卡顿的罪魁祸首。 具体的执行和调度逻辑可以参考如何理解TFLite/LiteRT的核心概念和框架流程？以及TFLite如何处理算子版本和兼容性的问题？这两篇文章。 4.模型返回与渲染 通过以上 LiteRT Runtime 所调度的模型前向推理的执行后，该部分的 C++ 引擎更新内存状态，通过Dart FFI机制，应用层的 Dart 语言层捕获到模型执行完成的信号。此时用户层应用程序就可以按照模型输出的数据结构和类型，从连续的内存块中拆解出 YOLO/RT-DETRv2等模型输出的张量信息（例如类别、边框、置信度等），对这些张量信息进行后处理（如YOLO还需要进行一步NMS处理），然后交回给 Flutter 的 GPU 渲染管道，根据屏幕比例映射坐标，在画布上轻量级地画出最终的目标检测框。 模型推理的GPU/NPU加速设置 如上所述，在LiteRT Runtime运行时环境对模型所进行的前向推理的计算过程中，interpreter 会根据具体算子的版本情况选择对应的delegate执行选项，主要是GPU、NPU和CPU SIMD等选项。那么在flutter框架下使用litert_flutter插件运行AI模型的时候，如何设置使用GPU/NPU来实现这些算子的硬件加速呢？ 需要通过 InterpreterOptions 来进行设置，具体代码如下： 以上代码的配置逻辑是，在Interpreter进行算子调度的过程中，优先使用GpuDelegateV2，如果算子在GPU上不支持的话，则会回退到CPU上用4线程来进行计算。 在当前（2026年4月）最新的2.0.11版本的 flutter_litert 插件中，InterpreterOptions 能够支持的加速模式包括： - GPU Delegates （图形处理器）：适用于大多数模型，特别是 CNN 类网络。优点是速度快，功耗相对较低。缺点是部分算子不支持，可能回退到 CPU。 - GpuDelegateV2()：针对android平台，其底层API是OpenGL ES 3.1 / Vulkan。 - GpuDelegate()：针对iOS平台，其底层API是iOS的Metal。 - Core ML Delegate （iOS）：针对iOS设备，iOS 11+，A12 芯片以上的设备。优点是在Apple 设备上性能最佳；缺点是仅支持 iOS。 - iOS 上应优先尝试 CoreMLDelegate() ，如果不支持再回退到 GpuDelegate() 。 - XNNPACK Delegate （CPU 优化）：无 GPU 或 GPU 不支持时。优点是兼容性比较好，速度快于普通的CPU；缺点是仍比 GPU 慢很多。 需要注意的是：通过options.addDelegate只能设置一个加速选项，如果多次调用addDelegate接口，只有最后一个会生效。因此实践中应使用try…catch的方式选择最合适的加速选项：