【Bug已解决】[Web] Expose WebGPU EP buffer cache mode options in JS 解决方案

【Bug已解决】[Web] Expose WebGPU EP buffer cache mode options in JS 解决方案一、现象长什么样在 Web 端ONNX Runtime Web用 WebGPU EP想调“缓冲区缓存模式”相关的 session 选项比如让中间张量在不同run()之间复用 GPU buffer减少分配开销。但 JS API 里根本找不到这些选项的入口设不进去const session await ort.InferenceSession.create(model.onnx, { executionProviders: [{ name: webgpu, /* 没有 buffer cache mode 选项可设 */ }], }); // 期望能设类似 // { name: webgpu, bufferCacheMode: reuse, ... } // 但 JS 类型/文档里没有这个选项最小信号WebGPU EP 在 C/原生侧有 buffer cache mode 选项 JS/Web 绑定没有暴露这些选项 - Web 用户调不了 性能调优受限无法复用 buffer注意这不是崩溃而是JS 绑定漏暴露了 WebGPU EP 的配置项属于 API 暴露缺口。二、背景WebGPU EP 在底层C有一组控制“张量缓冲区如何缓存/复用”的 session 选项。核心思想是多次run()之间很多中间张量的形状是固定的与其每次都createBuffer/destroyBuffer不如把 buffer缓存起来跨 run 复用buffer cache mode。这能显著降低 GPU 内存分配的系统调用开销提升反复推理的吞吐。这套选项在 ORT 的 CSessionOptions/OrtCUDAProviderOptions风格的 WebGPU 配置结构体里是存在的比如控制 cache 模式、缓存大小、是否跨 session 复用等。但 ORT Web 的JS 绑定把 C 选项映射成 JS 对象的那层只暴露了少数几个常用项deviceId、preferredLayout 等漏掉了 buffer cache mode 相关的字段。于是 Web 开发者要么用不了这个优化要么只能改 ORT Web 源码重新编译门槛很高。三、根因根因是ORT Web 的 JS 绑定在把 WebGPU EP 的 session 选项从 C 映射到 JS 对象时漏掉了 buffer cache mode 相关字段导致 Web 侧无法设置这些优化项选项映射不全JS 绑定的“WebGPU 选项 schema”只列了部分字段buffer cache mode 字段如bufferCacheMode、enableBufferReuse等没进白名单传了也被忽略或报错。C 侧有、JS 侧无底层OrtSessionOptionsAppendExecutionProvider_WebGPU支持这些选项但 JS 层没把它暴露成可设属性。不是功能缺失功能在后端存在只是 Web 入口没开Web 用户被挡在门外。只影响 Web原生/C 用户能直接设Web 用户不能 - 典型的绑定暴露缺口。所以这不是数值错而是JS API 暴露不全WebGPU EP 的 buffer 缓存选项调不到。四、最小可运行复现下面用 JS 风格的伪代码模拟“JS 选项 schema 过滤掉未知字段导致 buffer cache 选项设不进”// C 侧支持的 WebGPU 选项完整 const WEBGPU_OPTIONS_CPP { deviceId: 0, preferredLayout: NCHW, bufferCacheMode: reuse, // 后端支持 enableBufferReuse: true, }; // JS 绑定的 schema 白名单漏了 buffer 缓存项 const JS_WHITELIST [deviceId, preferredLayout]; function createSessionOptions(jsOpts) { const cppOpts {}; for (const k of Object.keys(jsOpts)) { if (!JS_WHITELIST.includes(k)) { console.warn(选项 ${k} 不被 JS 绑定支持已忽略); // 漏暴露 - 忽略 continue; } cppOpts[k] jsOpts[k]; } return cppOpts; // bufferCacheMode 没进去 } const applied createSessionOptions({ deviceId: 0, bufferCacheMode: reuse, // 想设但被忽略 }); console.log(applied); // { deviceId: 0 } - bufferCacheMode 丢了跑这个逻辑因为bufferCacheMode不在 JS 白名单被忽略最终applied里没有它。这复现了“JS 绑定漏暴露 WebGPU buffer 缓存选项”的机制。五、解决方案第一层最小直接修复最小修复在 ORT Web 的 JS 绑定里把 WebGPU EP 的 buffer cache mode 选项加进 schema 白名单让它能透传到 C 侧。对使用者临时规避若版本未修是改 ORT Web 源码把选项加进白名单重新打包或退而求其次用其它已暴露的复用手段。JS 绑定侧修复示意把字段加入 WebGPU 选项类型与转换// ort-web 的 WebGPU EP 选项类型扩展 export interface WebGpuExecutionProviderOption { deviceId?: number; preferredLayout?: NCHW | NHWC; // 新增缓冲区缓存模式透传到底层 bufferCacheMode?: none | reuse | reuse_cross_session; enableBufferReuse?: boolean; // 转换时把这些字段写进底层 OrtSessionOptions }// 使用方现在能直接设 const session await ort.InferenceSession.create(model.onnx, { executionProviders: [{ name: webgpu, bufferCacheMode: reuse, // 现在生效 enableBufferReuse: true, }], });这一层立刻让 Web 用户能调 buffer 缓存优化。六、解决方案第二层结构性改进把“WebGPU EP 在 JS 侧应暴露哪些选项”收口成唯一的配置对象OrtWebGpuBufferCachePolicy绑定与文档读它from dataclasses import dataclass, field from typing import Tuple dataclass(frozenTrue) class OrtWebGpuBufferCachePolicy: WebGPU EP buffer 缓存选项在 JS 侧暴露的单一事实来源。 # 必须在 JS 绑定暴露的 WebGPU 选项 exposed_js_options: Tuple[str, ...] ( deviceId, preferredLayout, bufferCacheMode, enableBufferReuse, cacheSizeBytes, ) # buffer 缓存模式取值 cache_modes: Tuple[str, ...] (none, reuse, reuse_cross_session) # 默认模式 default_mode: str reuse def is_exposed(self, option: str) - bool: return option in self.exposed_js_options def describe(self) - str: return WebGPU buffer 缓存选项在 JS 绑定全量暴露可透传调优 POLICY OrtWebGpuBufferCachePolicy() def plan_js_options(opts: dict, policy: OrtWebGpuBufferCachePolicy POLICY) - dict: out {} for k, v in opts.items(): if policy.is_exposed(k): out[k] v return out所有 JS 绑定与文档读同一份POLICYbuffer 缓存选项不再被漏暴露。七、解决方案第三层断言 / CI 守护把“WebGPU buffer 缓存选项在 JS 侧可设”做成断言。下面用 pytest 风格守护复用第四节逻辑import pytest def test_buffer_cache_option_exposed(policy): assert bufferCacheMode in policy.exposed_js_options assert enableBufferReuse in policy.exposed_js_options def test_option_passes_through(policy): applied plan_js_options({deviceId: 0, bufferCacheMode: reuse}, policy) assert bufferCacheMode in applied def test_cache_modes_valid(policy): assert policy.default_mode in policy.cache_modes def test_no_silent_drop(policy): # 暴露列表外的字段才被忽略列表内的必须透传 assert policy.is_exposed(bufferCacheMode) is True这四组断言锁住(1) buffer 缓存选项已暴露(2) 选项能透传(3) 缓存模式合法(4) 暴露项不被静默丢弃。CI 跑通即代表 JS 暴露缺口被守护。八、排查清单遇到 Web 上设不了 WebGPU buffer 缓存选项先确认后端是否支持C 侧有该选项、JS 设不进 - 锁定 JS 绑定漏暴露。看 JS 选项 schema白名单里有没有 buffer cache 相关字段。查转换层JS 对象有没有把字段透传到底层OrtSessionOptions。临时规避改 ORT Web 源码加白名单重新打包。根本修复把 buffer 缓存选项加进 JS 绑定 schema 并透传。统一策略对象用OrtWebGpuBufferCachePolicy固化。CI 守护断言选项暴露、能透传、不被静默丢。九、小结[Web] Expose WebGPU EP buffer cache mode options in JS的根因是ORT Web 的 JS 绑定在把 WebGPU EP 的 session 选项从 C 映射到 JS 对象时漏掉了 buffer cache mode 相关字段只暴露了 deviceId/preferredLayout 等导致 Web 侧无法设置“跨 run 复用 GPU buffer”的优化项而底层 C 其实支持。最小修复是把 buffer cache mode 选项加进 JS 绑定 schema 并透传到底层结构性改进是用唯一的OrtWebGpuBufferCachePolicy固化应暴露的选项清单CI 用四组断言守护“选项暴露、能透传、不被静默丢”。记住后端支持的 EP 选项必须在各语言绑定全量暴露漏一个字段用户就被挡在优化门外。