webnn

WebNN

流程

步骤 1：识别浏览器集成边界

1. 检查工作区，查找浏览器入口、UI 处理程序、Worker 入口文件，以及任何现有的模型加载或推理抽象层。
2. 如果有 Node 运行时，执行 node scripts/find-webnn-targets.mjs .，盘点可能的前端文件和现有的 WebNN 标记。
3. 如果没有 Node 运行时，手动检查最近的 package.json、HTML 入口、框架引导文件和 Worker 入口文件，以确定浏览器应用的边界。
4. 如果工作区包含多个前端应用，优先选择包含当前路由、组件或用户请求功能界面的应用。
5. 如果盘点后仍有多个可能的前端目标，请停止并询问应将 WebNN 集成到哪个应用中。
6. 如果项目不是浏览器 Web 应用，请停止并说明此技能不适用。

步骤 2：确认 WebNN 的可行性并选择运行时形态

1. 编写代码前，阅读 references/webnn-reference.md。
2. 在选择直接 WebNN 图流程还是围绕现有浏览器 ML 运行时构建适配器时，阅读 references/examples.md。
3. 当原生支持、预览标志、设备行为或后端差异会影响实现时，阅读 references/compatibility.md。
4. 当上下文创建、图构建、张量读回或设备选择失败时，阅读 references/troubleshooting.md。
5. 确认该功能在安全上下文中，以及 Window 或 Worker 上下文（DedicatedWorker、SharedWorker 或 ServiceWorker）中运行。
6. 如果该功能必须在服务器上运行、训练模型或依赖云端推理，请停止并说明平台不匹配。
7. 谨慎选择设备意图：吞吐量优先时使用 powerPreference: "high-performance"，节能加速时使用 powerPreference: "low-power"，或者使用 accelerated: false，优先选择 CPU 推理以获得最广泛的适用性。
8. 将 accelerated 和 powerPreference 视为偏好，而非保证。浏览器后端仍可能拆分图，或对各个算子采用回退方案。
9. 当应用负责构建图，或可以维持精简且确定的图执行路径时，选择直接使用 MLGraphBuilder 的流程。
10. 仅当应用已通过现有本地运行时加载模型，且任务是优先使用 WebNN 加速而不重写整个推理栈时，才选择围绕该运行时构建适配器。
11. 如果项目使用 TypeScript，请为项目所用的 WebNN 接口添加或保留类型定义。

步骤 3：实现受保护的运行时适配器

1. 阅读 assets/webnn-runtime.template.ts，并根据工作区中的框架、状态模型和文件布局进行调整。
2. 将支持检测集中处理，检查 window.isSecureContext、navigator.ml 和请求的执行上下文，而不要在 UI 组件中分散检查逻辑。
3. 仅在应用准备好初始化本地推理的边界处创建 MLContext。
4. 如果产品确有实际偏好，请传入明确的 accelerated 和 powerPreference 值；对于产品无法证明合理的调优选项，则省略。
5. 如果该功能使用直接 WebNN 操作，则通过 MLGraphBuilder 构建图；如果现有运行时已负责模型加载和预处理／后处理，则通过应用现有的本地运行时适配器执行模型。
6. 当请求之间的输入和输出形状保持稳定时，复用已编译的图和可复用张量。
7. 对于直接图执行，依次使用 context.writeTensor()、context.dispatch() 和 await context.readTensor()。
8. 监视 context.lost；如果浏览器使执行状态失效，则重建上下文、图和张量。
9. 当该功能被释放或路由不再需要这些对象时，销毁张量、图和上下文。 步骤 4：接入用户体验和回退行为
10. 明确展示不支持的浏览器、安全上下文失败、运行时准备中、原生执行就绪和显式回退执行等不同状态。
11. 如果必须确保该功能始终可用，请为不支持的浏览器或设备保留非 WebNN 路径。
12. 回退方案必须明确且经过产品批准。如果该功能应保持本地运行，请勿悄悄切换到远程模型提供方。
13. 将设备选择表述为意向，而非承诺所有操作都会在该设备上执行。
14. 如果应用已采用适合 Worker 的架构，请将耗时较长的模型准备工作或重复推理移出主线程。
15. 确保所有用户数据处理方式符合产品对本地处理的承诺和隐私要求。

步骤 5：验证行为

1. 执行 node scripts/find-webnn-targets.mjs .，确认预期的应用边界和 WebNN 标记仍能定位到已编辑的集成界面。
2. 在排查更深层的运行时问题之前，先验证安全上下文和 navigator.ml 检测。
3. 对于直接使用 WebNN 的路径，运行冒烟测试：创建上下文、构建简单图、写入输入、分发并读取输出。
4. 测试预期的 accelerated 和 powerPreference 设置，并确认无法创建加速上下文时回退行为仍可用。
5. 如果算子覆盖范围或张量数据类型支持会影响图设计，请使用 context.opSupportLimits()。
6. 确认应用不会重复使用已销毁的张量、图或上下文。
7. 如果目标环境依赖预览版 Chromium 标志或特定里程碑版本的行为，请先根据 references/compatibility.md 确认所需的浏览器状态，再将运行时故障视为应用 Bug。
8. 编辑后运行工作区构建、类型检查或测试。

错误处理

• 如果缺少 navigator.ml，请先根据 references/compatibility.md 确认安全上下文要求和浏览器支持情况，再更改应用代码。
• 如果 createContext() 的加速或高性能请求失败，只能按照产品批准的回退计划重试，并说明失败原因。
• 如果 build() 或 dispatch() 失败，请先查看 references/examples.md 和 references/troubleshooting.md，检查算子、形状和设备是否不匹配，再考虑重写功能。
• 如果 context.lost 得到解析，应将当前上下文、图和张量视为无效，并在下次推理前重新创建。
• 如果产品仅支持远程推理契约，请停止操作，并说明此技能并不直接适用。