ONNX Runtime JSEPJS Execution Provider弃用指南onnxruntime-web 的 WebGPU 原生半体与其向原生 WebGPU EP 的迁移【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime本文围绕 JSEP 原生端目录说明 展开解释onnxruntime/core/providers/js/在 onnxruntime-web 中扮演的角色、该 EP 已进入仅接受 bug 修复与安全修复维护模式的原因、其 TypeScript 内核与 C 桩代码协同工作的实现机制、--use_jsepUSE_JSEP构建链路以及如何判断你的构建到底在跑哪套 WebGPU 后端并给出向原生 WebGPU EP 迁移的具体路径。目录定位JSEP 的原生半体onnxruntime/core/providers/js/ 是JSEPJS Execution Provider的原生半体对应onnxruntime-web中 JavaScript/TypeScript 实现的 WebGPU 计算路径。JSEP 的核心思想是把 WebGPU 计算逻辑用 TypeScript 写在浏览器端js/web/lib/wasm/jsep/而 C 侧即本目录只负责生成内核桩kernel stubs每个算子在构造与执行时通过 Emscripten 的EM_ASM内联汇编把调用派发回 JavaScript 侧真正执行。该目录当前的文件构成均可在仓库中直接查看文件职责js_execution_provider.h / js_execution_provider.ccEP 主体能力划分GetCapability、内核注册表、数据布局偏好、图捕获Graph Capture策略js_kernel.h / js_kernel.ccJsKernel基类与JSEP_KERNEL_IMPL等宏完成序列化上下文 → 回调 JS 内核的执行桥js_provider_factory.cc / js_provider_factory_creator.hIExecutionProviderFactory工厂按 ProviderOptions 创建JsExecutionProviderallocator.h / data_transfer.h / external_data_loader.hEP 私有分配器、CPU↔JS 内存搬运、外部数据加载js_data_types.hJSEP 自定义数据类型的桥接定义js_export.hEMSCRIPTEN_KEEPALIVE导出的 C 函数JsepOutput、JsepGetNodeName供 JS 侧回调operators/约 40 组 ONNX 算子桩Conv、MatMul、Gemm、Pool、Softmax、Resize、LayerNorm、GatherND、ScatterND、DFT、Einsum 等JSEP 的完整组成跨越仓库多个区域引自权威弃用声明 docs/JSEP_Deprecation.md路径内容js/web/lib/wasm/jsep/TypeScript WebGPU 后端及全部内核实现onnxruntime/core/providers/js/本目录原生 JS EP——把执行派发回 JavaScript 的内核桩onnxruntime/contrib_ops/js/同一 EP 的 contrib 算子注册js_contrib_kernels.cc 等onnxruntime/wasm/pre-jsep.jsEmscripten 胶水脚本cmake/onnxruntime_providers_js.cmake、js/build_jsep.bat构建管线当前状态弃用与贡献政策README 开宗明义本目录已弃用计划移除替代品是 onnxruntime/core/providers/webgpu/ 下的原生 WebGPU execution provider。JSEP 处于维护模式maintenance mode仅接受 bug 修复与安全修复新算子、新特性、性能优化一律应提交到原生 WebGPU EP。docs/JSEP_Deprecation.md 给出了权威的变更归属表变更类型归属既有 JSEP 内核的正确性/安全修复JSEP——接受新算子原生 WebGPU EP——onnxruntime/core/providers/webgpu/或onnxruntime/contrib_ops/webgpu/新特性或性能工作原生 WebGPU EP需要注意两点细节移除时间表尚未确定官方表示会依据真实世界的 JSEP 使用量在移除前公告js/web/docs/webgpu-operators.md虽名为 webgpu但实际列举的是JSEP算子不能用它来判断原生 WebGPU EP 的算子覆盖情况若某模型在 JSEP 上能跑、在原生 WebGPU EP 上跑不了属于值得报告的缺口open issue 或在原生 EP 中补齐。现在往 JSEP 加代码等于这些工作日后被删除、还要针对原生 EP 重写一遍——这是弃用声明中明确的贡献者警示。实现机制C 桩如何驱动 TypeScript 内核内核注册与构造本目录中的算子桩普遍采用js_kernel.h中定义的一组宏。以JSEP_KERNEL_IMPL(classname, optype)为例它生成的类在构造时执行JSEP_INIT_KERNEL(optype)展开为#define JSEP_INIT_KERNEL(optype) EM_ASM({ Module.jsepCreateKernel(#optype, $0, undefined); }, this)即 C 内核对象构造时通过EM_ASM内联 JavaScript 在浏览器端注册同名内核Module.jsepCreateKernel析构时调用Module.jsepReleaseKernel释放。带属性的算子如 Conv 的 strides/pads则通过JSEP_CLASS_IMPL_ATTRIBUTE_FLOAT_DEFAULT等宏把OpKernelInfo中读到的属性值一并传给 JS 侧。执行桥上下文序列化JsKernel::ComputeInternal展示了每次Compute的完整链路见 js_kernel.hSerializeKernelContext把OpKernelContext序列化为一段连续uintptr_t数组context_ptr | input_count | output_count | custom_data_ptr | custom_data_size随后对每个输入写入type | data_ptr | dim_size | dim[0..N-1]可选输入为空时写入三个 0 占位JS 侧据此感知输入个数通过EM_ASM_INT调用Module.jsepRunKernel传入内核对象、序列化缓冲、session handle 与错误通道依据返回状态码映射为Status::OK()或失败。此外js_export.h用EMSCRIPTEN_KEEPALIVE导出JsepOutput/JsepGetNodeName供 JS 回调JsKernel还支持SerializeCustomData供子类追加自定义数据JsMultiProgramKernel的多程序内核在源码中仍标注为 TODO。EP 层行为特征从 js_execution_provider.h 可以看到几个影响使用者行为的关键设定首选数据布局 NHWCJsExecutionProviderInfo从 ProviderOptions 的preferred_layout读取仅支持NCHW/NHWCJSEP 默认为NHWCL23-L38禁止并发运行ConcurrentRunSupported()返回false源码注释解释原因是底层实现如 WebGPU 后端依赖全局状态异步并发运行可能破坏状态导致未定义行为L63-L65融合风格FusionStyle::FilteredGraphViewer并内置图捕获Graph Capture支持要求最少 1 次常规运行后才捕获节点分配策略为ALLOW_CPU_FOR_SHAPES。js_execution_provider.cc中还在kJsExecutionProvider下注册了MemcpyFromHost/MemcpyToHost执行队列 0/1用于 CPU 与 JS 内存域之间的张量搬运以及数十个带版本区间的一阶算子如 Abs、Neg、Tanh 注册在 opset 6–12 与 13 两个区间。构建链路USE_JSEP 与 WASM 产物JSEP 通过构建参数--use_jsepCMake 变量USE_JSEP启用注册到 EP 名称JsExecutionProvider之下。仓库中的构建管线证据cmake/CMakeLists.txt 定义option(onnxruntime_USE_JSEP Build with JavaScript implemented kernels support OFF)为真时追加-DUSE_JSEP1编译定义tools/ci_build/build_args.py 中的 argparse 定义--use_jsepEnable JavaScript EP (used with WebAssembly)cmake/onnxruntime_providers_js.cmake 负责把本目录与 contrib_ops/js 源文件纳入编译js/build_jsep.bat 是 Windows 下的 JSEP 构建入口。浏览器侧的产物选择则体现在 js/web/package.json 的导出映射中.jsep.wasm资产路径等。区分两套 WebGPUimport 与 WASM 文件名JSEP 与原生 WebGPU EP 都注册在 JavaScript 的webgpu后端键下运行哪一个由构建期决定而非运行期。docs/JSEP_Deprecation.md 给出的对照表是排障时的首选依据ImportWebGPU 实现WASM 产物onnxruntime-web默认JSEPort-wasm-simd-threaded.jsep.wasmonnxruntime-web/allJSEPort-wasm-simd-threaded.jsep.wasmonnxruntime-web/webgpu原生 WebGPU EPort-wasm-simd-threaded.asyncify.wasmonnxruntime-web/jspi原生 WebGPU EPort-wasm-simd-threaded.jspi.wasmWASM 文件名中的.jsep中缀是可靠判别信号。一份没有指明 import 或产物的 bug 报告在 triage 前属于歧义状态应先澄清。如何迁移到原生 WebGPU EPonnxruntime-web/webgpu与onnxruntime-web/jspi今天已经基于原生 WebGPU EP 构建不需要任何代码改动即可使用import * as ort from onnxruntime-web/webgpu;结合迁移设计文档 docs/design/onnxruntime_web_jsep_to_webgpu_ep_migration.md使用者需要关注以下差异点默认 import 暂未切换当前onnxruntime-web默认仍选 JSEP计划在未来版本翻转为原生 WebGPU EP翻转后官方会提供临时的onnxruntime-web/jsep逃生舱导出用于固定旧行为至少保留一个 release期间使用会发出一次性弃用警告。int64 行为原生 WebGPU EP 默认enableInt64 false与 JSEP 默认行为一致int64 算术在 CPU/WASM 上全精度执行int64 索引在 GPU 上按 i32 截断。如需 GPU 上全量 int64可通过extra: { ep.webgpuexecutionprovider.enableInt64: 1 }开启代价是 2³¹的真值会丢失精度另外enableGraphCapture true会强制打开 int64。JSEP 专属的env.webgpu设置env.webgpu.profiling.ondata每次 dispatch 的 JS 回调携带kernelId/时间戳/张量元数据在原生路径上没有等价物属 JSEP-only 机制将随 JSEP 一起移除adapter/forceFallbackAdapter在原生路径上为 no-op自定义设备请走 per-session 的executionProviders: [{ name: webgpu, device }]powerPreference将转发到原生 EP 的ep.webgpuexecutionprovider.powerPreference选项且需注意两者的未设置默认行为不同JSEP 让浏览器自选原生侧默认HighPerformance。wasmPaths翻转后底层产物从.jsep.wasm变为.asyncify.wasm固定了 WASM 路径的消费者对象形式env.wasm.wasmPaths、预加载/CSP 规则、复制的资源需要同步更新。算子/类型面原生 WebGPU EP 构建当前应用了缩减构建参数禁用 ml ops、generation ops 与 string/float4/float8/optional/sparse 类型翻转前该差异需要按设计文档 §7 的 A/B/C 构建测量结果统一处理。Phase 2JSEP 将被移除什么设计文档明确了删除范围约 130 个 C/CMake 文件几乎全是删除onnxruntime/core/providers/js/约 90 文件与onnxruntime/contrib_ops/js/约 30 文件、cmake/onnxruntime_providers_js.cmake 及USE_JSEP在多个 CMake 文件中的管线、onnxruntime/wasm/pre-jsep.js、js/build_jsep.bat以及 CI 中--use_jsep参数。两处需要特别留意kJsExecutionProvider属于公共 C API 面声明于include/onnxruntime/core/graph/constants.h并在onnxruntime_c_api.h中命名其移除是一次 API 变更post-webnn.js在 JSEP 构建下被抑制移除 JSEP 会改变 WebNN 构建链接的胶水脚本需要 WebNN 冒烟测试而不只是编译通过。小结onnxruntime/core/providers/js/ 承载的是 JSEP 的 C 内核桩与 EP 基础设施内核通过EM_ASM把执行派发回 TypeScript 侧的 WebGPU 实现EP 侧提供 NHWC 偏好布局、禁止并发运行、图捕获等策略。该组件已进入仅 bug 与安全修复的维护模式替代品是原生 WebGPU EP——今天即可通过onnxruntime-web/webgpu或onnxruntime-web/jspiimport 使用默认 bundle 的翻转与 JSEP 的最终移除将按 docs/JSEP_Deprecation.md 与 迁移设计文档 的分期推进并在移除前公告时间表。【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ONNX Runtime JSEP（JS Execution Provider）弃用指南：onnxruntime-web 的 WebGPU 原生半体与其向原生 WebGPU EP 的迁移
ONNX Runtime JSEPJS Execution Provider弃用指南onnxruntime-web 的 WebGPU 原生半体与其向原生 WebGPU EP 的迁移【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime本文围绕 JSEP 原生端目录说明 展开解释onnxruntime/core/providers/js/在 onnxruntime-web 中扮演的角色、该 EP 已进入仅接受 bug 修复与安全修复维护模式的原因、其 TypeScript 内核与 C 桩代码协同工作的实现机制、--use_jsepUSE_JSEP构建链路以及如何判断你的构建到底在跑哪套 WebGPU 后端并给出向原生 WebGPU EP 迁移的具体路径。目录定位JSEP 的原生半体onnxruntime/core/providers/js/ 是JSEPJS Execution Provider的原生半体对应onnxruntime-web中 JavaScript/TypeScript 实现的 WebGPU 计算路径。JSEP 的核心思想是把 WebGPU 计算逻辑用 TypeScript 写在浏览器端js/web/lib/wasm/jsep/而 C 侧即本目录只负责生成内核桩kernel stubs每个算子在构造与执行时通过 Emscripten 的EM_ASM内联汇编把调用派发回 JavaScript 侧真正执行。该目录当前的文件构成均可在仓库中直接查看文件职责js_execution_provider.h / js_execution_provider.ccEP 主体能力划分GetCapability、内核注册表、数据布局偏好、图捕获Graph Capture策略js_kernel.h / js_kernel.ccJsKernel基类与JSEP_KERNEL_IMPL等宏完成序列化上下文 → 回调 JS 内核的执行桥js_provider_factory.cc / js_provider_factory_creator.hIExecutionProviderFactory工厂按 ProviderOptions 创建JsExecutionProviderallocator.h / data_transfer.h / external_data_loader.hEP 私有分配器、CPU↔JS 内存搬运、外部数据加载js_data_types.hJSEP 自定义数据类型的桥接定义js_export.hEMSCRIPTEN_KEEPALIVE导出的 C 函数JsepOutput、JsepGetNodeName供 JS 侧回调operators/约 40 组 ONNX 算子桩Conv、MatMul、Gemm、Pool、Softmax、Resize、LayerNorm、GatherND、ScatterND、DFT、Einsum 等JSEP 的完整组成跨越仓库多个区域引自权威弃用声明 docs/JSEP_Deprecation.md路径内容js/web/lib/wasm/jsep/TypeScript WebGPU 后端及全部内核实现onnxruntime/core/providers/js/本目录原生 JS EP——把执行派发回 JavaScript 的内核桩onnxruntime/contrib_ops/js/同一 EP 的 contrib 算子注册js_contrib_kernels.cc 等onnxruntime/wasm/pre-jsep.jsEmscripten 胶水脚本cmake/onnxruntime_providers_js.cmake、js/build_jsep.bat构建管线当前状态弃用与贡献政策README 开宗明义本目录已弃用计划移除替代品是 onnxruntime/core/providers/webgpu/ 下的原生 WebGPU execution provider。JSEP 处于维护模式maintenance mode仅接受 bug 修复与安全修复新算子、新特性、性能优化一律应提交到原生 WebGPU EP。docs/JSEP_Deprecation.md 给出了权威的变更归属表变更类型归属既有 JSEP 内核的正确性/安全修复JSEP——接受新算子原生 WebGPU EP——onnxruntime/core/providers/webgpu/或onnxruntime/contrib_ops/webgpu/新特性或性能工作原生 WebGPU EP需要注意两点细节移除时间表尚未确定官方表示会依据真实世界的 JSEP 使用量在移除前公告js/web/docs/webgpu-operators.md虽名为 webgpu但实际列举的是JSEP算子不能用它来判断原生 WebGPU EP 的算子覆盖情况若某模型在 JSEP 上能跑、在原生 WebGPU EP 上跑不了属于值得报告的缺口open issue 或在原生 EP 中补齐。现在往 JSEP 加代码等于这些工作日后被删除、还要针对原生 EP 重写一遍——这是弃用声明中明确的贡献者警示。实现机制C 桩如何驱动 TypeScript 内核内核注册与构造本目录中的算子桩普遍采用js_kernel.h中定义的一组宏。以JSEP_KERNEL_IMPL(classname, optype)为例它生成的类在构造时执行JSEP_INIT_KERNEL(optype)展开为#define JSEP_INIT_KERNEL(optype) EM_ASM({ Module.jsepCreateKernel(#optype, $0, undefined); }, this)即 C 内核对象构造时通过EM_ASM内联 JavaScript 在浏览器端注册同名内核Module.jsepCreateKernel析构时调用Module.jsepReleaseKernel释放。带属性的算子如 Conv 的 strides/pads则通过JSEP_CLASS_IMPL_ATTRIBUTE_FLOAT_DEFAULT等宏把OpKernelInfo中读到的属性值一并传给 JS 侧。执行桥上下文序列化JsKernel::ComputeInternal展示了每次Compute的完整链路见 js_kernel.hSerializeKernelContext把OpKernelContext序列化为一段连续uintptr_t数组context_ptr | input_count | output_count | custom_data_ptr | custom_data_size随后对每个输入写入type | data_ptr | dim_size | dim[0..N-1]可选输入为空时写入三个 0 占位JS 侧据此感知输入个数通过EM_ASM_INT调用Module.jsepRunKernel传入内核对象、序列化缓冲、session handle 与错误通道依据返回状态码映射为Status::OK()或失败。此外js_export.h用EMSCRIPTEN_KEEPALIVE导出JsepOutput/JsepGetNodeName供 JS 回调JsKernel还支持SerializeCustomData供子类追加自定义数据JsMultiProgramKernel的多程序内核在源码中仍标注为 TODO。EP 层行为特征从 js_execution_provider.h 可以看到几个影响使用者行为的关键设定首选数据布局 NHWCJsExecutionProviderInfo从 ProviderOptions 的preferred_layout读取仅支持NCHW/NHWCJSEP 默认为NHWCL23-L38禁止并发运行ConcurrentRunSupported()返回false源码注释解释原因是底层实现如 WebGPU 后端依赖全局状态异步并发运行可能破坏状态导致未定义行为L63-L65融合风格FusionStyle::FilteredGraphViewer并内置图捕获Graph Capture支持要求最少 1 次常规运行后才捕获节点分配策略为ALLOW_CPU_FOR_SHAPES。js_execution_provider.cc中还在kJsExecutionProvider下注册了MemcpyFromHost/MemcpyToHost执行队列 0/1用于 CPU 与 JS 内存域之间的张量搬运以及数十个带版本区间的一阶算子如 Abs、Neg、Tanh 注册在 opset 6–12 与 13 两个区间。构建链路USE_JSEP 与 WASM 产物JSEP 通过构建参数--use_jsepCMake 变量USE_JSEP启用注册到 EP 名称JsExecutionProvider之下。仓库中的构建管线证据cmake/CMakeLists.txt 定义option(onnxruntime_USE_JSEP Build with JavaScript implemented kernels support OFF)为真时追加-DUSE_JSEP1编译定义tools/ci_build/build_args.py 中的 argparse 定义--use_jsepEnable JavaScript EP (used with WebAssembly)cmake/onnxruntime_providers_js.cmake 负责把本目录与 contrib_ops/js 源文件纳入编译js/build_jsep.bat 是 Windows 下的 JSEP 构建入口。浏览器侧的产物选择则体现在 js/web/package.json 的导出映射中.jsep.wasm资产路径等。区分两套 WebGPUimport 与 WASM 文件名JSEP 与原生 WebGPU EP 都注册在 JavaScript 的webgpu后端键下运行哪一个由构建期决定而非运行期。docs/JSEP_Deprecation.md 给出的对照表是排障时的首选依据ImportWebGPU 实现WASM 产物onnxruntime-web默认JSEPort-wasm-simd-threaded.jsep.wasmonnxruntime-web/allJSEPort-wasm-simd-threaded.jsep.wasmonnxruntime-web/webgpu原生 WebGPU EPort-wasm-simd-threaded.asyncify.wasmonnxruntime-web/jspi原生 WebGPU EPort-wasm-simd-threaded.jspi.wasmWASM 文件名中的.jsep中缀是可靠判别信号。一份没有指明 import 或产物的 bug 报告在 triage 前属于歧义状态应先澄清。如何迁移到原生 WebGPU EPonnxruntime-web/webgpu与onnxruntime-web/jspi今天已经基于原生 WebGPU EP 构建不需要任何代码改动即可使用import * as ort from onnxruntime-web/webgpu;结合迁移设计文档 docs/design/onnxruntime_web_jsep_to_webgpu_ep_migration.md使用者需要关注以下差异点默认 import 暂未切换当前onnxruntime-web默认仍选 JSEP计划在未来版本翻转为原生 WebGPU EP翻转后官方会提供临时的onnxruntime-web/jsep逃生舱导出用于固定旧行为至少保留一个 release期间使用会发出一次性弃用警告。int64 行为原生 WebGPU EP 默认enableInt64 false与 JSEP 默认行为一致int64 算术在 CPU/WASM 上全精度执行int64 索引在 GPU 上按 i32 截断。如需 GPU 上全量 int64可通过extra: { ep.webgpuexecutionprovider.enableInt64: 1 }开启代价是 2³¹的真值会丢失精度另外enableGraphCapture true会强制打开 int64。JSEP 专属的env.webgpu设置env.webgpu.profiling.ondata每次 dispatch 的 JS 回调携带kernelId/时间戳/张量元数据在原生路径上没有等价物属 JSEP-only 机制将随 JSEP 一起移除adapter/forceFallbackAdapter在原生路径上为 no-op自定义设备请走 per-session 的executionProviders: [{ name: webgpu, device }]powerPreference将转发到原生 EP 的ep.webgpuexecutionprovider.powerPreference选项且需注意两者的未设置默认行为不同JSEP 让浏览器自选原生侧默认HighPerformance。wasmPaths翻转后底层产物从.jsep.wasm变为.asyncify.wasm固定了 WASM 路径的消费者对象形式env.wasm.wasmPaths、预加载/CSP 规则、复制的资源需要同步更新。算子/类型面原生 WebGPU EP 构建当前应用了缩减构建参数禁用 ml ops、generation ops 与 string/float4/float8/optional/sparse 类型翻转前该差异需要按设计文档 §7 的 A/B/C 构建测量结果统一处理。Phase 2JSEP 将被移除什么设计文档明确了删除范围约 130 个 C/CMake 文件几乎全是删除onnxruntime/core/providers/js/约 90 文件与onnxruntime/contrib_ops/js/约 30 文件、cmake/onnxruntime_providers_js.cmake 及USE_JSEP在多个 CMake 文件中的管线、onnxruntime/wasm/pre-jsep.js、js/build_jsep.bat以及 CI 中--use_jsep参数。两处需要特别留意kJsExecutionProvider属于公共 C API 面声明于include/onnxruntime/core/graph/constants.h并在onnxruntime_c_api.h中命名其移除是一次 API 变更post-webnn.js在 JSEP 构建下被抑制移除 JSEP 会改变 WebNN 构建链接的胶水脚本需要 WebNN 冒烟测试而不只是编译通过。小结onnxruntime/core/providers/js/ 承载的是 JSEP 的 C 内核桩与 EP 基础设施内核通过EM_ASM把执行派发回 TypeScript 侧的 WebGPU 实现EP 侧提供 NHWC 偏好布局、禁止并发运行、图捕获等策略。该组件已进入仅 bug 与安全修复的维护模式替代品是原生 WebGPU EP——今天即可通过onnxruntime-web/webgpu或onnxruntime-web/jspiimport 使用默认 bundle 的翻转与 JSEP 的最终移除将按 docs/JSEP_Deprecation.md 与 迁移设计文档 的分期推进并在移除前公告时间表。【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
