MLOperand

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

Web 神经网络（WebNN）API 的 MLOperand 接口表示正在构建的计算图中的一个节点：图的输入、常量或某个操作的输出。操作数是符号化的——它们描述值的数据类型和形状，但不持有脚本可以读取的任何数据。

MLOperand 对象由 MLGraphBuilder 的方法创建，例如 input()、constant()，以及 add() 或 conv2d() 等每一个操作。操作数属于创建它的构建器，因此也属于该构建器的 MLContext；将其传递给其他构建器会抛出 TypeError。

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

Web IDL

web-idl


[SecureContext, Exposed=(Window, Worker)]
interface MLOperand {
  readonly attribute MLOperandDataType dataType;
  readonly attribute FrozenArray<unsigned long> shape;
};

dictionary MLOperatorOptions {
  USVString label = "";
};

typedef (bigint or unrestricted double) MLNumber;

构造函数

无。操作数由 MLGraphBuilder 的方法创建。

实例属性

dataType

只读的 MLOperandDataType 字符串，给出操作数的元素类型，例如 "float32"。

shape

只读的、冻结的 unsigned long 值数组，给出每个维度的大小。条目数量即为操作数的秩。标量的该数组为空（[]）。

由于操作输出的形状在构建图时就已计算出来，你可以在构建过程中检查 shape 以核对中间结果：

shape.js


const x = builder.input('x', { dataType: 'float32', shape: [1, 3, 224, 224] });
const y = builder.averagePool2d(x, { windowDimensions: [2, 2], strides: [2, 2] });
console.log(y.dataType, y.shape); // "float32" [1, 3, 112, 112]

实例方法

无。

MLOperandDescriptor

MLOperandDescriptor 字典描述操作数的数据类型和形状。它会被传递给 MLGraphBuilder.input()、MLGraphBuilder.constant() 和 MLContext.createConstantTensor()，并且是 MLTensorDescriptor 的基础。

web-idl


enum MLInputOperandLayout {
  "nchw",
  "nhwc"
};

enum MLOperandDataType {
  "float32",
  "float16",
  "int32",
  "uint32",
  "int64",
  "uint64",
  "int8",
  "uint8"
};

dictionary MLOperandDescriptor {
  required MLOperandDataType dataType;
  required sequence<[EnforceRange] unsigned long> shape;
};

成员	类型	描述
`dataType` （必需）	`MLOperandDataType`	操作数的数据类型。
`shape` （必需）	`sequence<unsigned long>`	维度列表。标量为空。

每个维度必须是大于零的整数（目前不允许大小为零的维度），且在 32 位有符号整数的范围内。元素总数也必须在该范围内，并且总字节长度不得超过实现的限制（参见 MLOpSupportLimits.maxTensorByteLength）。否则，接收该描述符的方法会抛出 TypeError。

描述符的字节长度是所有维度的乘积再乘以数据类型的元素大小。

MLOperandDataType

值	描述	元素大小	对应的 `ArrayBufferView`
`"float32"`	32 位 IEEE 754 浮点数	4 字节	`Float32Array`
`"float16"`	16 位 IEEE 754 浮点数	2 字节	`Float16Array`
`"int32"`	32 位有符号整数	4 字节	`Int32Array`
`"uint32"`	32 位无符号整数	4 字节	`Uint32Array`
`"int64"`	64 位有符号整数	8 字节	`BigInt64Array`
`"uint64"`	64 位无符号整数	8 字节	`BigUint64Array`
`"int8"`	8 位有符号整数	1 字节	`Int8Array`
`"uint8"`	8 位无符号整数；也用于逻辑操作的布尔结果	1 字节	`Uint8Array`

并非每个算子在每个平台上都支持所有数据类型。每个算子都会列出其允许的和必需的数据类型；使用 MLContext.opSupportLimits() 可以查询当前上下文支持的内容。

MLInputOperandLayout

4 维类图像张量的内存布局，用于依赖布局的算子，例如 conv2d()、convTranspose2d()、池化、instanceNormalization() 和 resample2d()。

值	描述
`"nchw"`	`[batches, channels, height, width]`（通道优先）
`"nhwc"`	`[batches, height, width, channels]`（通道在后）

当前平台偏好的布局由 MLOpSupportLimits.preferredInputLayout 报告。

MLOperatorOptions

MLOperatorOptions 字典是每个操作的选项字典的基础。每个操作都接受它，或者直接接受，或者通过诸如 MLConv2dOptions 之类的派生字典接受。

成员	类型	默认值	描述
`label`	`USVString`	`""`	算子的标识符。实现可以在错误消息和调试工具中使用它，既包括构建图期间的同步错误，也包括由 `build()` 报告的错误。

标签并不是自然语言字符串；请像对待变量名或错误代码一样对待它，例如 "mul#1234" 或 "encoder.layer3.attention.matmul"。

label.js


try {
  builder.matmul(a, b, { label: 'decoder.proj' });
} catch (e) {
  console.error(e.message); // 该消息可能会提到 "decoder.proj"。
}

MLNumber

MLNumber 是 bigint 和 unrestricted double 的联合类型，用于其类型取决于操作数数据类型的数值选项——例如 clamp() 的 minValue/maxValue、pad() 的 value，以及标量 constant(dataType, value) 重载。

单独使用 double 会损失大于 2⁵³ 的 64 位整数的精度，而 long long 无法容纳大于 2⁶³ 的值。实现会将 MLNumber 转换为相应的操作数数据类型：

对于整数类型，该值会被转换为该整数类型；使用 bigint（例如 2n ** 60n）可以保持完整的 64 位精度。
对于浮点类型，该值会被转换为最接近的可表示值。
超出目标类型范围的值会被截断。

mlnumber.js


const big = builder.constant('int64', 9007199254740993n); // 精确，超过 2^53。
const clamped = builder.clamp(x, { minValue: 0, maxValue: 6 }); // 转换为 x.dataType。

示例

在构建图时检查操作数

operands.js


const context = await navigator.ml.createContext();
const builder = new MLGraphBuilder(context);
 
const input = builder.input('input', { dataType: 'float32', shape: [1, 4] });
const weights = builder.constant(
  { dataType: 'float32', shape: [4, 2] },
  new Float32Array([1, 0, 0, 1, 1, 0, 0, 1]),
);
const scalar = builder.constant('float32', 0.5);
 
const product = builder.matmul(input, weights);
const output = builder.mul(product, scalar);
 
console.log(product.shape); // [1, 2]
console.log(scalar.shape);  // []（标量）
console.log(output.dataType); // "float32"

规范

规范	状态
Web 神经网络 API — `MLOperand` 接口	候选推荐草案
Web 神经网络 API — `MLOperandDescriptor` 字典	候选推荐草案

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

浏览器兼容性

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

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