gonnx

README

GONNX

The goal of this package is to provide an easy way of running ONNX models in Go. This package is intended for inference usage of ONNX models. The package can be used to load an .onnx file and perform inference using the model described by this file.

Currently, we are implementing ONNX operation set 13, and we plan to add all opsets following this one as well. Feel free to contribute by implementing operators!

Getting started

Installation & setup

First, install Go on your machine. Then, clone the repository:

git clone https://github.com/AdvancedClimateSystems/gonnx.git
cd gonnx

Then, install the dependencies as follows:

make install
make install_lint
make install_gotestsum

Usage

A simple example is shown below:

package main

import (
    "github.com/advancedclimatesystems/gonnx"
    "gorgonia.org/tensor"
)


func main() {
    model, err := gonnx.NewModel("./path_to_onnx/model.onnx")
    if err != nil {
        log.Fatal(err)
    }

    var inputs map[string]*tensor.Tensor
    inputs = // However you construct inputs. It must have a tensor for all inputs.

    result, err := model.Run(inputs)
    if err != nil {
        log.Fatal(err)
    }
}

Tests

Most of the code should be tested. If you add operators (or an entire opset version) make sure you add unit tests as wel as tests for the ONNX test suite

The GONNX test suite consists of unit tests and integration tests, the standard provided by ONNX.

The ONNX test data is not stored in the repository, hence one needs to download it first:

make test_data

Now, one can run all tests using (which runs both integration and unit tests):

make test

Because the current implementation is lacking certain opset versions, some of the tests from ONNX will not run. All tests that are skipped can be found in ops_test.go, as well as the reason that particular test is skipped. We try to be explicit in which tests are ran and which are skipped.

How to Contribute

Any kind of contribution is welcome. Try to keep the style consistent and make sure all linter checks succeed before opening a pull request.

Pull requests

Our workflow is based on the github-flow .

1. Create a new issue.

2. Fork the project.

3. Clone your fork and add the upstream.

   git remote add upstream https://github.com/AdvancedClimateSystems/gonnx.git
   

4. Pull new changes from the upstream.

   git checkout main
   git fetch upstream
   git merge upstream/main
   

5. Create a feature branch

   git checkout -b <branch-name>
   

6. Commit your changes and reference the issue number in your comment.

   git commit -m "Issue #<issue-ref> : <your message>"
   

7. Push the feature branch to your remote repository.

   git push origin <branch-name>
   

8. Open new pull request.

Code of conduct

Welcome to the GONNX community! To make sure everyone has a blast while working together, here's our quick code of conduct:

1. Be respectful and kind to everyone. No hate speech or harassment allowed.
2. Keep conversations on topic and respectful.
3. Respect other people's work and intellectual property rights.
4. Follow the guidelines for contributing to the project and make your first pull request! Anything is welcome 🙂
5. If you see something, say something. Report any violations to the maintainers.
6. Have fun! We're all here to work on something awesome together, so let's make the most of it!

By participating in the GONNX project, you're agreeing to follow these guidelines and make sure everyone has a good time. Whether you're a seasoned veteran or a newcomer, we're excited to have you here. Let's make something amazing!

Authors

• @wipsel
• @swopper050
• @stensipma

Documentation

Index

• func ErrInvalidShape(expected onnx.Shape, actual []int) error
• func ErrModel(format string, a ...any) error
• func ModelProtoFromBytes(bytesModel []byte) (*onnx.ModelProto, error)
• type InvalidShapeError
  • func (i InvalidShapeError) Error() string
• type Model
  • func NewModel(mp *onnx.ModelProto) (*Model, error)
  • func NewModelFromBytes(bytesModel []byte) (*Model, error)
  • func NewModelFromFile(path string) (*Model, error)
  • func NewModelFromZipFile(file *zip.File) (*Model, error)
  • func (m *Model) InputDimSize(input string, i int) (int, error)
  • func (m *Model) InputNames() []string
  • func (m *Model) InputShapes() onnx.Shapes
  • func (m *Model) OutputNames() []string
  • func (m *Model) OutputShape(output string) onnx.Shape
  • func (m *Model) OutputShapes() onnx.Shapes
  • func (m *Model) ParamNames() []string
  • func (m *Model) Run(inputs Tensors) (Tensors, error)
• type OpGetter
  • func ResolveOperatorGetter(opsetID int64) (OpGetter, error)
• type Tensors

Functions

func ErrInvalidShape

func ErrInvalidShape(expected onnx.Shape, actual []int) error

func ErrModel

func ErrModel(format string, a ...any) error

ErrModel is used for when an error ocured during setup of running onnx models. The user can specify a formatted message using the standard formatting rules.

func ModelProtoFromBytes

func ModelProtoFromBytes(bytesModel []byte) (*onnx.ModelProto, error)

ModelProtoFromBytes creates an onnx.ModelProto based on a list of bytes.

Types

type InvalidShapeError

type InvalidShapeError struct {
	// contains filtered or unexported fields
}

func (InvalidShapeError) Error

func (i InvalidShapeError) Error() string

type Model

type Model struct {
	GetOperator OpGetter
	// contains filtered or unexported fields
}

Model defines a model that can be used for inference.

func NewModel

func NewModel(mp *onnx.ModelProto) (*Model, error)

NewModel creates a new model ready for inference given a path to an onnx file.

func NewModelFromBytes

func NewModelFromBytes(bytesModel []byte) (*Model, error)

NewModelFromBytes creates a new model from a list of bytes.

func NewModelFromFile

func NewModelFromFile(path string) (*Model, error)

NewModelFromFile creates a new model from a path to a file.

func NewModelFromZipFile

func NewModelFromZipFile(file *zip.File) (*Model, error)

NewModelFromZipFile creates a new model from a file in a zip archive.

func (*Model) InputDimSize

func (m *Model) InputDimSize(input string, i int) (int, error)

InputDimSize returns the size of the input dimension given an input tensor.

func (*Model) InputNames

func (m *Model) InputNames() []string

InputNames returns this models input names as defined by the model proto.

func (*Model) InputShapes

func (m *Model) InputShapes() onnx.Shapes

InputShapes returns the shapes for all input tensors.

func (*Model) OutputNames

func (m *Model) OutputNames() []string

OutputNames returns this models output names as defined by the model proto.

func (*Model) OutputShape

func (m *Model) OutputShape(output string) onnx.Shape

OutputShape returns the shape of a specific output tensors.

func (*Model) OutputShapes

func (m *Model) OutputShapes() onnx.Shapes

OutputShapes returns the shapes for all output tensors.

func (*Model) ParamNames

func (m *Model) ParamNames() []string

ParamNames returns this models parameter names as defined by the model proto.

func (*Model) Run

func (m *Model) Run(inputs Tensors) (Tensors, error)

Run builds and executes the computional graph of the network given the inputs.

type OpGetter

type OpGetter func(string) (ops.Operator, error)

OpGetter is a function that gets an operator based on a string.

func ResolveOperatorGetter

func ResolveOperatorGetter(opsetID int64) (OpGetter, error)

ResolveOperatorGetter resolves the getter for operators based on the opset version.

type Tensors

type Tensors map[string]tensor.Tensor

Tensors is a map with tensors.