onnxruntime-napi

简介

onnxruntime-napi 是 ONNX Runtime NAPI 接口库。本库基于 ONNX Runtime 原库进行适配，并沿用其现有用法和特性。 onnxruntime的主要功能代码都在native侧进行了实现，并提供给ArkTS侧使用。

下载安装

   ohpm install @ohos/onnxruntime

OpenHarmony ohpm环境配置等更多内容，请参考 如何安装OpenHarmony ohpm包 。

约束与限制

兼容性

在下述版本验证通过：

• DevEco Studio 6.0.1 Release, SDK: API12

编译运行

本项目依赖onnxruntime库, 需要将编译产物的.a文件和头文件拷贝至cpp目录下的thirdparty目录.

手动编译tpc_c_cplusplus onnxruntime c库

参考onnxruntime本地编译脚本
编译完成后, 将tpc_c_cplusplus/lycium/usr目录下的文件夹拷贝至cpp目录下的thirdparty目录.如下图所示:

使用prebuild.sh脚本编译(需要linux环境)

• 修改prebuild.sh脚本, 将SDK_DIR设置为SDK目录路径, 如: /home/OHOS_SDK/linux

• 执行prebuild.sh脚本:

./prebuild.sh

脚本将自行下载tpc_c_cplusplus库, 编译生成onnxruntime库, 并拷贝至cpp目录下的thirdparty目录. 如下图所示:

使用示例

下面以SIGMOID基准测试为例, 展示了onnxruntime napi库推理的主要过程:

• 初始化onnxruntime全局环境
• 加载模型
• 构建输入张量
• 执行推理
• 解析推理结果
• 资源释放

import * as api from '@ohos/onnxruntime';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  private context: Context = this.getUIContext().getHostContext()!;
  private filesDir: string = this.context.filesDir;
  private resourceDir: string = this.context.resourceDir;

  @State modelPath: string = this.resourceDir + '/sigmoid.ort';

  build() {
    Column() {
      Button("运行 ONNX Runtime 测试")
        .margin({ bottom: 10 })
        .onClick(() => {
          this.runOnnxRuntimeTest();
        })
    }
    .width('100%')
      .height('100%')
  }

  private runOnnxRuntimeTest(): void {
    try {
      // 1. 初始化环境并获取版本
      api.OnnxEnvironment.InitEnvironment();
      const version: string = api.OnnxEnvironment.GetVersion();
      console.info(`ONNX Runtime 版本: ${version}`);

      // 2. 创建推理会话
      const session: api.OnnxSession =
        api.OnnxEnvironment.CreateSessionFromModelFile(this.modelPath);
      const inputNames: string[] = session.GetInputNames();
      const outputNames: string[] = session.GetOutputNames();
      console.info(`输入节点: ${JSON.stringify(inputNames)}`);
      console.info(`输出节点: ${JSON.stringify(outputNames)}`);
    
      // 3. 准备输入数据
      const shape: number[] = [3, 4, 5];
      const totalElements: number = 60;
      const testdataBuffer: ArrayBuffer = new ArrayBuffer(totalElements * 4);
      const expectedBuffer: ArrayBuffer = new ArrayBuffer(totalElements * 4);
      const testdataView: Float32Array = new Float32Array(testdataBuffer);
      const expectedView: Float32Array = new Float32Array(expectedBuffer);
    
      let idx: number = 0;
      for (let i: number = 0; i < 3; i++) {
        for (let j: number = 0; j < 4; j++) {
          for (let k: number = 0; k < 5; k++) {
            const x: number = i + j + k;
            testdataView[idx] = x;
            expectedView[idx] = 1.0 / (1.0 + Math.exp(-x));
            idx++;
          }
        }
      }
    
      const inputTensor: api.OnnxTensor =
        new api.OnnxTensor(testdataBuffer, shape, api.OnnxArkTSType.FLOAT);
    
      const inputs: Record<string, api.OnnxValue> = {};
      inputs[inputNames[0]] = inputTensor;
    
      // 4. 执行推理
      const result: api.OnnxResult = session.Run(inputs);
      const value: api.OnnxValue = result.GetValueByName(outputNames[0]);
    
      // 5. 验证输出类型
      if (value.GetType() !== api.OnnxValueType.TENSOR) {
        console.error('输出类型错误，期望 TENSOR');
        return;
      }
    
      // 6. 精度验证
      const tensorValue: api.OnnxTensor = value as api.OnnxTensor;
      const buffer: ArrayBuffer = tensorValue.GetDataAsArrayBuffer();
      const bufferView: Float32Array = new Float32Array(buffer);
    
      if (bufferView.length !== expectedView.length) {
        console.error(`输出长度不匹配: 实际 ${bufferView.length}, 期望 ${expectedView.length}`);
        return;
      }
    
      let failCount: number = 0;
      const epsilon: number = 1e-6;
      for (let i: number = 0; i < bufferView.length; i++) {
        if (Math.abs(bufferView[i] - expectedView[i]) > epsilon) {
          failCount++;
        }
      }
    
      if (failCount === 0) {
        console.info('ONNX Runtime 测试通过，所有输出值均在误差范围内');
      } else {
        console.error(`精度验证失败: ${failCount} 个元素超出误差范围`);
      }
    
      // 7. 释放资源(推荐显式释放，避免内存占用过高)
      result.Close()
      inputTensor.Close()
      session.Close()
    } catch (err) {
      console.error(`ONNX Runtime 测试失败: ${err.message}`);
    }
  }
}

使用说明

onnxruntime一个完整的推理过程需要所有阶段参与, 但每个阶段可以有一些参数可以调整

初始化onnxruntime全局环境

在进行任何模型加载或推理操作之前，必须先初始化 ONNX Runtime 的全局环境。环境负责管理日志输出、全局线程池等共享资源。
注意: 全局环境仅需初始化一次.

最简单的初始化方式是不带任何参数:

    import * as api from '@ohos/onnxruntime';
    
    // 使用默认配置初始化环境
    api.OnnxEnvironment.InitEnvironment();
    const version = api.OnnxEnvironment.GetVersion();
    console.info(`ONNX Runtime 版本: ${version}`);

如果需要更精细的控制，可以使用以下重载方法：

• InitEnvironmentWithName(envName: string) – 指定环境名称，便于日志标识。
• InitEnvironmentWithLogLevel(logLevel: OnnxLoggingLevel) – 设置全局日志级别。
• InitEnvironmentWithNameAndLogLevel(envName: string, logLevel: OnnxLoggingLevel) – 同时指定名称与日志级别。
• InitEnvironmentFull(envName: string, logLevel: OnnxLoggingLevel, threadOptions: OnnxThreadOptions) – 完整初始化，可配置全局线程行为

线程配置（OnnxThreadOptions）允许设置跨算子并行数、算子内部并行数以及自旋控制策略，典型用法：

    const threadOptions = new api.OnnxThreadOptions();
    threadOptions.SetGlobalInterOpNumThreads(4);
    threadOptions.SetGlobalIntraOpNumThreads(2);
    threadOptions.SetGlobalSpinControl(true);
    threadOptions.SetGlobalDenormalAsZero();
    
    api.OnnxEnvironment.InitEnvironmentFull("MyApp", api.OnnxLoggingLevel.WARNING, threadOptions);
    threadOptions.Close(); // 配置完成后可关闭配置对象

日志级别枚举 OnnxLoggingLevel 包含 VERBOSE、INFO、WARNING、ERROR、FATAL，建议开发期使用 VERBOSE，发布时调整为 ERROR。

加载模型

环境初始化后，即可通过环境对象创建推理会话。OnnxEnvironment 提供了三种模型加载方式：

• 从文件加载 – 适用于模型以 .onnx 或 .ort 文件存储在设备上的场景。
• 从内存缓冲区加载 – 适用于模型文件打包在应用 rawfile 中，或从网络下载到内存的场景。
• 从数值数组加载 – 将模型字节转换为 number[] 后传入，内部自动转为 Int8Array。

每种方式都提供了基础版和带配置选项的版本（...WithOptions）。
基础加载示例：

    // 从文件加载
    const session = api.OnnxEnvironment.CreateSessionFromModelFile("/data/model.onnx");
    
    // 从内存缓冲区加载（假设 buffer 为 Int8Array）
    const session2 = api.OnnxEnvironment.CreateSessionFromBuffer(modelBuffer);

带会话选项加载：
OnnxSessionOptions 提供了丰富的配置项，用于控制模型优化、执行模式和线程数等。

    const options = new api.OnnxSessionOptions();
    options.SetOptimizationLevel(api.OnnxOptimizationLevel.ALL);      // 启用所有优化
    options.SetExecutionMode(api.OnnxExecutionMode.PARALLEL);         // 并行执行
    options.SetIntraOpNumThreads(2);                                  // 算子内线程数
    options.SetInterOpNumThreads(1);                                  // 算子间线程数
    options.SetMemoryPatternOptimizationEnabled(true);                // 内存模式优化
    options.EnableProfiling("profile_prefix");                        // 开启性能分析
    
    const session = api.OnnxEnvironment.CreateSessionFromModelFileWithOptions(
    "/data/model.onnx", options
    );
    options.Close();

OnnxOptimizationLevel 的可选值：

• DISABLED – 不优化
• BASIC – 基础优化（常量折叠等）
• EXTENDED – 扩展优化（算子融合等）
• LAYOUT – 布局优化
• ALL – 启用所有可用优化（推荐生产环境使用）

其它常用设置：

• SetCPUArenaAllocatorEnabled(true) – 启用 Arena 内存分配器，减少内存碎片。
• SetDeterministicComputeEnabled(true) – 强制确定性计算。
• AddCPUExecutionProvider(useArena) – 添加 CPU EP后端执行器；
• AddExecutionProvider - 注册其它硬件后端, 暂未有其它支持的EP后端, 此为保留的扩展接口
• SetSymbolicDimensionValue("batch_size", 1n) – 固定动态维度，例如 batch size。
• RegisterCustomOpLibrary(path) – 加载自定义算子动态库。

加载完成后可通过 session.GetModelMetadata() 查看模型的版本、生产者、描述等元信息。

构建输入张量

在执行推理之前，需要将应用数据封装为 OnnxValue 的子类对象。最常用的类型是 稠密张量 OnnxTensor。

获取输入信息
通过会话查询模型的输入名称、形状及数据类型，以便准备正确尺寸的缓冲区。

    const inputInfo = session.GetInputInfo(); // Record<string, NodeInfo>
    const firstInputName = Object.keys(inputInfo)[0];
    const nodeInfo = inputInfo[firstInputName];
    const tensorInfo = nodeInfo.GetInfo() as api.TensorInfo;
    const shape = tensorInfo.GetShape();          // 例如 [1, 3, 224, 224]
    const elementType = tensorInfo.arktsElementType; // 对应的 ArkTS 数据类型

创建张量：

• 数值张量 – 传入 ArrayBuffer、形状和 OnnxArkTSType 枚举值。

    const buffer = new ArrayBuffer(60 * 4);          // 假设 60 个 float
    const dataView = new Float32Array(buffer);
    // 填充 dataView ...
    const tensor = new api.OnnxTensor(buffer, [3, 4, 5], api.OnnxArkTSType.FLOAT);

OnnxArkTSType 定义了 FLOAT、DOUBLE、INT8、UINT8、INT16、INT32、INT64、BOOL、STRING 等，与 ArkTS 的 TypedArray 类型对应。

• 字符串张量 – 直接传入字符串数组与形状。

  const stringTensor = new api.OnnxTensor(["hello", "world"], [2]);

构建输入映射表，键为输入节点名称，值为张量对象：

    const inputs: Record<string, api.OnnxValue> = {};
    inputs[firstInputName] = tensor;

如果模型输入包含非张量类型（如 OnnxMap 或 OnnxSequence），也可以通过相应的构造函数创建，并将其放入映射表

执行推理

准备好输入后，调用会话的 Run 系列方法触发推理计算。

基础调用:

  const result: api.OnnxResult = session.Run(inputs);

返回的 OnnxResult 包含模型的所有输出。

高级调用：

• RunWithOptions(inputs, runOptions) – 传入 OnnxRunOptions，可覆盖本次运行的日志级别、添加配置项、绑定 LoRA 适配器等。
• RunWithSpecifiedOutputs(inputs, outputNames) – 仅计算指定的输出节点，减少不必要的计算。
• RunWithPinnedOutputs(inputs, pinnedOutputs) – 复用预先分配的缓冲区，降低内存分配开销。
• RunFull(...) – 所有参数可选，提供最大灵活度。

OnnxRunOptions 的使用示例：

    const runOpts = new api.OnnxRunOptions();
    runOpts.SetLogLevel(api.OnnxLoggingLevel.WARNING);
    runOpts.SetRunTag("inference_1");
    const result = session.RunWithOptions(inputs, runOpts);
    runOpts.Close();

指定输出示例（仅计算所需节点）：

    const outputNames = ["output_0"];
    const result = session.RunWithSpecifiedOutputs(inputs, outputNames);

LoRA 适配器推理：

    const adapter = new api.OnnxLoraAdapter("/path/to/adapter.onnx_adapter");
    const runOpts = new api.OnnxRunOptions();
    runOpts.AddActiveLoraAdapter(adapter);
    const result = session.RunWithOptions(inputs, runOpts);
    // 释放资源
    result.Close();
    runOpts.Close();
    adapter.Close();

如果开启了性能分析（在 OnnxSessionOptions 中启用），推理结束后可以通过 session.EndProfiling() 获取分析文件路径。

解析推理结果

OnnxResult 提供了按索引或按名称访问输出值的能力。大多数情况下，输出的类型为 OnnxTensor。

获取输出值:

    const outputNames = session.GetOutputNames();
    const value: api.OnnxValue = result.GetValueByName(outputNames[0]);
    
    // 类型检查
    if (value.GetType() !== api.OnnxValueType.TENSOR) {
      console.error('非张量输出');
    }
    const outputTensor = value as api.OnnxTensor;

读取张量数据:

• 数值数据：GetDataAsArrayBuffer() 返回原始数据缓冲区，用对应的 TypedArray 视图读取。
• 字符串数据：GetDataAsStringArray() 返回字符串数组。

    const outBuffer = outputTensor.GetDataAsArrayBuffer();
    const outData = new Float32Array(outBuffer); // 假设输出为 FLOAT 类型
    console.info(`输出前 5 个值: ${outData.slice(0, 5)}`);

其它输出类型:

• OnnxMap – 通过 GetStringKeys() / GetLongKeys() 和对应的值获取方法读取。
• OnnxSequence – 通过 GetTensors() 或 GetMaps() 获取元素数组。

资源释放

推理结果、张量以及会话在使用完毕后应及时调用 Close() 释放 Native 资源。虽然 ArkTS 对象在离开作用域时可能触发自动回收，但建议始终显式释放，尤其是处理大量数据或循环推理时。

    result.Close();
    inputTensor.Close();
    session.Close();

通过以上五个步骤，即可完成一次完整的 ONNX 模型推理流程。每个阶段都提供了灵活的配置接口，可以根据性能、精度和功能需求进行定制。

接口说明

onnxruntime 库主要提供以下核心类供应用开发者使用，覆盖环境管理、会话创建、张量构建、推理执行与结果解析等全流程。

枚举类型

枚举名称	说明	可选值
OnnxLoggingLevel	日志级别	VERBOSE，INFO，WARNING，ERROR，FATAL
OnnxExecutionMode	图执行模式	SEQUENTIAL（顺序），PARALLEL（并行）
OnnxOptimizationLevel	图优化等级	DISABLED，BASIC，EXTENDED，LAYOUT，ALL
OnnxValueType	ONNX 值类型分类	UNDEFINED，TENSOR，SEQUENCE，MAP，SPARSE_TENSOR
OnnxArkTSType	ArkTS 原生数据类型	FLOAT，DOUBLE，INT8，UINT8，INT16，INT32，INT64，BOOL，STRING，FLOAT16，BFLOAT16，UNKNOWN
OnnxTensorType	ONNX 张量元素类型	与 OnnxArkTSType 类似但包含更多数值类型，如 COMPLEX64 等
OnnxMapValueType	Map 键值的数据类型	INVALID，STRING，LONG，FLOAT，DOUBLE
SparseTensorFormat	稀疏张量存储格式	UNDEFINED，COO，CSRC，BLOCK_SPARSE

OnnxRuntime(全局运行时信息)

接口	说明	参数	返回值
Version()	获取 ONNX Runtime 版本字符串	无	string，例如 "1.16.0"
IsCUDAAvailable()	是否支持 CUDA GPU 后端	无	boolean
IsROCMAvailable()	是否支持 ROCm AMD GPU 后端	无	boolean
IsDNNLAvailable()	是否支持 oneDNN 后端	无	boolean
IsOpenVINOAvailable()	是否支持 OpenVINO 后端	无	boolean
IsTensorRTAvailable()	是否支持 TensorRT 后端	无	boolean
IsQNNAvailable()	是否支持 QNN 高通后端	无	boolean

OnnxThreadOptions（全局线程池配置）

接口	说明	参数	返回值
构造函数 OnnxThreadOptions()	创建线程配置对象	无	OnnxThreadOptions
Close()	释放底层资源	无	无
SetGlobalInterOpNumThreads(numThreads)	设置跨算子并行线程数	numThreads: number，建议设为物理核心数	无
SetGlobalIntraOpNumThreads(numThreads)	设置算子内部并行线程数	numThreads: number	无
SetGlobalSpinControl(enable)	设置自旋等待策略	enable: boolean	无
SetGlobalDenormalAsZero()	将非规格化浮点数置零	无	无

OnnxEnvironment（环境管理）

注意：全局环境仅需初始化一次，之后可通过该对象创建会话。

接口	说明	参数	返回值
InitEnvironment()	默认初始化环境	无	无
InitEnvironmentWithName(envName)	使用自定义名称初始化	envName: string	无
InitEnvironmentWithLogLevel(logLevel)	使用指定日志级别初始化	logLevel: OnnxLoggingLevel	无
InitEnvironmentWithNameAndLogLevel(envName, logLevel)	同时指定名称与日志级别	envName: string，logLevel: OnnxLoggingLevel	无
InitEnvironmentFull(envName, logLevel, threadOptions)	完整参数初始化	envName: string，logLevel: OnnxLoggingLevel，threadOptions: OnnxThreadOptions	无
CreateSessionFromModelFile(modelPath)	从模型文件创建推理会话	modelPath: string，模型文件路径	OnnxSession
CreateSessionFromModelFileWithOptions(modelPath, sessionOptions)	从模型文件创建会话（带配置）	modelPath: string，sessionOptions: OnnxSessionOptions	OnnxSession
CreateSessionFromBuffer(modelBuffer)	从内存缓冲区创建会话	modelBuffer: Int8Array	OnnxSession
CreateSessionFromBufferWithOptions(modelBuffer, sessionOptions)	从缓冲区创建会话（带配置）	modelBuffer: Int8Array，sessionOptions: OnnxSessionOptions	OnnxSession
CreateSessionFromArray(modelData)	从数值数组创建会话	modelData: number[]	OnnxSession
CreateSessionFromArrayWithOptions(modelData, sessionOptions)	从数组创建会话（带配置）	modelData: number[]，sessionOptions: OnnxSessionOptions	OnnxSession
SetTelemetryEnabled(enable)	启用/禁用遥测收集	enable: boolean	无
GetVersion()	获取 ONNX Runtime 版本	无	string
ToString()	获取环境配置字符串（调试）	无	string

OnnxSessionOptions（会话配置）

接口	说明	参数	返回值
构造函数 OnnxSessionOptions()	创建会话选项对象	无	OnnxSessionOptions
Close()	释放资源	无	无
IsClosed()	是否已关闭	无	boolean
SetExecutionMode(mode)	设置图执行模式	mode: OnnxExecutionMode	无
SetOptimizationLevel(level)	设置优化等级	level: OnnxOptimizationLevel	无
SetIntraOpNumThreads(numThreads)	设置算子内线程数	numThreads: number，-1 表示默认	无
SetInterOpNumThreads(numThreads)	设置跨算子线程数	numThreads: number	无
SetOptimizedModelFilePath(filePath)	设置优化后模型的保存路径	filePath: string	无
SetLoggerId(loggerId)	设置日志标识	loggerId: string	无
SetSessionLogLevel(logLevel)	设置会话日志级别	logLevel: OnnxLoggingLevel	无
SetSessionLogVerbosityLevel(verbosityLevel)	设置日志详细程度	verbosityLevel: number	无
EnableProfiling(filePrefix)	启用性能分析	filePrefix: string，输出文件前缀	无
DisableProfiling()	禁用性能分析	无	无
SetMemoryPatternOptimizationEnabled(enable)	启用内存模式优化	enable: boolean	无
SetCPUArenaAllocatorEnabled(useArena)	启用 Arena 内存分配器	useArena: boolean	无
SetDeterministicComputeEnabled(enable)	启用确定性计算	enable: boolean	无
DisablePerSessionThreads()	禁用每会话线程，使用全局线程池	无	无
RegisterCustomOpLibrary(libraryPath)	注册自定义算子库	libraryPath: string，.so 文件路径	无
RegisterCustomOpsUsingFunction(functionName)	通过函数名注册自定义算子	functionName: string	无
AddInitializer(tensorName, tensorValue)	添加/覆盖初始化器	tensorName: string，tensorValue: OnnxValue	无
AddExternalInitializers(initializers)	批量添加外部初始化器	initializers: Record<string, OnnxValue>	无
SetSymbolicDimensionValue(dimensionName, dimensionValue)	固定动态维度值	dimensionName: string，dimensionValue: bigint	无
AddConfigEntry(key, value)	添加自定义配置项	key: string，value: string	无
GetConfigEntries()	获取所有配置项	无	Record<string, string>
AddCPUExecutionProvider(useArena)	添加 CPU 执行提供程序	useArena: boolean	无
AddExecutionProvider(providerName, providerOptions)	添加硬件执行提供程序	providerName: string，providerOptions: Record<string, string>	无

OnnxRunOptions（运行配置）

接口	说明	参数	返回值
构造函数 OnnxRunOptions()	创建运行选项对象	无	OnnxRunOptions
Close()	释放资源	无	无
IsClosed()	是否已关闭	无	boolean
SetLogLevel(logLevel)	设置本次运行日志级别	logLevel: OnnxLoggingLevel	无
SetLogVerbosityLevel(verbosityLevel)	设置日志详细程度	verbosityLevel: number	无
GetLogLevel()	获取日志级别	无	OnnxLoggingLevel
GetLogVerbosityLevel()	获取日志详细程度	无	number
SetRunTag(tag)	设置运行标签	tag: string	无
GetRunTag()	获取运行标签	无	string
AddConfigEntry(key, value)	添加运行专属配置	key: string，value: string	无
GetConfigEntry(key)	获取配置值	key: string	string
AddActiveLoraAdapter(adapter)	添加激活的 LoRA 适配器	adapter: OnnxLoraAdapter	无

OnnxLoraAdapter（LoRA 适配器）

接口	说明	参数	返回值
构造函数 OnnxLoraAdapter(loraFilePath)	从文件路径创建适配器	loraFilePath: string	OnnxLoraAdapter
构造函数 OnnxLoraAdapter(loraData)	从 Int8Array 创建适配器	loraData: Int8Array	OnnxLoraAdapter
构造函数 OnnxLoraAdapter(loraData)	从 number[] 创建适配器	loraData: number[]	OnnxLoraAdapter
Close()	释放适配器资源	无	无

OnnxSession（推理会话）

接口	说明	参数	返回值
GetInputCount()	获取模型输入数量	无	number
GetOutputCount()	获取模型输出数量	无	number
GetInputNames()	获取所有输入名称数组	无	string[]
GetOutputNames()	获取所有输出名称数组	无	string[]
GetInputInfo()	获取输入节点详细信息	无	Record<string, NodeInfo>
GetOutputInfo()	获取输出节点详细信息	无	Record<string, NodeInfo>
Run(inputMap)	执行推理，返回所有输出	inputMap: Record<string, OnnxValue>	OnnxResult
RunWithOptions(inputMap, runOptions)	带运行选项的推理	inputMap: Record<string, OnnxValue>，runOptions: OnnxRunOptions	OnnxResult
RunWithSpecifiedOutputs(inputMap, outputNames)	仅计算指定输出	inputMap: Record<string, OnnxValue>，outputNames: string[]	OnnxResult
RunWithSpecifiedOutputsAndOptions(inputMap, outputNames, runOptions)	指定输出并带运行选项	inputMap，outputNames: string[]，runOptions: OnnxRunOptions	OnnxResult
RunWithPinnedOutputs(inputMap, pinnedOutputs)	输出复用缓冲区	inputMap，pinnedOutputs: Record<string, OnnxValue>	OnnxResult
RunWithSpecifiedOutputsAndPinnedOutputs(...)	指定输出 + 输出复用	inputMap，outputNames: string[]，pinnedOutputs: Record<string, OnnxValue>	OnnxResult
RunFull(inputMap, outputNames, pinnedOutputs, runOptions)	全参数推理接口	全部可选，具体见声明	OnnxResult
GetModelMetadata()	获取模型元数据	无	OnnxModelMetadata
GetProfilingStartTimeNs()	性能分析起始时间戳（纳秒）	无	bigint
EndProfiling()	结束性能分析并返回结果文件路径	无	string
Close()	释放会话资源	无	无
IsClosed()	检查会话是否已关闭	无	boolean

OnnxResult（推理结果）

接口	说明	参数	返回值
Close()	释放结果资源	无	无
IsClosed()	是否已关闭	无	boolean
GetOutputCount()	输出值的数量	无	number
GetValueByIndex(index)	按索引获取输出值	index: number	OnnxValue
GetValueByName(name)	按名称获取输出值	name: string	OnnxValue
IsResultOwner(index)	指定索引的输出是否由结果对象拥有	index: number	boolean

OnnxModelMetadata（模型元数据）

接口	说明	参数	返回值
GetProducerName()	模型生产者名称	无	string
GetGraphName()	计算图名称	无	string
GetGraphDescription()	计算图描述	无	string
GetDomain()	模型域	无	string
GetDescription()	模型文档描述	无	string
GetVersion()	模型版本号	无	bigint
GetCustomMetadataMap()	自定义元数据映射	无	Record<string, string>
GetCustomMetadata(key)	获取特定自定义元数据	key: string	string
ToString()	字符串表示	无	string
HashCode()	元数据哈希值	无	number

NodeInfo / TensorInfo / MapInfo / SequenceInfo（节点信息与类型信息）

类	接口	说明	参数	返回值
NodeInfo	GetName()	获取节点名称	无	string
	GetInfo()	获取值类型信息	无	ValueInfo（通常为 TensorInfo / MapInfo / SequenceInfo）
	ToString()	字符串表示	无	string
TensorInfo	构造函数	创建张量信息	多种重载：shape: number[]，elementType/onnxTensorType 等	TensorInfo
	GetShape()	获取张量形状	无	number[]
	GetDimensionNames()	获取维度名称	无	string[]
	GetElementCount()	获取元素总数	无	number
	IsScalar()	是否为标量	无	boolean
	CreateDataCarrier()	创建承载此类型数据的 ArrayBuffer	无	ArrayBuffer
	onnxTensorType（只读）	ONNX 张量类型	无	OnnxTensorType
	arktsElementType（只读）	对应的 ArkTS 数据类型	无	OnnxArkTSType
MapInfo	构造函数	创建映射信息	size, keyType, valueType 等	MapInfo
	elementCount（只读）	元素数量	无	number
	keyType（只读）	键类型	无	OnnxArkTSType
	valueType（只读）	值类型	无	OnnxArkTSType
SequenceInfo	构造函数	创建序列信息	length, elementType 等	SequenceInfo
	length（只读）	序列长度	无	number
	isMapSequence（只读）	是否为 Map 序列	无	boolean
	elementType（只读）	元素类型	无	OnnxArkTSType
	mapInfo（只读）	映射信息（若为 Map 序列）	无	MapInfo

OnnxValue 及其子类（稠密张量、稀疏张量、序列、映射）

OnnxValue（基类）

接口	说明	参数	返回值
GetType()	获取值类型分类	无	OnnxValueType
Close()	释放值资源	无	无
IsClosed()	是否已关闭	无	boolean

OnnxTensor（稠密张量）

接口	说明	参数	返回值
构造函数	从 ArrayBuffer 创建	dataBuffer: ArrayBuffer，shape: number[]，elementType: OnnxArkTSType	OnnxTensor
构造函数	从字符串数组创建	stringValues: string[]，shape: number[]	OnnxTensor
GetType()	固定返回 TENSOR	无	OnnxValueType.TENSOR
Close()	释放值资源	无	无
IsClosed()	是否已关闭	无	bool
GetInfo()	获取张量信息	无	TensorInfo
ToString()	字符串表示	无	string
GetDataAsArrayBuffer()	获取底层数据缓冲区	无	ArrayBuffer
GetDataAsStringArray()	获取字符串数据（仅 STRING 类型）	无	string[]

OnnxMap（映射类型）

接口	说明	参数	返回值
GetType()	返回 MAP	无	OnnxValueType.MAP
GetElementCount()	元素数量	无	number
GetInfo()	映射信息	无	MapInfo
GetKeyTypeCategory()	键的类型分类	无	OnnxMapValueType
GetValueTypeCategory()	值的类型分类	无	OnnxValueType
GetStringKeys()	获取字符串键数组	无	string[]
GetLongKeys()	获取长整型键数组	无	bigint[]
GetStringValues()	获取字符串值数组	无	string[]
GetLongValues()	获取长整型值数组	无	bigint[]
GetFloatValues()	获取浮点值数组	无	number[]
GetDoubleValues()	获取双精度值数组	无	number[]

OnnxSequence（序列类型）

接口	说明	参数	返回值
GetType()	返回 SEQUENCE	无	OnnxValueType.SEQUENCE
GetMaps()	获取 Map 元素数组（元素为 Map 时）	无	OnnxMap[]
GetTensors()	获取 Tensor 元素数组（元素为 Tensor 时）	无	OnnxTensor[]
GetInfo()	序列信息	无	SequenceInfo

稀疏张量相关（SparseTensor 抽象类及 COO/CSRC/BlockSparseTensor）

类	接口	说明	参数	返回值
SparseTensor（抽象）	GetSparseFormat()	获取格式	无	SparseTensorFormat
	GetNonZeroElementCount()	非零元素数量	无	number
	GetDenseShape()	稠密形状	无	number[]
	GetIndicesType()	索引数据类型	无	OnnxArkTSType
	GetIndicesShape()	索引形状	无	number[]
	GetIndicesBuffer()	索引数据缓冲区	无	ArrayBuffer
	GetValuesType()	值数据类型	无	OnnxArkTSType
	GetValuesShape()	值形状	无	number[]
	GetValuesBuffer()	值数据缓冲区	无	ArrayBuffer
COOTensor	构造函数	创建 COO 稀疏张量	indices: BigInt64Array，indicesShape: number[]，values: ArrayBuffer，denseShape: number[]，elementType: OnnxArkTSType，numNonZeroElements: number	COOTensor
CSRCTensor	构造函数	创建 CSR/CSC 稀疏张量	outerIndices: BigInt64Array，innerIndices: BigInt64Array，values: ArrayBuffer，denseShape: number[]，elementType: OnnxArkTSType，numNonZeroElements: number	CSRCTensor
	GetInnerIndicesShape()	内部索引形状	无	number[]
	GetInnerIndicesBuffer()	内部索引缓冲区	无	ArrayBuffer
BlockSparseTensor	构造函数	创建分块稀疏张量	blockIndices: Int32Array，indicesShape: number[]，values: ArrayBuffer，valuesShape: number[]，denseShape: number[]，elementType: OnnxArkTSType，numNonZeroElements: number	BlockSparseTensor
OnnxSparseTensor	构造函数 OnnxSparseTensor(sparseTensor)	包装稀疏张量为OnnxValue	COO / CSRC / BlockSparseTensor 实例	OnnxSparseTensor
	GetType()	获取值类型分类（固定返回 SPARSE_TENSOR）	无	OnnxValueType.SPARSE_TENSOR
	Close()	释放底层资源	无	无
	IsClosed()	是否已关闭	无	boolean
	GetInfo()	获取对应稠密张量的类型信息	无	TensorInfo
	ToString()	获取对象的字符串表示（调试用）	无	string
	GetSparseFormat()	获取稀疏存储格式	无	SparseTensorFormat
	GetIndicesBuffer()	获取外层索引数据缓冲区（COO 坐标、CSRC 行指针、Block 块索引）	无	ArrayBuffer
	GetInnerIndicesBuffer()	获取内层索引数据缓冲区（仅 CSRC 格式有效，列/行索引）	无	ArrayBuffer
	GetValuesBuffer()	获取非零元素值数据缓冲区	无	ArrayBuffer
	GetIndicesShape()	获取外层索引数组的形状	无	number[]
	GetInnerIndicesShape()	获取内层索引数组的形状（仅 CSRC 有效）	无	number[]
	GetValuesShape()	获取非零元素值数组的形状	无	number[]

以上涵盖了 onnxruntime 库对外开放的主要类和方法。更多类型细节可参考 Index.d.ts 源码。

项目结构

|---- ohos_onnxruntime
|     |---- entry  # 示例代码文件夹
|     |---- library  # onnxruntime 库文件夹
|     |     |---- src
|     |     |     └── main  
|     |     |         |---- cpp  # C++ Native 代码
|     |     |                |---- napi        # onnxruntime napi 代码
|     |     |                |---- thirdparty  # onnxruntime 编译产物存放目录
|     |     |                |---- types
|     |     |                |       |---- libonnxruntime_napi/Index.d.ts  # 接口定义
|     |     |                └──   CMakeLists.txt
|     |     |---- Index.ets  # 对外接口
|     |---- README.md  # 英文说明
|     |---- README_zh.md  # 中文说明

贡献代码

使用过程中发现任何问题都可以提 Issue ，当然，也非常欢迎发 PR 共建。

开源协议

本项目基于 MIT License ，请自由地享受和参与开源。