ONNX 的 TensorFlow 后端

注意：此仓库目前不再积极维护，并将被弃用。如果您有意成为其所有者，请联系 ONNX 指导委员会（https://github.com/onnx/steering-committee）。

开放神经网络交换格式（ONNX） 是一种用于表示机器学习模型的开放标准格式。ONNX 得到了众多合作伙伴社区的支持，这些伙伴已在许多框架和工具中实现了对 ONNX 的支持。

ONNX 的 TensorFlow 后端使得可以将 ONNX 模型作为 TensorFlow 的输入。首先将 ONNX 模型转换为 TensorFlow 模型，然后将其委托给 TensorFlow 执行以生成输出。

这是 ONNX 社区中服务于不同目的的两个 TensorFlow 转换器项目之一：

• onnx-tensorflow 将 ONNX 模型转换为 TensorFlow 模型
• tf2onnx 将 TensorFlow 模型转换为 ONNX 模型

从 ONNX 到 TensorFlow 的模型转换

使用命令行界面

命令行界面文档

从 ONNX 到 TensorFlow：onnx-tf convert -i /path/to/input.onnx -o /path/to/output

以编程方式转换

从 ONNX 到 TensorFlow

从 onnx-tf 迁移到 tf-onnx

我们已与微软合作共同开发 ONNX 的 TensorFlow 前端。对于当前使用 onnx-tf 前端的用户，请迁移至使用 tf-onnx (https://github.com/onnx/tensorflow-onnx)，我们的代码已合并到其中。

使用 TensorFlow 后端进行 ONNX 模型推理

import onnx
from onnx_tf.backend import prepare

onnx_model = onnx.load("input_path")  # 加载 ONNX 模型
output = prepare(onnx_model).run(input)  # 运行加载的模型

更多教程

使用 TensorFlow 运行 ONNX 模型

生产环境安装

ONNX-TF 需要将 ONNX（开放神经网络交换格式）作为外部依赖项。如遇到 ONNX 安装相关问题，我们建议用户参考 ONNX 项目仓库 获取文档和帮助。值得注意的是，如果您计划通过 pip 安装 ONNX，请确保 protoc 已可用。

我们在 ONNX-TF 主分支中支持的具体 ONNX 发布版本号可在 此处 查看。关于 ONNX 版本要求的信息会自动编码在 setup.py 中，因此用户在安装 ONNX-TF 时无需担心 ONNX 版本兼容性问题。

要通过 pip 安装最新版本的 ONNX-TF，请运行 pip install onnx-tf。

由于用户通常偏好安装不同版本的 TensorFlow（例如 GPU 版本而非 CPU 版本），我们在安装脚本中并未明确要求安装 TensorFlow。因此，确保 ONNX-TF 可以使用正确版本的 TensorFlow 是用户的责任。此外，我们要求 TensorFlow 版本必须为 2.8.0。

开发

覆盖率状态

ONNX-TensorFlow 操作覆盖率状态

API

ONNX-TensorFlow API

安装

• 从源码安装 ONNX 主分支。
• 安装 TensorFlow >= 2.8.0、tensorflow-probability 和 tensorflow-addons。（注意：TensorFlow 1.x 已不再支持）
• 运行 git clone https://github.com/onnx/onnx-tensorflow.git && cd onnx-tensorflow。
• 运行 pip install -e .。

文件夹结构

• onnx_tf：主源代码文件。
• test：测试文件。

代码规范

• 格式化代码

pip install yapf
yapf -rip --style="{based_on_style: google, indent_width: 2}" $FilePath$

• 安装 pylint

pip install pylint
wget -O /tmp/pylintrc https://raw.githubusercontent.com/tensorflow/tensorflow/master/tensorflow/tools/ci_build/pylintrc

• 检查格式

pylint --rcfile=/tmp/pylintrc myfile.py

文档规范

Google 风格的 Python 文档字符串

测试

单元测试

要执行 单元测试：

pip install pytest tabulate
python -m unittest discover test

注意：只有位于 test_onnx_backend.py 中的 ONNX 后端测试需要 pytest 和 tabulate 包。

测试需要大量的硬件资源，但我们仍然强烈建议用户在部署 onnx-tf 之前先运行完整的测试套件。根据硬件配置的不同，完整测试套件通常需要 15 到 45 分钟才能完成。

Model Zoo 测试

位于 test_modelzoo.py 中的测试用于验证 ONNX Model Zoo 中的模型是否能够成功通过 ONNX 规范的验证，并被转换为 TensorFlow 表示形式。目前尚未对转换后的模型进行推理测试。

先决条件

Model Zoo 使用 Git LFS（大文件存储） 来存储 ONNX 模型文件。请确保您的操作系统上已安装 Git LFS。

运行

默认情况下，测试假设 Model Zoo 仓库已被克隆到该项目目录中。系统会扫描 Model Zoo 目录以查找 ONNX 模型。对于每个找到的模型：下载该模型，将其转换为 TensorFlow 格式，生成测试状态，并删除该模型。默认情况下，生成的测试报告会保存在系统的临时目录中。运行 python test/test_modelzoo.py -h 以获取命令行选项的帮助。

git clone https://github.com/onnx/models
python test/test_modelzoo.py

测试所有模型可能需要至少一个小时，具体时间取决于硬件配置和模型下载速度。如果您预计会频繁测试某些模型，我们建议您在运行测试之前先使用 Git LFS 下载这些模型，以便将大文件缓存在本地。

报告

在进行代码贡献时，每当有提交合并时，都会运行 Model Zoo 测试。生成的测试报告会发布在 onnx-tensorflow wiki 上。

onnx-tensorflow 快速上手指南

⚠️ 重要提示：该仓库目前不再积极维护，即将被弃用。如果您是新用户，建议优先考虑迁移至 tf2onnx 或其他活跃项目。如需成为该项目维护者，请联系 ONNX 指导委员会。

1. 环境准备

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

• 操作系统：Linux, macOS 或 Windows
• Python：推荐 Python 3.x
• 核心依赖：
  • ONNX：需预先安装。若通过 pip 安装 ONNX，请确保系统已安装 protoc 编译器。
  • TensorFlow：必须严格等于 2.8.0 版本 (tensorflow==2.8.0)。不支持 TensorFlow 1.x 或其他 2.x 版本。
  • 其他库：tensorflow-probability, tensorflow-addons。
• 可选工具（用于开发或完整测试）：
  • Git LFS：运行 Model Zoo 测试时需要。
  • pytest, tabulate：运行部分单元测试时需要。

💡 国内加速建议：安装依赖时推荐使用国内镜像源以提升下载速度。 例如使用清华源：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple <package_name>

2. 安装步骤

方式一：通过 Pip 安装（推荐生产环境）

这是最简单的安装方式。请注意，安装脚本不会自动安装 TensorFlow，您需要手动确保环境中已存在正确版本的 TensorFlow。

# 1. 手动安装指定版本的 TensorFlow 及其他依赖
pip install tensorflow==2.8.0 tensorflow-probability tensorflow-addons

# 2. 安装 onnx-tf
pip install onnx-tf

方式二：从源码安装（推荐开发环境）

如果您需要修改代码或使用最新特性，可以从 GitHub 克隆源码进行安装。

# 1. 确保已安装 ONNX (从源码或 pip) 和 TensorFlow 2.8.0

# 2. 克隆仓库
git clone https://github.com/onnx/onnx-tensorflow.git
cd onnx-tensorflow

# 3. 以可编辑模式安装
pip install -e .

3. 基本使用

onnx-tensorflow 主要用于将 ONNX 模型转换为 TensorFlow 模型，或直接使用 TensorFlow 后端推理 ONNX 模型。

场景一：命令行转换 (CLI)

将 .onnx 模型文件转换为 TensorFlow 格式（SavedModel）。

onnx-tf convert -i /path/to/input.onnx -o /path/to/output

场景二：Python 代码推理

直接在 Python 中加载 ONNX 模型并使用 TensorFlow 后端进行推理，无需显式保存中间文件。

import onnx
from onnx_tf.backend import prepare

# 加载 ONNX 模型
onnx_model = onnx.load("input_path") 

# 准备后端并运行推理 (input 为符合模型要求的输入数据)
output = prepare(onnx_model).run(input) 

场景三：编程式转换

如果您需要在代码中执行转换逻辑，可参考官方示例： From ONNX to TensorFlow Example