uTensor - 测试版本发布

注意：如果您正在寻找稳定版本，请检出 master 分支。

教程

构建教程示例

确保您的系统上已安装 cmake（构建工具）并运行以下命令：

$ mkdir build
$ cd build
$ cmake -DPACKAGE_TUTORIALS=ON ..
$ make

构建过程完成后，您应该在 build/tutorials/ 目录下找到教程可执行文件。

遵循每个教程目录中 README.md 的说明来学习如何使用 uTensor。

以下是教程链接：

1. 使用 uTensor 进行错误处理
2. 自定义算子

简介

它是什么？

uTensor 是一个极轻量级的机器学习推理框架，基于 Tensorflow（深度学习框架）构建并针对 Arm（处理器架构）目标进行了优化。它由一个运行时库（Runtime library）和一个离线工具组成，后者处理大部分模型转换工作。此仓库包含核心运行时以及一些算子（Operators）、内存管理器/调度器（Memory managers/schedulers）的示例实现，且核心运行时的大小仅为 ~2KB！

Module	.text	.data	.bss
uTensor/src/uTensor/core	1275(+1275)	4(+4)	28(+28)
uTensor/src/uTensor/tensors	791(+791)	0(+0)	0(+0)

uTensor 工作流程是如何运作的？

模型在 Tensorflow 中构建和训练。uTensor 接收该模型并生成 .cpp 和 .hpp 文件。这些文件包含推理所需的生成的 C++11 代码。在嵌入式侧使用 uTensor 就像复制粘贴一样简单。

uTensor 运行时是如何工作的？

在此处查看详细描述

发布说明

此次重构从根本上围绕几个关键理念展开，代码库结构和构建工具也随之自然演变。 旧的关键点：

• 张量 (Tensor) 描述数据如何访问以及来自何处
  • 算子 (Ops) 的性能取决于使用了哪些张量
• 算子 (Operators) 是独立于张量的
  • 高性能算子可以一次性获取数据块
• 追求执行过程中的低总功耗
• 低静态和动态占用空间，保持小巧
  • 整个系统中每个张量的成本低，因为大多数生成的模型包含 100+ 个（包括中间变量），这也影响动态占用空间
  • 轻量级类层次结构
  • 显而易见

新的附加关键理念：

• 系统安全性
  • 所有张量元数据和实际数据都拥有在专用区域中
    • 这可以由用户提供，也可以是我们创建的
  • 我们可以保证在代码生成时或编译时，运行时使用的 RAM 不超过 N 字节！
  • 通常不应与用户空间或系统空间内存冲突，即不要共享堆
  • 一般含义：安全的运行时意味着我们可以安全地远程更新模型
  • 尽可能多的编译时错误！
    • 输入、输出或数量不匹配
    • 使用了错误的尺寸
    • 不可能的内存访问
    • 等等
• 清晰、简洁且可调试
  • uTensor 的前一版本几乎过于依赖代码生成 (Codegen)，出于任何原因修改模型都几乎不可能
  • 开发人员应该能够在不依赖代码生成的情况下修改模型
  • 开发人员应该能够查看模型文件并立即理解图的结构，而无需大量跳转
  • 默认张量接口应表现得像高级语言，同时利用 C++ 的速度
    • 一般来说：别再搞指针垃圾了！C 语言极易出错，不服来战
      • 只有专用算子可以访问原始数据块，这些算子将非常快
  • 可扩展、可配置且可优化掉的错误处理
  • GDB（调试器）调试现在变得极其简单

如前所述，这些关键理念不仅需要在代码中体现，还需要体现在代码结构中，使其具有可维护性、可修改性和用户可扩展性。uTensor 运行时中的几乎所有内容都可以分为两个组件：核心和其他部分。核心库包含运行时实现上述保证所需的所有底层深度功能，以及具体实现所需的接口。此外，相对于系统操作，此核心引擎的开销应该可以忽略不计。核心库之外的所有内容实际上都应被视为合理的默认值。例如，张量实现、默认算子、示例内存分配器，甚至可能的日志系统和错误处理器。这些模块应该是未来优化的主要领域，特别是在模型部署之前。

高级 API

using namespace uTensor;

const uint8_t s_a[4] = {1, 2, 3, 4};
const uint8_t s_b[4] = {5, 6, 7, 8};
const uint8_t s_c_ref[4] = {19, 22, 43, 50};

// These can also be embedded in models
// Recommend, not putting these on the heap or stack directly as they can be large
localCircularArenaAllocator<256> meta_allocator; // All tensor metadata gets stored here automatically, even when new is called
localCircularArenaAllocator<256> ram_allocator;  // All temporary storage gets allocated here

void foo() {
  // Tell the uTensor context which allocators to use
  Context::get_default_context()->set_metadata_allocator(&meta_allocator);
  Context::get_default_context()->set_ram_data_allocator(&ram_allocator);

  // Tensors are simply handles for accessing data as necessary, they are no larger than a pointer
  // RomTensor(TensorShape, data_type, data*);
  Tensor a = new /*const*/ RomTensor({2, 2}, u8, s_a);
  Tensor b = new /*const*/ RomTensor({2, 2}, u8, s_b);
  Tensor c_ref = new RomTensor({2,2}, u8, s_c_ref);
  // RamTensors are held internally and can be moved or cleared depending on the memory schedule (optional)
  Tensor c = new RamTensor({2, 2}, u8);

  // Operators take in a fixed size map of (input_name -> parameter), this gives compile time errors on input mismatching
  // Also, the name binding + lack of parameter ordering makes ctag jumping and GDB sessions significantly more intuitive
  MatrixMultOperator<uint8_t> mult_AB;
  mult_AB
      .set_inputs({{MatrixMultOperator<uint8_t>::a, a}, {MatrixMultOperator<uint8_t>::b, b}})
      .set_outputs({{MatrixMultOperator<uint8_t>::c, c}})
      .eval();

  // Compare results
  TensorShape& c_shape = c->get_shape();
  for (int i = 0; i < c_shape[0]; i++) {
    for (int j = 0; j < c_shape[1]; j++) {
      // Just need to cast the access to the expected type
      if( static_cast<uint8_t>(c(i, j)) != static_cast<uint8_t>(c_ref(i, j)) ) {
        printf("Oh crap!\n");
        exit(-1);
      }
    }
  }
}

本地构建与测试

git clone git@github.com:uTensor/uTensor.git
cd uTensor/
git checkout proposal/rearch
git submodule init
git submodule update
mkdir build
cd build/
cmake -DPACKAGE_TESTS=ON -DCMAKE_BUILD_TYPE=Debug ..
make
make test

在 Arm Mbed OS 上构建和运行

uTensor 核心库开箱即用地配置为 Mbed (嵌入式开发平台) 库，因此我们只需将其导入项目并正常构建。

mbed new my_project
cd my_project
mbed import https://github.com/uTensor/uTensor.git
# Create main file
# Run uTensor-cli workflow and copy model directory here
mbed compile # as normal

在 Arm 系统上构建和运行

TODO 注意：CMake (跨平台构建工具) 对 ARM (处理器架构) 的支持目前处于实验阶段 https://stackoverflow.com/questions/46916611/cross-compiling-googletest-for-arm64

默认构建

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=../extern/CMSIS_5/CMSIS/DSP/gcc.cmake  ..

使用 CMSIS (微控制器软件接口标准) 优化内核

mkdir build && cd build
cmake -DARM_PROJECT=1 -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=../extern/CMSIS_5/CMSIS/DSP/gcc.cmake  ..

延伸阅读

• 为什么是边缘计算
• 为什么机器学习的未来是微型化
• TensorFlow
• Mbed
• Node-Viewer
• 如何使用 TensorFlow 量化神经网络
• MXNet 手写数字识别

uTensor 快速上手指南

uTensor 是一个基于 TensorFlow 构建的超轻量级机器学习推理框架，专为 ARM 目标设备优化。其核心运行时库仅约 2KB，适合资源受限的嵌入式环境。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux / macOS / Windows (需支持 CMake)
• 版本控制：Git
• 构建工具：CMake (需安装在系统路径中)
• 编译器：支持 C++11 标准的 C++ 编译器
• 依赖：ARM Mbed OS (若用于嵌入式开发)

安装步骤

1. 克隆仓库并初始化子模块

git clone git@github.com:uTensor/uTensor.git
cd uTensor/
git checkout proposal/rearch
git submodule init
git submodule update

注意：如果您寻找稳定版本，可切换至 master 分支。本指南基于当前架构重构版本 (proposal/rearch) 编写。

2. 配置与编译

创建构建目录并运行 CMake 配置：

mkdir build
cd build/
cmake -DPACKAGE_TESTS=ON -DCMAKE_BUILD_TYPE=Debug ..
make
make test

编译完成后，测试用例将位于 build/ 目录下。

3. 嵌入式集成 (可选)

uTensor 核心库已配置为 Mbed 库，可直接导入项目：

mbed new my_project
cd my_project
mbed import https://github.com/uTensor/uTensor.git
# 创建 main 文件
# 运行 uTensor-cli 工作流并将模型目录复制至此
mbed compile # 正常编译

基本使用

uTensor 的工作流是：在 TensorFlow 中构建训练模型 -> 使用 uTensor 工具生成 .cpp 和 .hpp 文件 -> 在嵌入式端进行推理。

以下是使用 uTensor 高级 API 进行矩阵乘法运算的示例：

using namespace uTensor;

const uint8_t s_a[4] = {1, 2, 3, 4};
const uint8_t s_b[4] = {5, 6, 7, 8};
const uint8_t s_c_ref[4] = {19, 22, 43, 50};

// These can also be embedded in models
// Recommend, not putting these on the heap or stack directly as they can be large
localCircularArenaAllocator<256> meta_allocator; // All tensor metadata gets stored here automatically, even when new is called
localCircularArenaAllocator<256> ram_allocator;  // All temporary storage gets allocated here

void foo() {
  // Tell the uTensor context which allocators to use
  Context::get_default_context()->set_metadata_allocator(&meta_allocator);
  Context::get_default_context()->set_ram_data_allocator(&ram_allocator);

  // Tensors are simply handles for accessing data as necessary, they are no larger than a pointer
  // RomTensor(TensorShape, data_type, data*);
  Tensor a = new /*const*/ RomTensor({2, 2}, u8, s_a);
  Tensor b = new /*const*/ RomTensor({2, 2}, u8, s_b);
  Tensor c_ref = new RomTensor({2,2}, u8, s_c_ref);
  // RamTensors are held internally and can be moved or cleared depending on the memory schedule (optional)
  Tensor c = new RamTensor({2, 2}, u8);

  // Operators take in a fixed size map of (input_name -> parameter), this gives compile time errors on input mismatching
  // Also, the name binding + lack of parameter ordering makes ctag jumping and GDB sessions significantly more intuitive
  MatrixMultOperator<uint8_t> mult_AB;
  mult_AB
      .set_inputs({{MatrixMultOperator<uint8_t>::a, a}, {MatrixMultOperator<uint8_t>::b, b}})
      .set_outputs({{MatrixMultOperator<uint8_t>::c, c}})
      .eval();

  // Compare results
  TensorShape& c_shape = c->get_shape();
  for (int i = 0; i < c_shape[0]; i++) {
    for (int j = 0; j < c_shape[1]; j++) {
      // Just need to cast the access to the expected type
      if( static_cast<uint8_t>(c(i, j)) != static_cast<uint8_t>(c_ref(i, j)) ) {
        printf("Oh crap!\n");
        exit(-1);
      }
    }
  }
}

更多教程示例（如错误处理、自定义算子）可在 tutorials/ 目录下找到。