TensorFlow Lite for Unity 示例

将“TensorFlow Lite 示例”移植到 Unity 并提供一些实用工具。

已在以下平台上测试：

• iOS / Android / macOS / Windows / Linux
• Unity 6000.3.2f1
• TensorFlow 2.19.0

包含的示例：

• TensorFlow
  • MNIST
  • EfficientDet 目标检测
  • DeepLab
  • MoveNet
  • 风格迁移
  • 文本分类
  • Bert 问答
  • 超分辨率
  • 音频分类
• MediaPipe
  • 手部追踪
  • Blaze Face
  • 人脸网格
  • 全身姿态估计
  • 自拍分割

包含的预编译库：

	iOS	Android	macOS	Ubuntu	Windows
核心 CPU	✅	✅	✅	✅	✅
Metal 委托	✅	-	✅	-	-
GPU 委托	-	✅	-	实验性支持	-
NNAPI 委托	-	✅	-	-	-

• 在 Linux 上运行 GPU 委托需要安装 OpenGL ES 和 OpenCL。详情请参阅 MediaPipe。

安装 TensorFlow Lite for Unity

[!重要]
您需要安装 Git-LFS。

• 若要尝试所有示例，请使用 Git-LFS 克隆此仓库。
• 如果您希望通过 UPM 获取 TensorFlow Lite 库，请打开 Packages/manifest.json 文件，并在 scopedRegistries 和 dependencies 部分添加以下内容。

{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": [
        "com.cysharp.unitask"
      ]
    },
    {
      "name": "npm",
      "url": "https://registry.npmjs.com",
      "scopes": [
        "com.github.asus4"
      ]
    }
  ],
  "dependencies": {
    // 核心 TensorFlow Lite 库
    "com.github.asus4.tflite": "2.19.0-p3",
    // 可选：TFLite 工具库
    "com.github.asus4.tflite.common": "2.19.0-p3",
    // 可选：MediaPipe 工具库
    "com.github.asus4.mediapipe": "2.19.0-p3",
    // 可选：仅在安装 UniTask 后才可使用异步方法
    "com.cysharp.unitask": "2.5.10",
    ...// 其他依赖项
  }
}

自行构建 TensorFlow Lite 库

UPM 包中已包含预编译库。此外，您还可以从 TFLite v2.14.0 或更高版本开始，在 tflite-runtime-builder 中找到 TFLite 库。

如果您想自行构建最新版本的 TFLite，请按照以下步骤操作：

1. 克隆 TensorFlow 库
2. 在 TensorFlow 库中运行 ./configure
3. 运行 ./build_tflite.py（Python3）以针对各个平台进行构建。

# 更新 iOS、Android 和 macOS
./build_tflite.py --tfpath ../tensorflow -ios -android -macos

# 使用 XNNPACK 构建
./build_tflite.py --tfpath ../tensorflow -macos -xnnpack

展示案例

MNIST

SSD 目标检测

DeepLab 语义分割

风格迁移

手部追踪

BERT

许可证

示例文件夹 Assets/Samples/* 采用 MIT 许可证。

MIT 许可证

版权所有 © 2024 Koki Ibukuro

特此授予任何人免费获取本软件及其相关文档文件（以下简称“软件”）副本的权利，允许其不受限制地处理该软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售该软件副本的权利；并允许向任何获得该软件的人提供服务，但须遵守以下条件：

上述版权声明及本许可声明应包含在该软件的所有副本或实质性部分中。

本软件按“原样”提供，不提供任何形式的保证，无论是明示还是暗示，包括但不限于适销性、特定用途适用性和非侵权性的保证。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任负责，无论这些责任是基于合同、侵权行为或其他原因产生的，亦或是与本软件或其使用有关的任何其他事项。

其他许可证

• TensorFlow: Apache 许可证 2.0
• MediaPipe: Apache 许可证 2.0
  • 部分 MediaPipe C# 代码基于 terryky/tflite_gles_app

模型许可证

📌：每个 TensorFlow Lite 模型可能有不同的许可证。请务必查看您所使用的模型的许可证。

• 官方 TFlite 模型
  • Bert
  • EfficientDet
  • DeepLab Lab
  • MNIST
  • 风格迁移
  • MoveNet
  • 文本分类
  • Smart Reply
• MediaPipe 模型
  • Blaze Pose
  • 人脸网格
  • 手部追踪
  • 自拍分割
    • 使用了来自 PINTO_model_zoo 的修改后模型，以移除自定义后处理步骤。

tf-lite-unity-sample 快速上手指南

本指南帮助中国开发者在 Unity 中快速集成 TensorFlow Lite 和 MediaPipe，运行各类 AI 模型示例（如物体检测、姿态估计、图像分割等）。

环境准备

系统要求

• 操作系统：iOS, Android, macOS, Windows, Linux
• Unity 版本：推荐 Unity 6000.3.2f1 或更高版本
• TensorFlow 版本：兼容 TensorFlow 2.19.0

前置依赖

1. Git-LFS（必须）：用于拉取包含大模型文件的仓库。
   • 下载地址：Git-LFS 官网
   • 安装后运行 git lfs install 初始化。
2. GPU 加速支持（Linux 可选）：
   • 若在 Linux 上使用 GPU Delegate，需安装 OpenGL ES 和 OpenCL。

安装步骤

你可以通过两种方式安装：克隆完整示例项目 或 仅通过 UPM 安装库。

方式一：克隆完整示例项目（推荐新手）

此方式包含所有演示场景和资源文件。

# 确保已安装 Git-LFS
git clone https://github.com/asus4/tf-lite-unity-sample.git
cd tf-lite-unity-sample

克隆完成后，使用 Unity Hub 打开项目根目录即可。

方式二：通过 UPM 安装库（适用于现有项目）

若需在现有项目中集成，请修改 Packages/manifest.json 文件。

注意：国内网络访问 npm 源可能较慢，建议配置 .npmrc 使用淘宝镜像或公司私有源加速。

在 manifest.json 中添加以下内容：

{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": [
        "com.cysharp.unitask"
      ]
    },
    {
      "name": "npm",
      "url": "https://registry.npmjs.com",
      "scopes": [
        "com.github.asus4"
      ]
    }
  ],
  "dependencies": {
    "com.github.asus4.tflite": "2.19.0-p3",
    "com.github.asus4.tflite.common": "2.19.0-p3",
    "com.github.asus4.mediapipe": "2.19.0-p3",
    "com.cysharp.unitask": "2.5.10"
  }
}

保存后，Unity 将自动下载并安装相关包。

基本使用

以下以 MNIST 手写数字识别 为例，展示最基础的调用流程。

1. 准备模型文件

将 .tflite 模型文件（例如 mnist.tflite）放入 Unity 项目的 Assets/Resources 或任意文件夹中，并确保其 Import Settings 中未被排除。

2. 编写推理脚本

创建一个 C# 脚本，引入命名空间并加载模型：

using UnityEngine;
using TensorFlowLite;
using TensorFlowLite.Common;

public class MnistInference : MonoBehaviour
{
    private Interpreter interpreter;
    private float[] inputBuffer = new float[784]; // 28x28
    private float[] outputBuffer = new float[10]; // 10 classes

    void Start()
    {
        // 加载模型 (假设模型放在 Resources 文件夹下)
        var modelAsset = Resources.Load<TextAsset>("mnist");
        var model = Model.FromBuffer(modelAsset.bytes);
        
        // 创建解释器
        interpreter = new Interpreter(model);
        interpreter.AllocateTensors();
    }

    void Update()
    {
        // 1. 填充输入数据 (此处仅为示例，实际需从纹理或输入设备获取)
        for (int i = 0; i < inputBuffer.Length; i++)
        {
            inputBuffer[i] = 0.5f; 
        }

        // 2. 设置输入张量
        interpreter.SetInputTensorData(0, inputBuffer);

        // 3. 执行推理
        interpreter.Invoke();

        // 4. 获取输出结果
        interpreter.GetOutputTensorData(0, outputBuffer);

        // 5. 处理结果 (找出最大概率的类别)
        int predictedClass = 0;
        float maxProb = outputBuffer[0];
        for (int i = 1; i < outputBuffer.Length; i++)
        {
            if (outputBuffer[i] > maxProb)
            {
                maxProb = outputBuffer[i];
                predictedClass = i;
            }
        }

        Debug.Log($"预测结果：数字 {predictedClass}, 置信度：{maxProb}");
    }

    void OnDestroy()
    {
        interpreter?.Dispose();
    }
}

3. 运行与测试

1. 将脚本挂载到场景中的 GameObject 上。
2. 点击 Play，查看 Console 输出的推理结果。
3. 参考 Assets/Samples 目录下的官方示例场景（如 Mnist, ObjectDetection, HandTracking），直接运行即可体验完整功能。

提示：不同平台（iOS/Android）可能需要额外配置权限或 Player Settings，具体请参考各示例场景的预设配置。