ort

README

基于 purego 实现的无 CGO 纯 Go 项目，通过 purego 直接绑定并调用 onnxruntime 原生库接口，无需依赖 CGO 编译环境， 即可实现 ONNX 模型的加载与推理计算，基于 onnxruntime 1.24.1 的头文件实现。

安装

下载 onnxruntime 1.24 动态链接库，安装 onnxruntime_purego 库，版本对应关系：

onnxruntime	onnxruntime_purego
1.24	v1.24.0
1.23	v1.23.0

# 下载最新版本
go get -u github.com/cnxxy-cn/onnxruntime_purego

# 针对 onnxruntime 1.24 下载特定版本 purego
go get -u github.com/cnxxy-cn/onnxruntime_purego@v1.24

快速开始

package main

import (
	ort "github.com/cnxxy-cn/onnxruntime_purego"
	"log"
)

const testModelPath = "./testdata/yolo11n.onnx"

func main() {
	engine, _ := ort.NewEngine(ort.DefaultLibraryPath())
	defer engine.Destroy()
	session, err := engine.NewSession(testModelPath, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer session.Destroy()

	inputData := make([]float32, 3*640*640)
	inputValue, err := engine.NewTensor([]int64{1, 3, 640, 640}, inputData)
	if err != nil {
		log.Fatal(err)
	}
	defer inputValue.Destroy()

	inputs := map[string]*ort.Value{
		"images": inputValue,
	}

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

	for name, output := range outputs {
		outputData, err := ort.GetTensorData[float32](output)
		if err != nil {
			log.Fatal(err)
		}
		log.Printf("%v: %+v", name, outputData[:min(len(outputData), 20)])
	}
}

案例

YOLOv11 目标检测

原图	Mask图

Documentation

Index

• Constants
• func DefaultLibraryPath() string
• func GetTensorData[T gotool.Number](v *Value) ([]T, error)
• type AllocatorHandle
• type AllocatorType
• type ApiVersion
• type CUDAProviderOptionsV2Handle
• type Engine
  • func NewEngine(libPath string) (*Engine, error)
  • func (e *Engine) Destroy()
  • func (e *Engine) GetVersion() string
  • func (e *Engine) NewSession(modelPath string, opts *SessionOptions) (*Session, error)
  • func (e *Engine) NewSessionOptions() (*SessionOptions, error)
• type EnvHandle
• type ErrorCode
• type LoggingLevel
• type MemType
• type MemoryInfoHandle
• type OnnxType
• type OpenVINOOptions
• type RunOptionsHandle
• type Session
  • func (s *Session) Destroy()
  • func (s *Session) Run(inputs map[string]*Value) (map[string]*Value, error)
• type SessionHandle
• type SessionOptions
  • func (o *SessionOptions) Destroy()
  • func (o *SessionOptions) EnableCUDA() error
  • func (o *SessionOptions) EnableOpenVINO(opts OpenVINOOptions) error
  • func (o *SessionOptions) SetCpuMemArena(useArena bool) error
  • func (o *SessionOptions) SetIntraOpNumThreads(num int32) error
• type SessionOptionsHandle
• type StatusHandle
• type TensorElementDataType
• type TensorTypeAndShapeInfoHandle
• type TypeInfoHandle
• type Value
  • func NewTensor(shape []int64, data any) (*Value, error)
  • func (v *Value) Destroy()
  • func (v *Value) GetElementCount() (int, error)
  • func (v *Value) GetShape() ([]int64, error)
• type ValueHandle

Constants

const (
	DeviceAllocator AllocatorType = 0
	ArenaAllocator  AllocatorType = 1

	DefaultMemType MemType = 0
)

const (
	ApiVersion23 ApiVersion = 23

	LogVerbose LoggingLevel = 0
	LogInfo    LoggingLevel = 1
	LogWarning LoggingLevel = 2
	LogError   LoggingLevel = 3
	LogFatal   LoggingLevel = 4

	DefaultEnvName = "GETCHARZP"
)

Functions

func DefaultLibraryPath

func DefaultLibraryPath() string

DefaultLibraryPath 默认动态库路径, 例如：

Return:

Windows: ./lib/onnxruntime.dll
Linux amd64: ./lib/onnxruntime_amd64.so
Linux arm64: ./lib/onnxruntime_arm64.so
Mac amd64: ./lib/onnxruntime_amd64.dylib
Mac arm64: ./lib/onnxruntime_arm64.dylib

func GetTensorData

func GetTensorData[T gotool.Number](v *Value) ([]T, error)

GetTensorData 获取 Tensor 数据

Types

type AllocatorHandle

type AllocatorHandle uintptr

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type AllocatorType

type AllocatorType int32

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type ApiVersion

type ApiVersion uint32

type CUDAProviderOptionsV2Handle

type CUDAProviderOptionsV2Handle uintptr

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type Engine

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

Engine 推理引擎上下文

func NewEngine

func NewEngine(libPath string) (*Engine, error)

NewEngine 初始化引擎

func (*Engine) Destroy

func (e *Engine) Destroy()

Destroy 释放资源

func (*Engine) GetVersion

func (e *Engine) GetVersion() string

GetVersion 获取版本字符串，例如：1.23.2

func (*Engine) NewSession

func (e *Engine) NewSession(modelPath string, opts *SessionOptions) (*Session, error)

NewSession 创建会话

Params:

modelPath: 模型路径
opts: Session 配置项

func (*Engine) NewSessionOptions

func (e *Engine) NewSessionOptions() (*SessionOptions, error)

type EnvHandle

type EnvHandle uintptr

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type ErrorCode

type ErrorCode int32

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type LoggingLevel

type LoggingLevel int32

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type MemType

type MemType int32

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type MemoryInfoHandle

type MemoryInfoHandle uintptr

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type OnnxType

type OnnxType int32

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type OpenVINOOptions

type OpenVINOOptions struct {
	DeviceType             string
	Precision              string
	NumThreads             int
	NumStreams             int
	CacheDir               string
	LoadConfig             string
	ContextHandle          uintptr
	EnableOpenCLThrottling bool
	EnableQDQOptimizer     bool
	DisableDynamicShapes   bool
}

OpenVINOOptions OpenVINO Execution Provider 配置

字段说明

DeviceType:  "CPU" / "GPU" / "GPU.0" / "GPU.1" / "AUTO" / "HETERO:GPU,CPU" / "MULTI:GPU,CPU"
             默认 "CPU"
Precision:   "FP32" / "FP16" / "ACCURACY"
             N5105 等 Intel iGPU 跑 FP16 模型时设 "FP16" 收益最大；ACCURACY 表示按模型原始精度
NumThreads:  CPU device 时的线程数；GPU 上无意义，留 0 即可
NumStreams:  并发推理流数；N5105 这类小核显建议 1，避免 GPU hang
CacheDir:    OpenVINO 把 ONNX 编译成 IR + JIT 后会写到这个目录；
             下次启动同模型直接复用，能节省十几秒首启时间，强烈建议设置
LoadConfig:  额外的 properties JSON 文件路径，留空即可
ContextHandle: 传入预先创建的 OpenCL/L0 context (高级用法)，留空即可
EnableOpenCLThrottling: 老 iGPU 上能改善多任务调度，N5105 上保持 false
EnableQDQOptimizer: INT8 模型可启用，FP16 / FP32 模型置 false
DisableDynamicShapes: 输入尺寸完全固定时设 true 可加速首次编译

type RunOptionsHandle

type RunOptionsHandle uintptr

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type Session

type Session struct {
	InputNames  []string
	OutputNames []string
	// contains filtered or unexported fields
}

func (*Session) Destroy

func (s *Session) Destroy()

func (*Session) Run

func (s *Session) Run(inputs map[string]*Value) (map[string]*Value, error)

Run 执行推理

type SessionHandle

type SessionHandle uintptr

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type SessionOptions

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

func (*SessionOptions) Destroy

func (o *SessionOptions) Destroy()

func (*SessionOptions) EnableCUDA

func (o *SessionOptions) EnableCUDA() error

EnableCUDA 启用 CUDA

func (*SessionOptions) EnableOpenVINO

func (o *SessionOptions) EnableOpenVINO(opts OpenVINOOptions) error

EnableOpenVINO 启用 OpenVINO Execution Provider

必备前置条件

1. onnxruntime.so 必须是带 OpenVINO EP 编译的版本 （比如从 pip 包 onnxruntime-openvino 抠出来的 libonnxruntime.so.*）
2. 同目录下需要有 libonnxruntime_providers_openvino.so / libopenvino*.so / plugins.xml
3. 系统上需要安装 Intel compute-runtime（OpenCL ICD + Level Zero backend） N5105 等 Gen11 硬件用 NEO 24.35.x（intel-opencl-icd / intel-level-zero-gpu）

典型用法

opts.EnableOpenVINO(ort.OpenVINOOptions{
    DeviceType: "GPU",
    Precision:  "FP16",
    NumStreams: 1,
    CacheDir:   "/var/cache/ov",
})

失败时建议 fallback 到 CPU，不要 fatal——用户机器上没装 Intel 驱动时还能跑。

func (*SessionOptions) SetCpuMemArena

func (o *SessionOptions) SetCpuMemArena(useArena bool) error

SetCpuMemArena 设置内存池策略

false: 禁用内存池，推理速度稍慢，但 Destroy 后立即归还内存给 OS ，解决内存滞留问题
true: 启用内存池，推理速度最快，但 Destroy 后内存会被缓存以供复用（默认）

func (*SessionOptions) SetIntraOpNumThreads

func (o *SessionOptions) SetIntraOpNumThreads(num int32) error

SetIntraOpNumThreads 设置线程数

type SessionOptionsHandle

type SessionOptionsHandle uintptr

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type StatusHandle

type StatusHandle uintptr

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type TensorElementDataType

type TensorElementDataType int32

OrtStatus is an opaque pointer to an ONNX Runtime status object.

const (
	TensorElementDataTypeUndefined      TensorElementDataType = 0
	TensorElementDataTypeFloat          TensorElementDataType = 1
	TensorElementDataTypeUint8          TensorElementDataType = 2
	TensorElementDataTypeInt8           TensorElementDataType = 3
	TensorElementDataTypeUint16         TensorElementDataType = 4
	TensorElementDataTypeInt16          TensorElementDataType = 5
	TensorElementDataTypeInt32          TensorElementDataType = 6
	TensorElementDataTypeInt64          TensorElementDataType = 7
	TensorElementDataTypeString         TensorElementDataType = 8
	TensorElementDataTypeBool           TensorElementDataType = 9
	TensorElementDataTypeFloat16        TensorElementDataType = 10
	TensorElementDataTypeDouble         TensorElementDataType = 11
	TensorElementDataTypeUint32         TensorElementDataType = 12
	TensorElementDataTypeUint64         TensorElementDataType = 13
	TensorElementDataTypeComplex64      TensorElementDataType = 14
	TensorElementDataTypeComplex128     TensorElementDataType = 15
	TensorElementDataTypeBFloat16       TensorElementDataType = 16
	TensorElementDataTypeFloat8E4M3FN   TensorElementDataType = 17
	TensorElementDataTypeFloat8E4M3FNUZ TensorElementDataType = 18
	TensorElementDataTypeFloat8E5M2     TensorElementDataType = 19
	TensorElementDataTypeFloat8E5M2FNUZ TensorElementDataType = 20
	TensorElementDataTypeUint4          TensorElementDataType = 21
	TensorElementDataTypeInt4           TensorElementDataType = 22
	TensorElementDataTypeFloat4E2M1     TensorElementDataType = 23
)

type TensorTypeAndShapeInfoHandle

type TensorTypeAndShapeInfoHandle uintptr

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type TypeInfoHandle

type TypeInfoHandle uintptr

OrtStatus is an opaque pointer to an ONNX Runtime status object.

type Value

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

func NewTensor

func NewTensor(shape []int64, data any) (*Value, error)

NewTensor 初始化 Tensor

Params:

shape: 形状
data: 数据

func (*Value) Destroy

func (v *Value) Destroy()

func (*Value) GetElementCount

func (v *Value) GetElementCount() (int, error)

GetElementCount 获取 Tensor 中的元素总数

func (*Value) GetShape

func (v *Value) GetShape() ([]int64, error)

GetShape 获取 Tensor 的维度信息

type ValueHandle

type ValueHandle uintptr

OrtStatus is an opaque pointer to an ONNX Runtime status object.