navigator.ml

实验性： 这是一项实验性技术。在生产环境中使用前，请仔细检查浏览器兼容性表格。

Navigator 和 WorkerNavigator 接口的只读属性 ml 返回一个 ML 对象，它是 Web 神经网络（WebNN）API 的入口。

此特性仅在安全上下文（HTTPS 或 localhost）中可用，并且在主线程和 Web Worker 中均可使用。

Web IDL

web-idl


interface mixin NavigatorML {
  [SecureContext, SameObject] readonly attribute ML ml;
};
Navigator includes NavigatorML;
WorkerNavigator includes NavigatorML;

值

一个 ML 对象。由于该属性被标记为 [SameObject]，在给定的全局对象内每次访问该属性都会返回同一个 ML 对象。

描述

navigator.ml 提供对 ML 接口的访问，其 createContext() 方法用于创建 MLContext。通过该上下文，你可以使用 MLGraphBuilder 构建计算图，分配 MLTensor 对象，并在设备的 CPU、GPU 或 NPU 上运行推理。

Window： 可通过 window.navigator.ml 使用。
Worker： 可通过 WorkerNavigator 以 self.navigator.ml 的形式使用。在 Worker 中运行推理可使图编译和数据传输不占用主线程。
仅限安全上下文： 在不安全的上下文中（例如通过纯 HTTP 提供的页面），不会暴露 ml 属性，因此 'ml' in navigator 为 false。

权限策略

WebNN 的使用由标识字符串为 webnn 的权限策略特性控制。其默认允许列表为 'self'，因此同源文档默认可以使用 WebNN。跨源 iframe 必须被明确授予访问权限：

iframe.html


<iframe src="https://example.com/inference.html" allow="webnn"></iframe>

当文档不被允许使用该特性时，ml 属性仍然存在，但 ML.createContext() 会返回一个以 SecurityError DOMException 拒绝的 Promise，并且 MLGraphBuilder() 构造函数会抛出 SecurityError。

示例

特性检测

feature-detection.js


if ('ml' in navigator) {
  const context = await navigator.ml.createContext();
  console.log('WebNN is available.');
} else {
  console.log('WebNN is not supported in this browser.');
}

在 Worker 中使用 WebNN

main.js


const worker = new Worker('worker.js', { type: 'module' });
worker.postMessage({ a: [1, 2, 3, 4], b: [5, 6, 7, 8] });
worker.onmessage = (e) => console.log('Result:', e.data); // Float32Array [6, 8, 10, 12]

worker.js


self.onmessage = async (e) => {
  const context = await navigator.ml.createContext();
  const builder = new MLGraphBuilder(context);
  const desc = { dataType: 'float32', shape: [4] };
  const graph = await builder.build({
    c: builder.add(builder.input('a', desc), builder.input('b', desc)),
  });
 
  const [a, b, c] = await Promise.all([
    context.createTensor({ ...desc, writable: true }),
    context.createTensor({ ...desc, writable: true }),
    context.createTensor({ ...desc, readable: true }),
  ]);
  context.writeTensor(a, new Float32Array(e.data.a));
  context.writeTensor(b, new Float32Array(e.data.b));
  context.dispatch(graph, { a, b }, { c });
 
  self.postMessage(new Float32Array(await context.readTensor(c)));
};

规范

规范	状态
Web 神经网络 API — `navigator.ml`	候选推荐草案

最新的编辑草案可在 webmachinelearning.github.io/webnn 查看。

浏览器兼容性

WebNN 正在积极开发中，不同浏览器、操作系统和硬件的支持情况各不相同。

参见浏览器兼容性：WebNN API。