后端错误
在基于 Chromium 的浏览器中，WebNN 运行在一个后端上，由它为操作系统和硬件转换您的图。后端取决于平台：
- Windows 11 24H2 或更新版本上使用 Windows ML 和 ONNX Runtime
- macOS 上使用 Core ML
- ChromeOS、Linux 和 Android 上使用 LiteRT（TFLite），在其他平台上则作为回退方案
WebNN API 本身的大多数问题请参阅常见错误。本页面针对源自后端的问题，以及有助于发现这些问题的浏览器命令行开关。各平台使用的后端请参阅浏览器兼容性表，此处提到的每个标志请参阅 WebNN 标志参考。
本页面中的命令行开关面向开发人员和测试人员，适用于 Chrome 和 Edge Canary。它们可能在不同版本之间发生变化或消失。示例使用的是 Chrome Canary 的 Windows 路径，请根据您的浏览器和平台调整路径。
确定您正在使用哪个后端
问题
您的模型在两台机器上表现不同，而您不知道每台机器使用的是哪个后端。
解决方法
- 在浏览器兼容性表和关于受支持后端的常见问题中查找您的操作系统和硬件。
- 在 Windows 11 上，检查是否正在使用 Windows ML 和 OpenVINO 执行提供程序，请参阅如何确定我在 Windows 11 上是否运行在 Windows ML / OpenVINO 执行提供程序上。
- 如下所述，使用详细的后端日志启动浏览器。
ONNX Runtime 错误
这些适用于 Windows ML 和 ONNX Runtime 后端，而不适用于您页面中的 ONNX Runtime Web。关于 ONNX Runtime Web，请参阅框架错误。
WebNN 运行在 LiteRT 后端而不是 Windows ML 上
问题
在 Windows 11 上，您期望使用 Windows ML 和 ONNX Runtime 后端，但 WebNN 运行在基于 TFLite 的 LiteRT 后端上。
解决方法
名为 “Windows ML / ONNX Runtime backend for WebNN” 的 #webnn-onnxruntime 标志（flag）控制这一行为。禁用它会启用对 TFLite 的回退。请确保它已启用，并且您运行的是 Windows 11 24H2 或更新版本。具体步骤请参阅安装，该页面还介绍了如何在不支持 Windows ML 的 Windows 版本上有意运行在 LiteRT 后端上。
"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --enable-features=WebMachineLearningNeuralNetwork,WebNNOnnxRuntime需要查看 ONNX Runtime 在做什么
问题
图编译失败或运行缓慢，而浏览器控制台没有给出有用的细节。
解决方法
使用 --webnn-ort-logging-level 提高 ONNX Runtime 的日志级别。可用的级别有 VERBOSE、INFO、WARNING、ERROR（默认）和 FATAL。
"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-logging-level=VERBOSE详细日志和信息日志还会列出这台机器上可用的执行提供程序设备。
强制指定执行提供程序设备时会话创建失败
问题
在传入 --webnn-ort-ep-device 之后，ONNX Runtime 会话创建失败。
解决方法
该命令行开关必须与现有设备匹配。如果没有设备匹配，会话创建就会失败。其值的格式为 ep_name,hardware_vendor_id,hardware_device_id，三项都必须提供且按此顺序，其中两个 id 为十六进制字符串。请在日志级别设置为 VERBOSE 或 INFO 的情况下，从日志中读取可用设备，并从中复制这些值。
"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --webnn-ort-ep-device=OpenVINOExecutionProvider,0x8086,0x4680某个执行提供程序被禁用
问题
您期望使用的某个执行提供程序没有被选中。
解决方法
部分执行提供程序会被启用标志的阻止列表禁用。若要在测试时一次性启用它们，请使用 --webnn-ort-ignore-ep-blocklist 启动浏览器。
检查优化后的模型或对运行进行性能分析
问题
您需要了解 ONNX Runtime 对您的图做了什么，或者时间花在了哪里。
解决方法
--webnn-ort-dump-model会保存经过图级别转换后的优化 ONNX 模型。--webnn-ort-enable-profiling会将 ONNX Runtime 的性能分析结果写入浏览器文件夹中的prefix_date_time.json文件。--webnn-ort-graph-optimization-level接受DISABLE_ALL、BASIC、EXTENDED和ALL。设置为DISABLE_ALL有助于您检查问题是否来自某项图优化。
输出文件夹必须可被 GPU 进程沙盒访问，否则您必须使用 --no-sandbox 启动浏览器：
"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-ort-dump-model=C:\temp\ort_models使用您自己的 ONNX Runtime、执行提供程序或驱动程序
问题
自定义构建的 ONNX Runtime、执行提供程序，或内部的 GPU 或 NPU 驱动程序没有被加载。
解决方法
请参阅调试，其中说明了如何使用 --webnn-ort-library-path-for-testing 让浏览器指向自定义的 ONNX Runtime 库，以及为什么第三方库和驱动程序需要 --allow-third-party-modules。
LiteRT 错误
这些适用于浏览器基于 TFLite 的 LiteRT 后端，而不适用于您页面中的 LiteRT.js。关于 LiteRT.js，请参阅框架错误。
GPU 或 NPU 请求在 CPU 上运行
问题
您请求了 GPU 或 NPU，但工作在 CPU 上运行，结果比预期的慢。
解决方法
LiteRT 后端使用 TFLite 委托来支持 GPU 和 NPU，而这些委托是可选的。如果所请求的委托在此平台上缺失或失败，执行会回退到 XNNPack CPU 路径，且不会引发错误。LiteRT 后端兼容性中的表格显示了每个平台使用哪个委托，以及哪些请求会回退到 CPU。
检查生成的 TFLite 模型
问题
您想查看浏览器根据您的 WebNN 图生成的 TFLite 模型。
解决方法
使用 --webnn-tflite-dump-model。该文件夹必须可从 GPU 进程沙盒访问，否则您必须使用 --no-sandbox 启动浏览器。
"%LOCALAPPDATA%\Google\Chrome SxS\Application\chrome.exe" --no-sandbox --webnn-tflite-dump-model=C:\temp\tflite_modelsCore ML 错误
在 macOS 上没有使用 Core ML 后端
问题
在 macOS 上，WebNN 没有使用 Core ML，GPU 和 NPU 请求比预期的慢。
解决方法
“Core ML backend for WebNN” 即 #webnn-coreml 标志，用于为 GPU 和 NPU 推理启用 Core ML，而 #webnn-coreml-explicit-gpu-or-npu 用于启用显式的 GPU 或 NPU 选择。Core ML 需要 Apple Silicon 上较新的 macOS。在 Intel Mac、较旧的 macOS 版本上，或者该功能被禁用时，WebNN 会回退到基于 TFLite 的后端。请查看浏览器兼容性表中 macOS 的表格。
检查生成的 Core ML 模型
问题
您想查看浏览器根据您的 WebNN 图生成的 Core ML 模型。
解决方法
使用 --webnn-coreml-dump-model。该文件夹必须可从 GPU 进程沙盒访问，否则您必须使用 --no-sandbox 启动浏览器。
/Applications/Google\ Chrome\ Canary.app/Contents/MacOS/Google\ Chrome\ Canary --no-sandbox --webnn-coreml-dump-model=/tmp/CoreMLModels特定 GPU 或 NPU 的问题
如果后端可以工作，但某个特定的 GPU 或 NPU 表现异常，例如 NPU 在 Windows 任务管理器中没有显示活动，或者驱动程序回滚损害了 GPU 性能，请参阅硬件错误。