这是一个用于 Open Neural Network Exchange (ONNX) 的 Go 接口。

使用前必读

该项目最初由 owulveryck 创建，并于 2024 年 5 月 31 日归档。

在 Orama，我们决定重启该项目，并将投入大量精力使其焕发生机！

在此，我们要感谢 owulveryck 的杰出工作以及对我们的信任与支持。

我们现在开始积极维护该项目，因此如果您发现任何问题，请耐心等待。

感谢您的理解！

概述

onnx-go 包含将 ONNX 二进制模型解码为计算后端的原语，并可在您的 Go 代码中像使用其他库一样使用它。 有关 ONNX 的更多信息，请访问 onnx.ai。

目前，对 ONNX 规范 的实现仅限于导入部分，而导出功能尚不存在。

愿景声明

对于需要在其代码中添加机器学习功能的 Go 开发人员而言， onnx-go 是一个能够简化神经网络模型（软件 2.0）使用的包。 与其他计算库不同，该包无需具备数据科学方面的特殊技能。

警告：API 尚处于实验阶段，可能会发生变化。

免责声明

这是 API 的新版本。
已移除经过调整的 Gorgonia 版本。现在它与 Gorgonia 的主分支兼容。
不过，仍有一些算子尚未实现。

新增了一个实用工具，用于运行模型动物园中的模型。
请查看 `examples` 子目录。

安装

通过 go get 安装：

go get github.com/owulveryck/onnx-go

onnx-go 与 Go 模块 兼容。

示例

这些示例假设您已经有一个预先训练好的 model.onnx 文件。 您可以从 ONNX 模型动物园 下载预训练模型。

非常简单的示例

此示例仅将图解码为一个简单的后端。 之后，您可以对生成的图执行任何操作。

// 创建一个后端接收器
backend := simple.NewSimpleGraph()
// 创建一个模型并设置执行后端
model := onnx.NewModel(backend)

// 读取 ONNX 模型
b, _ := ioutil.ReadFile("model.onnx")
// 将其解码到模型中
err := model.UnmarshalBinary(b)

运行预训练模型的简单示例

此示例使用 Gorgonia 作为后端。

import "github.com/owulveryck/onnx-go/backend/x/gorgonnx"

目前，Gorgonia 尚未实现 ONNX 的所有算子。因此，大多数来自模型动物园的模型将无法正常运行。 随着更多算子被添加到后端，情况会逐渐改善。

您可以在 这里 找到已测试示例的列表及覆盖率信息。

func Example_gorgonia() {
	// 创建一个后端接收器
	backend := gorgonnx.NewGraph()
	// 创建一个模型并设置执行后端
	model := onnx.NewModel(backend)

	// 读取 ONNX 模型
	b, _ := ioutil.ReadFile("model.onnx")
	// 将其解码到模型中
	err := model.UnmarshalBinary(b)
	if err != nil {
		log.Fatal(err)
	}
	// 设置第一个输入，数量取决于模型
	model.SetInput(0, input)
	err = backend.Run()
	if err != nil {
		log.Fatal(err)
	}
	// 检查输出
	output, _ := model.GetOutputTensors()
	// 将第一个输出写入标准输出
	fmt.Println(output[0])
}

模型动物园

在 examples 子目录中，您将找到一个用于运行模型动物园中模型的实用工具，以及一个使用 Tiny YOLO v2 分析图片的示例工具。

内部

ONNX Protobuf 定义

ONNX 的 Protobuf 定义已使用经典的 protoc 工具编译为 Go 代码。该定义位于 internal 目录中。 为了避免对外部依赖的引入，该定义并未公开。实际上，未来可能会改用更高效的编译器（如 gogo protobuf），而这种变化应对本包的用户透明。

执行后端

为了执行神经网络，你需要一个能够执行计算图的后端（有关计算图的更多信息，请阅读这篇博客文章

这张图展示了其工作机制：

onnx-go 并不提供任何可执行的后端，但作为参考，它提供了一个简单的构建信息图的示例后端（参见 simple 子包）。Gorgonia 是 ONNX-Go 的主要目标后端。

后端实现

后端本质上是一个加权有向图，可以在其节点上应用操作。它应该实现以下接口：

type Backend interface {
	OperationCarrier
	graph.DirectedWeightedBuilder
}

type OperationCarrier interface {
	// 在图的节点上应用操作
	// graph.Node 是一个数组，因为它可以处理多个输出
	// 例如，拆分操作会返回 n 个节点...
	ApplyOperation(Operation, ...graph.Node) error
}

一个操作由其 name 和属性映射表示。例如，按照 ONNX 规范 中的描述，卷积算子将被表示为如下形式：

convOperator := Operation{
		Name: "Conv",
		Attributes: map[string]interface{}{
			"auto_pad":  "NOTSET",
			"dilations": []int64{1, 1},
			"group":     1,
			"pads":      []int64{1, 1},
			"strides":   []int64{1, 1},
		},
	}

此外，除了操作之外，节点还可以携带一个值。这些值被描述为 tensor.Tensor 类型。为了承载数据，图中的 Node 应该实现以下接口：

type DataCarrier interface {
	SetTensor(t tensor.Tensor) error
	GetTensor() tensor.Tensor
}

后端测试

onnx-go 提供了一些用于测试后端的工具。更多信息请访问 testbackend 包。

贡献

欢迎贡献。我们最终会编写一份贡献指南。在此期间，你可以提交问题或拉取请求。你也可以通过 Twitter 或 Gophers Slack 联系我（我在两个平台上都是 @owulveryck）。

本项目旨在成为一个安全、友好的协作空间，期望贡献者遵守 Contributor Covenant 行为准则。

作者

Olivier Wulveryck

许可证

MIT。

onnx-go 快速上手指南

onnx-go 是一个 Go 语言接口，用于将 ONNX（Open Neural Network Exchange）二进制模型解码为计算图，以便在 Go 代码中直接运行神经网络模型。它旨在让 Go 开发者无需深厚的数据科学背景即可集成机器学习能力。

注意：该项目目前由 Orama 团队维护并处于活跃开发中，API 仍具有实验性，可能会发生变化。

环境准备

• 操作系统：Linux、macOS 或 Windows
• Go 版本：建议使用 Go 1.13 或更高版本（支持 Go Modules）
• 前置依赖：
  • 已安装的 Go 开发环境
  • 可选后端库：如使用完整功能，需安装 Gorgonia（目前主要支持的后端）
  • 预训练的 .onnx 模型文件（可从 ONNX Model Zoo 下载）

安装步骤

使用 go get 命令安装 onnx-go：

go get github.com/owulveryck/onnx-go

onnx-go 完全兼容 Go Modules。如果你在项目中使用 Go Modules，无需额外配置即可自动管理依赖。

国内加速建议：如果下载速度较慢，可配置国内 GOPROXY 镜像：

export GOPROXY=https://goproxy.cn,direct
go get github.com/owulveryck/onnx-go

基本使用

以下示例展示如何加载一个预训练的 ONNX 模型并使用简单后端进行解码。

最简单的示例：解码模型图

此示例仅将 ONNX 模型解码为简单的计算图结构，不执行实际推理。

// Create a backend receiver
backend := simple.NewSimpleGraph()
// Create a model and set the execution backend
model := onnx.NewModel(backend)

// read the onnx model
b, _ := ioutil.ReadFile("model.onnx")
// Decode it into the model
err := model.UnmarshalBinary(b)

运行预训练模型（使用 Gorgonia 后端）

若要实际运行模型，需使用支持运算的后端（如 Gorgonia）。

import "github.com/owulveryck/onnx-go/backend/x/gorgonnx"

完整示例：

func Example_gorgonia() {
	// Create a backend receiver
	backend := gorgonnx.NewGraph()
	// Create a model and set the execution backend
	model := onnx.NewModel(backend)

	// read the onnx model
	b, _ := ioutil.ReadFile("model.onnx")
	// Decode it into the model
	err := model.UnmarshalBinary(b)
	if err != nil {
		log.Fatal(err)
	}
	// Set the first input, the number depends of the model
	model.SetInput(0, input)
	err = backend.Run()
	if err != nil {
		log.Fatal(err)
	}
	// Check error
	output, _ := model.GetOutputTensors()
	// write the first output to stdout
	fmt.Println(output[0])
}

提示：当前 Gorgonia 尚未实现所有 ONNX 算子，部分模型可能无法运行。可查看 算子覆盖列表 了解支持情况。

更多示例（如使用 Tiny YOLO v2 进行图像分析）请参考项目 examples 目录。