公告

更新：2023年4月26日

TensorFlow 团队已正式将该项目迁移到一个新的仓库 tensorflow/flutter-tflite，并废弃了此仓库。我们将专注于使该插件达到稳定且可用的状态，以帮助开发者在 Flutter 应用中添加强大的机器学习功能。欢迎在此新仓库中提交 PR 和贡献，但请注意，目前仍处于开发阶段，因此某些功能可能会暂时存在问题 :)

我们非常感谢 Amish 为这个初始插件所做的工作，并期待它能够继续发展。

在此期间，如有任何问题，欢迎随时与我联系。

谢谢！

• ptruiz@google.com

概述

TensorFlow Lite Flutter 插件提供了一种灵活且快速的解决方案，用于访问 TensorFlow Lite 解释器并执行推理。其 API 与 TFLite 的 Java 和 Swift API 类似。它直接绑定到 TFLite C API，因此效率高（低延迟）。支持使用 NNAPI、Android 上的 GPU 委托、iOS 上的 Metal 和 CoreML 委托，以及桌面平台上的 XNNPack 委托来加速推理过程。

主要特性

• 支持多平台：Android、iOS、Windows、Mac、Linux。
• 可灵活使用任何 TFLite 模型。
• 通过多线程和委托支持实现加速。
• 结构与 TensorFlow Lite Java API 相似。
• 推理速度接近使用 Java API 构建的原生 Android 应用。
• 您可以通过本地构建二进制文件来选择使用任何 TensorFlow 版本。
• 在不同的 Isolate 中运行推理，以避免阻塞 UI 线程。

（重要）初始设置：将动态库添加到您的应用

Android

1. 将脚本 install.sh（Linux/Mac）或 install.bat（Windows）放置在项目的根目录下。

2. 在项目根目录下执行 sh install.sh（Linux）或 install.bat（Windows），以自动下载并将二进制文件放置到相应文件夹中。

   注意：安装的二进制文件不包含对 GpuDelegateV2 和 NnApiDelegate 的支持，但仍然可以使用 InterpreterOptions().useNnApiForAndroid。

3. 如果您希望使用这些 GpuDelegateV2 和 NnApiDelegate，请改用 sh install.sh -d（Linux）或 install.bat -d（Windows）。

这些脚本会根据最新的稳定版 TensorFlow 安装预编译的二进制文件。如需使用其他版本的 TensorFlow，请参阅 wiki 中的说明。

iOS

1. 下载 TensorFlowLiteC.framework。如需构建自定义版本的 TensorFlow，请参阅 wiki 中的说明。
2. 将 TensorFlowLiteC.framework 放入此包的 pub-cache 文件夹中。

Pub-Cache 文件夹位置：(参考)

• ~/.pub-cache/hosted/pub.dartlang.org/tflite_flutter-<plugin-version>/ios/（Linux/Mac）
• %LOCALAPPDATA%\Pub\Cache\hosted\pub.dartlang.org\tflite_flutter-<plugin-version>\ios\（Windows）

桌面

请按照 此指南 中的说明构建并使用桌面端的二进制文件。

TFLite Flutter 辅助库

一个具有简单架构的专用库，用于处理和操作 TFLite 模型的输入和输出。其 API 设计和文档与 TensorFlow Lite Android 支持库完全相同。强烈建议与 tflite_flutter_plugin 一起使用。了解更多信息。

示例

标题	代码	演示	博客
文本分类应用	代码		博客/教程
图像分类应用	代码		-
目标检测应用	代码		博客/教程
强化学习应用	代码		博客/教程

导入

import 'package:tflite_flutter/tflite_flutter.dart';

使用说明

创建解释器

• 从资源文件加载

  将 your_model.tflite 放入 assets 目录中。确保在 pubspec.yaml 中包含这些资源。

  final interpreter = await tfl.Interpreter.fromAsset('your_model.tflite');
  

有关如何从缓冲区或文件创建解释器的信息，请参阅文档。

执行推理

有关输入和输出的便捷处理，请参阅 TFLite Flutter 助手库。

• 对于单个输入和输出

  使用 void run(Object input, Object output)。

  // 例如：如果输入张量形状为 [1,5]，类型为 float32
  var input = [[1.23, 6.54, 7.81, 3.21, 2.22]];
  
  // 如果输出张量形状为 [1,2]，类型为 float32
  var output = List.filled(1*2, 0).reshape([1,2]);
  
  // 推理
  interpreter.run(input, output);
  
  // 打印输出
  print(output);
  

• 对于多个输入和输出

  使用 void runForMultipleInputs(List<Object> inputs, Map<int, Object> outputs)。

  var input0 = [1.23];  
  var input1 = [2.43];  
  
  // 输入：List<Object>
  var inputs = [input0, input1, input0, input1];  
  
  var output0 = List<double>.filled(1, 0);  
  var output1 = List<double>.filled(1, 0);
  
  // 输出：Map<int, Object>
  var outputs = {0: output0, 1: output1};
  
  // 推理  
  interpreter.runForMultipleInputs(inputs, outputs);
  
  // 打印输出
  print(outputs)
  

关闭解释器

interpreter.close();

使用委托支持提升性能

注意：此功能目前仍在测试中，在某些构建版本和设备上可能不稳定。

• 适用于 Android 的 NNAPI 委托

  var interpreterOptions = InterpreterOptions()..useNnApiForAndroid = true;
  final interpreter = await Interpreter.fromAsset('your_model.tflite',
      options: interpreterOptions);
  

  或者

  var interpreterOptions = InterpreterOptions()..addDelegate(NnApiDelegate());
  final interpreter = await Interpreter.fromAsset('your_model.tflite',
      options: interpreterOptions);
  

• 适用于 Android 和 iOS 的 GPU 委托

  • Android GpuDelegateV2

    final gpuDelegateV2 = GpuDelegateV2(
            options: GpuDelegateOptionsV2(
            false,
            TfLiteGpuInferenceUsage.fastSingleAnswer,
            TfLiteGpuInferencePriority.minLatency,
            TfLiteGpuInferencePriority.auto,
            TfLiteGpuInferencePriority.auto,
        ));
    
    var interpreterOptions = InterpreterOptions()..addDelegate(gpuDelegateV2);
    final interpreter = await Interpreter.fromAsset('your_model.tflite',
        options: interpreterOptions);
    

  • iOS Metal 委托（GpuDelegate）

    final gpuDelegate = GpuDelegate(
          options: GpuDelegateOptions(true, TFLGpuDelegateWaitType.active),
        );
    var interpreterOptions = InterpreterOptions()..addDelegate(gpuDelegate);
    final interpreter = await Interpreter.fromAsset('your_model.tflite',
        options: interpreterOptions);
    

请参考 测试用例，以查看每种方法的更多示例代码。

致谢

• TensorFlow Lite 团队的 Tian LIN、Jared Duke、Andrew Selle、YoungSeok Yoon 和 Shuangfeng Li 提供了宝贵的指导。
• dart-lang/tflite_native 的作者们。

tflite_flutter_plugin 快速上手指南

环境准备

• 系统要求：支持 Android、iOS、Windows、macOS 和 Linux。
• 前置依赖：
  • 已安装 Flutter SDK。
  • 已配置对应平台的开发环境（如 Android Studio/Xcode）。
• 重要提示：

  ⚠️ 官方公告：TensorFlow 团队已将该项目的维护迁移至新仓库 flutter-tflite。原仓库 (am15h/tflite_flutter_plugin) 已不再作为官方首选，但现有功能仍可使用。建议新项目优先考虑迁移后的官方版本，若需使用本指南内容，请知悉其处于维护过渡期。

安装步骤

1. 添加依赖

在 pubspec.yaml 文件中添加插件：

dependencies:
  tflite_flutter: ^0.10.4 # 请使用最新可用版本

运行以下命令获取依赖：

flutter pub get

2. 配置动态库 (关键步骤)

由于 TFLite 核心库需要原生二进制文件，必须执行以下脚本下载并放置库文件，否则应用无法运行。

Android 配置

在项目根目录下执行以下脚本（根据操作系统选择）：

• Linux / macOS:

  sh install.sh
  

  若需启用 GPU 加速 (GpuDelegateV2) 或 NNAPI，请使用:

  sh install.sh -d
  

• Windows:

  install.bat
  

  若需启用 GPU 加速 (GpuDelegateV2) 或 NNAPI，请使用:

  install.bat -d
  

注意：上述脚本会自动下载基于最新稳定版 TensorFlow 预编译的二进制文件。

iOS 配置

1. 下载 TensorFlowLiteC.framework。
2. 将解压后的 TensorFlowLiteC.framework 文件夹复制到插件的 iOS 目录中。
   • Linux/Mac 路径: ~/.pub-cache/hosted/pub.dartlang.org/tflite_flutter-<版本号>/ios/
   • Windows 路径: %LOCALAPPDATA%\Pub\Cache\hosted\pub.dartlang.org\tflite_flutter-<版本号>\ios\

Desktop (Windows/Mac/Linux) 配置

如需在桌面端使用并开启 XNNPack 加速，请参考官方 Wiki 构建对应的二进制文件。

3. 推荐辅助库

为了更方便地处理输入输出数据（如图片预处理、张量转换），强烈建议同时安装辅助库：

dependencies:
  tflite_flutter_helper: ^0.3.2 # 请检查最新版本

基本使用

1. 导入包

import 'package:tflite_flutter/tflite_flutter.dart';
// 推荐使用辅助库处理数据
import 'package:tflite_flutter_helper/tflite_flutter_helper.dart';

2. 加载模型

将 .tflite 模型文件放入项目的 assets 目录，并在 pubspec.yaml 中注册：

flutter:
  assets:
    - assets/your_model.tflite

初始化解释器（Interpreter）：

// 从资源文件加载
final interpreter = await Interpreter.fromAsset('your_model.tflite');

// 可选：配置加速选项 (例如 Android NNAPI)
// var options = InterpreterOptions()..useNnApiForAndroid = true;
// final interpreter = await Interpreter.fromAsset('your_model.tflite', options: options);

3. 执行推理 (Inference)

场景 A：单输入单输出

// 准备输入数据 (例如形状为 [1, 5] 的 float32 数据)
var input = [[1.23, 6.54, 7.81, 3.21, 2.22]];

// 准备输出缓冲区 (例如形状为 [1, 2])
var output = List.filled(1 * 2, 0.0).reshape([1, 2]);

// 运行推理
interpreter.run(input, output);

// 使用结果
print(output);

场景 B：多输入多输出

// 准备多个输入
var input0 = [1.23];
var input1 = [2.43];
var inputs = [input0, input1]; 

// 准备多个输出容器
var output0 = List<double>.filled(1, 0);
var output1 = List<double>.filled(1, 0);
var outputs = {0: output0, 1: output1}; // 映射索引到对象

// 运行推理
interpreter.runForMultipleInputs(inputs, outputs);

print(outputs);

4. 释放资源

使用完毕后关闭解释器以释放内存：

interpreter.close();

性能优化提示

• 隔离运行：建议在独立的 isolate 中运行推理，避免阻塞 UI 线程导致卡顿。
• 硬件加速：
  • Android: 支持 NnApiDelegate 和 GpuDelegateV2。
  • iOS: 支持 Metal Delegate (GpuDelegate) 和 CoreML Delegate。
  • Desktop: 支持 XNNPack Delegate。 (具体配置代码请参考 Usage instructions 中的 Delegate 部分)