Sonos的神经网络推理引擎。

该项目曾被称为tfdeploy，即Tensorflow-deploy-rust。

是什么？

tract是一个神经网络推理工具包。它可以读取ONNX或NNEF格式的模型，对其进行优化并运行。

快速入门与示例

• 使用ONNX格式的MobileNet v2
• 使用ONNX格式的BERT示例
• 使用TensorFlow格式的MobileNet v2
• 从Keras和TensorFlow 2转换为tract
• 使用PyTorch的ResNet

此外，还有一些技术文档和博客文章可供参考。

tract在行业中的位置

ONNX

截至今日，tract成功通过了约85%的ONNX后端测试。ONNX测试套件中所有“实际应用”的集成测试均已通过：包括bvlc_alexnet、densenet121、inception_v1、inception_v2、resnet50、shufflenet、squeezenet、vgg19以及zfnet512等模型。

目前仍缺失的部分主要是处理张量序列和可选张量的算子。tract的核心设计理念是只处理张量流，而不涉及其他复杂结构。这一设计具有一定的结构性限制，若要修改将较为困难，且可能会影响性能和可维护性。我们尚未看到这些功能在实际应用中展现出显著价值，因此暂时选择不支持。

此外，还有一些特定的算子（如Resize）虽然完全符合框架的设计理念，但其内部逻辑较为复杂，与我们的核心业务目标存在一定距离。对于这类情况，我们非常欢迎社区贡献，并愿意提供帮助。

以下是一些已实现并经过测试的算子：

Abs, Acos, Acosh, Add, And, ArgMax, ArgMin, ArrayFeatureExtractor, Asin, Asinh, Atan, Atanh, AveragePool, BatchNormalization, BitShift, BitwiseAnd, BitwiseNot, BitwiseOr, BitwiseXor, BlackmanWindow, Cast, CastLike, CategoryMapper, Ceil, Clip, Compress, Concat, Constant, ConstantLike, ConstantOfShape, Conv, ConvInteger, ConvTranspose, Cos, Cosh, CumSum, DFT, DepthToSpace, DequantizeLinear, Div, Dropout, DynamicQuantizeLinear, Einsum, Elu, Equal, Erf, Exp, Expand, EyeLike, Flatten, Floor, GRU, Gather, GatherElements, GatherND, Gemm, GlobalAveragePool, GlobalLpPool, GlobalMaxPool, Greater, GreaterOrEqual, HammingWindow, HannWindow, HardSigmoid, Hardmax, Identity, If, InstanceNormalization, IsInf, IsNaN, LRN, LSTM, LeakyRelu, Less, LessOrEqual, Log, LogSoftmax, MatMul, MatMulInteger, Max, MaxPool, Mean, MelWeightMatrix, Min, Mod, Mul, Multinomial, Neg, NonMaxSuppression, NonZero, Not, OneHot, Or, PRelu, Pad, ParametricSoftplus, Pow, QLinearConv, QLinearMatMul, QuantizeLinear, RNN, RandomNormal, RandomNormalLike, RandomUniform, RandomUniformLike, Range, Reciprocal, ReduceL1, ReduceL2, ReduceLogSum, ReduceLogSumExp, ReduceMax, ReduceMean, ReduceMin, ReduceProd, ReduceSum, ReduceSumSquare, Relu, Reshape, Resize, Round, Rsqrt, STFT, ScaledTanh, Scan, Scatter, ScatterElements, ScatterND, Selu, Shape, Shrink, Sigmoid, Sign, Sin, Sinh, Size, Slice, Softmax, Softplus, Softsign, SpaceToDepth, Split, Sqrt, Squeeze, Sub, Sum, Tan, Tanh, ThresholdedRelu, Tile, Transpose, TreeEnsembleClassifier, Unsqueeze, Where, Xor

我们对这些算子进行了全面测试，覆盖了从ONNX 1.4.1（算子集9）到ONNX 1.13.0（算子集18）的所有版本。

尽管我们使用了ONNX测试套件，但它并不能涵盖所有场景。同时，我们也根据实际情况有意识地忽略了一些测试用例，或对其范围进行了限制。然而，随着时间推移和领域的发展，某些决策可能会变得不再适用。因此，如果您遇到无法在tract中运行的ONNX模型，欢迎随时联系我们进行排查。

NNEF

简而言之，TensorFlow和ONNX格式非常适合用于网络的设计和训练。它们需要快速迭代以跟上研究领域的进展，往往会积极引入新特性和算子，并具备较高的表达能力，便于网络设计。

然而，在实际生产环境中，真正被部署的算子和网络特性往往只是其中的一小部分。因此，用于预测的生产系统并不需要支持如此多的算子。此外，一些仅在训练阶段有用的信息也可以在部署前从网络中移除。

NNEF旨在弥合训练框架与推理之间的差距，提出了一种专为生产和预测设计的格式。

tract支持NNEF：

• tract_nnef模块可以加载并执行NNEF格式的模型。
• tract支持NNEF规范中的大多数内容，最显著的例外是ROI相关的算子。
• tract还引入了tract-OPL扩展，用于支持更多算子或扩展现有算子的功能语义，从而能够表示tract-core所支持的完整算子集合：任何由tract理解的网络都应能被序列化为tract-OPL格式。目前这一工作仍在推进中。
• tract命令行工具还可以将TensorFlow或ONNX格式的模型转换为NNEF/OPL格式。

tract-opl 版本兼容性

提醒一下：NNEF 的表达能力不足以表示所有的 ONNX 模型。tract-OPL 通过专有扩展来弥补 NNEF 的不足，支持那些缺失的功能。显著的扩展包括脉冲算子、循环算子（如 Scan）以及符号化扩展。

目前并没有严格的版本检查机制，因此实现并不完全健壮。

• NNEF 部分旨在保持高度稳定，并严格遵循 NNEF 规范以确保兼容性。

• tract-opl 则相对更加灵活多变。尽管如此，我们仍坚持以下黄金法则：

  使用 tract 0.x.y 序列化的模型应在 tract 0.x.z 中正常运行，其中 z ≥ y

• 实际上，迄今为止破坏性变更相对较少。自 tract 支持 NNEF 以来，大多数模型都具备向前和向后的兼容性。

值得注意的不兼容情况包括：

• 0.16.3 版本（向前兼容）对 Scan 算子的处理变化
• 0.17.0 版本对二元决策树分类器的支持调整

从 0.17.0 版本开始，tract-opl 文件中会注入一个模型属性 (tract_nnef_ser_version)，用于标记生成该文件的 tract 版本。由于大多数模型仍将保持兼容性，tract 不会进行版本检查，而是由应用程序开发者自行负责。

此外，还有一个较为宽松的版本标签 tract_nnef_format_version。0.17.0 之前的版本将其设置为 alpha1，而之后的版本则设置为 beta1。请不要过于在意这里的“alpha”命名。

注意：对 TensorFlow 1.x 的支持

尽管 tract 距离支持任意模型还有很大差距，但它已经能够运行 Google Inception v3 和 Snips 唤醒词模型。缺失的算子相对容易添加。然而，缺乏易于复用的测试套件，以及 TensorFlow 中算子种类繁多，使得全面支持变得困难。

目前已实现并经过测试的算子包括：

Abs, Add, AddN, AddV2, Assign, AvgPool, BatchToSpaceND, BiasAdd, BlockLSTM, Cast, Ceil, ConcatV2, Const, Conv2D, DepthwiseConv2dNative, Div, Enter, Equal, Exit, ExpandDims, FakeQuantWithMinMaxVars, Fill, FloorMod, FusedBatchNorm, GatherNd, GatherV2, Greater, GreaterEqual, Identity, Less, LessEqual, Log, LogicalAnd, LogicalOr, LoopCond, MatMul, Max, MaxPool, Maximum, Mean, Merge, Min, Minimum, Mul, Neg, NoOp, Pack, Pad, Placeholder, Pow, Prod, RandomUniform, RandomUniformInt, Range, RealDiv, Relu, Relu6, Reshape, Rsqrt, Shape, Sigmoid, Slice, Softmax, SpaceToBatchND, Squeeze, StridedSlice, Sub, Sum, Switch, Tanh, Tile, Transpose, VariableV2

另外，TensorFlow 2 的复杂性使得 tract 很难直接支持它。不过，许多 TensorFlow 2 模型可以转换为 ONNX 格式，然后再加载到 tract 中。

支持的网络示例

这些模型以及其他模型被用于跟踪 tract 性能的演变，作为持续集成任务的一部分。更多信息请参阅 .travis/README.md 和 .travis/bundle-entrypoint.sh。

ARM Cortex-M 微控制器上的关键词检测

https://github.com/ARM-software/ML-KWS-for-MCU

ARM 通过提供教程和预训练的关键词检测模型，展示了 Cortex-M 系列处理器的能力。虽然这一实践主要面向微控制器，但 tract 仍然可以运行其中间步骤的 TensorFlow 模型。

例如，在 Raspberry Pi Zero 上，“CNN M”模型的推理时间约为 70 微秒；而在 Raspberry Pi 3 上，则为 11 微秒。

Snips 唤醒词模型

https://arxiv.org/abs/1811.07684

Snips 使用 tract 来运行唤醒词检测器。早期的模型基于分类任务，无需特殊处理；而得益于 tract 的脉冲计算能力，WaveNet 模型得以在 Raspberry Pi Zero 上高效运行。

Inception v3

设备	架构	TensorFlow-lite	tract
Raspberry Pi Zero	Armv6 VFP	113s	39s
Raspberry Pi 2	Armv7 NEON	25s	7s
Raspberry Pi 3	aarch32 NEON	5s	5s

注释：

• 尽管 Raspberry Pi 3 是一款 Armv8 设备，但本次基准测试是在 Raspbian 操作系统上进行的，该系统基于 armv6 架构，这严重限制了两个框架的性能。
• 网络上存在其他关于 Pi 3 上 TensorFlow（非 Lite 版本）性能的基准测试结果，显示其表现更好。这些测试利用了设备的四核处理器。而此处的 TensorFlow-Lite 和 tract 均仅在单核环境下运行。

许可证

注意：tensorflow/protos 目录下的文件是从 TensorFlow 项目复制而来，并不受以下许可声明的约束。

注意：onnx/protos 目录下的文件是从 ONNX 项目复制而来，也不受以下许可声明的约束。

Apache 2.0/MIT

所有原创作品均根据您的选择，采用以下任一许可证进行授权：

• Apache License, Version 2.0 (LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

贡献

除非您明确声明相反意见，否则您有意提交并纳入本作品的任何贡献，将按照 Apache-2.0 许可协议的规定，以双重许可方式授权，且不附加任何额外条款或条件。

tract 快速上手指南

tract 是 Sonos 开发的高性能神经网络推理引擎（基于 Rust），支持加载、优化并运行 ONNX 和 NNEF 格式的模型。它特别适用于嵌入式设备、边缘计算及对性能敏感的生产环境。

环境准备

系统要求

• 操作系统：Linux (推荐), macOS, Windows
• 架构支持：x86_64, ARM (包括 Cortex-M 微控制器), AArch64
• Rust 版本：rustc >= 1.91.0

前置依赖

确保已安装 Rust 工具链。若未安装，请使用以下命令（国内开发者推荐使用清华或中科大镜像加速）：

# 使用国内镜像安装 rustup
export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
curl --proto '=https' --tlsv1.2 -sSf https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup-init.sh | sh

# 安装完成后，确保 rustc 版本 >= 1.91.0
rustc --version

若需使用 Python 绑定，请确保已安装 Python 3.6+ 及 pip。

安装步骤

方式一：作为 Rust 库使用

在你的 Rust 项目 Cargo.toml 中添加依赖：

[dependencies]
tract-onnx = "0.21" # 请根据 crates.io 最新版本调整
# 或者同时支持 TensorFlow
tract-tensorflow = "0.21"

然后在代码中引入：

use tract_onnx::prelude::*;

方式二：使用命令行工具 (CLI)

安装 tract 命令行工具以便直接转换或运行模型：

cargo install tract

注：国内网络若下载 crates 索引缓慢，可配置 .cargo/config.toml 使用稀疏协议或替换源。

方式三：Python 绑定

通过 PyPI 安装（支持国内镜像加速）：

pip install tract -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

场景 1：使用命令行运行 ONNX 模型

假设你有一个名为 mobilenet_v2.onnx 的模型和一个输入图像预处理后的张量文件 input.npy。

1. 查看模型信息：

   tract mobilenet_v2.onnx info
   

2. 运行推理（自动处理输入输出）：

   tract mobilenet_v2.onnx run input.npy
   

3. 将 ONNX 模型转换为 NNEF 格式（用于生产部署）：

   tract mobilenet_v2.onnx dump --nnef my_model.nnef
   

场景 2：在 Rust 代码中加载并运行模型

以下是最小化的 Rust 示例，展示如何加载 ONNX 模型并执行推理：

use tract_onnx::prelude::*;

fn main() -> TractResult<()> {
    // 1. 加载并构建模型
    let model = tract_onnx::onnx()
        .model_for_path("mobilenet_v2.onnx")?
        .into_optimized()?
        .into_runnable()?;

    // 2. 创建输入张量 (示例：1x3x224x224 的 f32 张量)
    let input = tensor4(&[[[[0.0f32; 224]; 224]; 3]; 1]);
    
    // 3. 运行推理
    let output = model.run(tvec!(input))?;
    
    // 4. 获取结果
    println!("推理完成，输出形状：{:?}", output[0].shape());
    
    Ok(())
}

场景 3：在 Python 中使用

import tract

# 加载 ONNX 模型
model = tract.onnx().model_for_path("mobilenet_v2.onnx")

# 优化并准备运行
runnable = model.optimize().to_runnable()

# 创建输入数据 (需符合模型输入形状)
import numpy as np
input_data = np.zeros((1, 3, 224, 224), dtype=np.float32)

# 执行推理
outputs = runnable.run([input_data])
print(outputs[0].shape)

提示：更多复杂示例（如 BERT、ResNet、TensorFlow 模型转换）请参考官方仓库的 examples/ 目录。