ONNX Runtime JavaScript API 统一抽象层：onnxruntime-common 包全面解读

ONNX Runtime JavaScript API 统一抽象层onnxruntime-common 包全面解读【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntimeONNX Runtime JavaScript API即 NPM 包onnxruntime-common是 ONNX Runtime 面向所有 JavaScript 平台场景的统一 API 定义层也是onnxruntime-node、onnxruntime-web、onnxruntime-react-native三个平台包的公共依赖。本文将基于仓库中的 js/common/README.md 及其源码深入剖析该包的设计定位、模块结构与核心 API帮助你理解 ONNX Runtime JS 生态的统一入口是如何组织的以及各平台包如何共享同一套 TypeScript 类型与接口。一、包定位统一 API而非直接使用根据 js/common/README.md 的说明ONNX Runtime JavaScript API 是一个面向所有 JavaScript 使用场景的统一 API它是以下三个 NPM 包的依赖onnxruntime-node面向 Node.js 原生绑定的推理运行时onnxruntime-web面向浏览器/Web 场景的 WebAssembly 与 WebGPU 推理运行时onnxruntime-react-native面向 React Native 移动端场景的推理运行时。仓库中的依赖声明印证了这一关系在 js/node/package.json 中声明了onnxruntime-common: file:../commonjs/react_native/package.json 同样以本地文件方式依赖onnxruntime-commononnxruntime-web也遵循相同模式。三个平台包通过各自的后端实现为onnxruntime-common定义的统一接口提供具体执行能力。该包在官方文档中被明确标注为不设计为直接使用用户应当根据目标平台选择安装上述三个平台包之一。这一点从 js/common/lib/index.ts 的包注释中也可确认——它同时列出了三个平台包的入口表明onnxruntime-common是它们共用的契约层。二、包结构与构建产物2.1 package.json 关键信息从 js/common/package.json 可以看到该包的核心元数据包名onnxruntime-common当前仓库版本为1.30.0许可证MIT模块类型type: module采用 ESM 规范双入口导出main:dist/cjs/index.jsCommonJS 入口exports.require:./dist/cjs/index.jsrequire()使用exports.import:./dist/esm/index.jsimport使用。构建脚本build:cjs: 以 CommonJS 模块编译到dist/cjsbuild:esm: 以 ESM 编译build:bundles: 通过 webpack 打包prepare: 发布前自动执行npm run buildtest: 使用 mocha 运行测试并支持test:f16在js-float16array环境下测试 float16 支持。也就是说同一个源码通过 TypeScript 编译出 CJS 与 ESM 两套产物同时兼容传统require与现代import两种消费方式这也是它能成为所有 JS 平台包公共基础的前提。2.2 源码目录结构js/common/lib目录下的 TypeScript 源码构成了统一 API 的全部内容主要文件包括index.ts —— 包入口统一导出全部公共 APIinference-session.ts —— 推理会话Session接口与工厂tensor.ts —— 张量类型与构造器tensor-factory.ts / tensor-conversion.ts —— 张量工厂与转换工具env.ts / env-impl.ts —— 全局环境配置backend.ts / backend-impl.ts —— 后端注册机制onnx-model.ts、onnx-value.ts —— 模型选项与值类型trace.ts、type-helper.ts、version.ts —— 辅助模块。从 index.ts 的导出语句可以看出统一 API 的核心对外能力集中在五个方面推理会话InferenceSession、全局环境env、张量Tensor、后端注册registerBackend以及ONNX 模型/值类型。下面逐一展开。三、核心 API 之一InferenceSession 推理会话InferenceSession是使用 ONNX Runtime 做推理的入口对象在 inference-session.ts 中被定义为代表一个 ONNX 模型的运行时实例。3.1 创建会话create() 的多种重载InferenceSession.create()是工厂方法从类型签名可以看到它支持多种模型来源从 URI/文件路径加载create(uri: string, options?)从 ArrayBuffer 加载create(buffer: ArrayBufferLike, options?)从 ArrayBuffer 的片段加载create(buffer, byteOffset, byteLength?, options?)便于直接定位缓冲区中的模型段从 Uint8Array 加载create(buffer: Uint8Array, options?)。所有重载均返回PromiseInferenceSession模型加载是异步的需要await获取会话实例。创建后的会话对外暴露run(feeds, options?)/run(feeds, fetches, options?)执行推理release()释放会话及其底层资源startProfiling()/endProfiling()控制 profilinginputNames/outputNames模型输入/输出名称列表inputMetadata/outputMetadata输入/输出的元数据张量类型、形状等。其中fetches期望获取的输出支持三种写法省略使用模型默认输出、输出名字符串数组、以输出名为键的OnnxValue | null映射。特别地当fetches中提供了预分配的OnnxValue时推理引擎会直接使用该缓冲省略时则由引擎内部自行分配这在需要复用好缓冲的高频推理场景中非常有用。3.2 SessionOptions 会话配置create()的可选参数SessionOptions定义了会话级行为其中较为关键的有executionProviders执行提供方EP数组。每个元素可以是表示 EP 名称的字符串也可以是带选项的对象intraOpNumThreads / interOpNumThreads算子内/算子间线程数仅 Node.js 绑定与 React Native 可用graphOptimizationLevel图优化级别取值为disabled | basic | extended | layout | allexecutionMode执行模式sequential | parallelenableCpuMemArena / enableMemPatternCPU 内存池与内存复用模式开关freeDimensionOverrides动态维度覆盖按维度名指定具体数值optimizedModelFilePath导出优化后模型的路径浏览器中会以 blob 弹窗形式下载logId / logSeverityLevel / logVerbosityLevel日志相关配置preferredOutputLocation指定输出数据位置仅 Web 端 WebGL/WebGPU EP 可用enableGraphCaptureWebGPU EP 下的图捕获开关extra透传底层 C 配置键值对例如session.set_denormal_as_zero、optimization.enable_gelu_approximation等。从源码注释可以看到extra的标准用法示例extra: { session: { set_denormal_as_zero: 1, disable_prepacking: 1 }, optimization: { enable_gelu_approximation: 1 } }3.3 执行提供方EP矩阵源码中的ExecutionProviderOptionMap完整列出了统一 API 覆盖的执行提供方同时注释给出了各后端的能力边界后端支持的 EPNode.js 绑定cpu、dmlWindows、coremlmacOS、cudaLinuxWebAssemblycpu、wasm、webgpu、webnnONNX.js旧版 Web 后端webglReact Nativecpu、xnnpack、coremliOS、nnapiAndroid对应的 EP 选项接口包括CpuExecutionProviderOptionuseArena是否启用内存池CudaExecutionProviderOption / DmlExecutionProviderOption / TensorRtExecutionProviderOption均支持deviceId指定设备WebGpuExecutionProviderOption支持preferredLayout默认NCHW、forceCpuNodeNames、validationModedisabled | wgpuOnly | basic | full默认basic、多种缓冲缓存模式storageBufferCacheMode默认bucket、uniformBufferCacheMode默认simple等以及外部deviceWebNNExecutionProviderOption可通过context传入外部MLContext并指定deviceTypecpu | gpu | npu、powerPreference等QnnExecutionProviderOptionbackendType默认htp与backendPath互斥CoreMLExecutionProviderOptioncoreMlFlags位标志如COREML_FLAG_USE_CPU_ONLY 0x001、COREML_FLAG_CREATE_MLPROGRAM 0x010以及useCPUOnly等 React Native 专属选项NnapiExecutionProviderOptionuseFP16、useNCHW、cpuDisabled、cpuOnly。这种统一选项接口 各平台能力子集的设计正是统一 API 的核心价值应用层代码用同一套配置书写由各平台包决定哪些选项实际生效。3.4 RunOptions 运行期配置run()的第三个可选参数RunOptions控制单次推理行为包括logSeverityLevel04 级、logVerbosityLevel运行期日志terminate置为true时尽快终止未完成的 OrtRun 调用tag为本次 Run 打标签便于区分多次调用extra透传运行期配置例如memory.enable_memory_arena_shrinkage: 1。四、核心 API 之二Tensor 张量与 OnnxValue4.1 数据类型映射在 ONNX Runtime JS API 中模型的输入输出统一抽象为OnnxValue。从 onnx-value.ts 可以看到export type OnnxValue Tensor | NonTensorType; // NonTensorType 目前为 never即暂不支持非张量值Tensor是核心数据结构其DataTypeMap见 tensor.ts定义了 JS 类型到 ONNX 数据类型的映射ONNX 类型JS 底层类型float32Float32Arrayfloat64Float64Arrayfloat16Uint16Array暂以 Uint16Array 承载int8/uint8/boolInt8Array/Uint8Array/Uint8Arrayint16/uint16Int16Array/Uint16Arrayint32/uint32Int32Array/Uint32Arrayint64/uint64BigInt64Array/BigUint64Arraystringstring[]uint4/int4Uint8Array/Int8Array4.2 数据位置与跨端能力Tensor.DataLocation定义了张量数据可能存在的五种位置none数据已释放cpu/cpu-pinnedCPU 内存pinned 表示锁页内存textureWebGL 纹理gpu-bufferWebGPU 缓冲区ml-tensorWebNN 的 MLTensor。Tensor 接口相应地提供了dataCPU 数据位于 GPU 时抛错、texture、gpuBuffer、mlTensor等访问器以及getData(releaseData?)数据在 CPU 时同步返回在 GPU 时异步下载dispose()释放底层数据调用后张量失效、位置变为none。这一设计让同一份张量对象可以在 CPU 与 GPU 后端之间流动是 WebGPU/WebGL/WebNN 后端得以共用统一 API 的关键。从构造器重载可以看出Tensor 既支持通过(type, data, dims)显式指定元素类型也支持通过传入的 TypedArray 自动推断类型且dims省略时按 1-D 张量处理。五、核心 API 之三全局环境配置 envenv.ts 定义了一个全局单例env对象实现位于 env-impl.ts集中管理运行时全局配置logLevel日志严重级别取值verbose | info | warning | error | fatal默认warningdebug / trace调试模式与跟踪开关versions只读暴露当前common版本及各平台web、node、react-native版本。此外env还按后端细分了三组标志5.1 env.wasmWebAssembly 标志numThreads线程数0 表示由系统决定1 表示不启动 worker 线程simdtrue | false | fixed | relaxed控制 SIMD 特性检测策略默认true即检测定宽 SIMDinitTimeoutWebAssembly 后端初始化超时毫秒0 表示不设超时wasmPathswasm/mjs文件的 URL 前缀或对象级覆盖路径。源码注释给出了默认文件名约定默认构建为ort-wasm-simd-threaded.wasm/.mjsJSEP 构建含 WebGPU/WebNN为.jsep.后缀Asyncify 与 JSPI 构建分别带.asyncify.、.jspi.后缀wasmBinary直接提供 wasm 二进制缓冲区设置后wasmPaths被忽略proxy是否将主线程执行代理到 worker 线程默认false。5.2 env.webglWebGL 标志contextIdwebgl | webgl2默认webgl2textureCacheMode纹理缓存模式initializerOnly | full默认fullpack打包纹理模式async异步下载开关。5.3 env.webgpuWebGPU 标志profiling.modeoff | default并可通过profiling.ondata回调接收 profiling 数据WebGpuProfilingData含 kernel 名称、起止时间、输入输出元数据等powerPreference/forceFallbackAdapterrequestAdapter()选项仅首个 WebGPU 会话创建前生效已标记弃用建议改用自建GPUDeviceadapter/device外部GPUAdapter/GPUDevice注入其中device在首次会话创建前 get 时会尝试创建新的GPUDevice创建后 get 则返回实际使用的设备validateInputContent输入内容校验开关。六、后端注册机制统一 API 如何落到各平台onnxruntime-common之所以能成为三个平台包的公共层关键在于其后端注册backend registration机制。backend.ts 定义了Backend接口init()异步初始化、createInferenceSessionHandler()创建底层会话处理器与InferenceSessionHandler提供run、startProfiling、endProfiling等实现并通过registerBackend导出注册入口实现在 backend-impl.ts。从源码结构可以推断出整体架构上层应用只与onnxruntime-common定义的InferenceSession、Tensor等统一接口交互各平台包node/web/react-native在初始化时向注册表注册自己的Backend实现例如 Node 包注册基于 C 绑定的后端Web 包注册基于 WebAssembly/WebGPU 的后端React Native 包注册基于原生模块的后端。InferenceSession.create()内部会根据当前环境可用的后端分发到对应实现。这就是写一次推理代码跑通所有 JS 平台的实现基础。七、典型使用方式基于统一 API 推导虽然onnxruntime-common本身不直接使用但理解其 API 后在任何平台包中都可以按以下模式编写推理代码以下示例基于 inference-session.ts 与 tensor.ts 的类型定义推导// 以 onnxruntime-node / onnxruntime-web / onnxruntime-react-native 之一为例 import * as ort from onnxruntime-node; // 或 onnxruntime-web // 1. 创建推理会话从 URI 加载 const session await ort.InferenceSession.create(./model.onnx, { executionProviders: [cpu], graphOptimizationLevel: all, }); // 2. 构造输入张量 const input new ort.Tensor(float32, new Float32Array([1, 2, 3, 4]), [2, 2]); // 3. 运行推理 const outputs await session.run({ inputName: input }); console.log(outputs.outputName.data); // 4. 释放会话 await session.release();若想查看各平台包对这些统一接口的具体实现差异可以分别深入 js/node/src、js/web/lib 与 js/react_native/lib 目录onnxruntime-common的测试与构建配置则见 js/common/test 与 js/common/package.json。八、许可证onnxruntime-common采用 MIT 许可证见 js/common/package.json 的license字段仓库根目录的 README.md 中提供了完整的许可证说明与第三方声明ThirdPartyNotices.txt。结语onnxruntime-common虽然是一个不作为直接使用的基础包却是整个 ONNX Runtime JavaScript 生态的基石它用一套 TypeScript 接口统一了 Node.js、WebWebAssembly/WebGPU/WebGL/WebNN与 React Native 三大平台的推理编程模型把会话管理、张量表示、执行提供方配置、全局环境开关等能力收敛为稳定契约。理解了它就理解了 ONNX Runtime 在 JavaScript 世界里的完整架构脉络。【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考