MLGraphBuilder 操作

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

Web 神经网络（WebNN）API 的操作是 MLGraphBuilder 接口的方法。每个操作接受一个或多个 MLOperand 参数（通常还带有一个选项字典），并返回一个描述结果的新 MLOperand（或操作数序列）。调用时操作并不会进行任何计算：它们只是向图中添加一个节点，由 build() 随后编译，并由 MLContext.dispatch() 执行。

本页记录了全部 95 个操作，并按类别分组。关于构建器本身（包括 input()、constant() 和 build()），请参阅 MLGraphBuilder。

概述

通用行为

以下规则适用于本页的每个操作，因此不会在各个条目中重复说明。

选项与标签

每个选项字典都派生自 MLOperatorOptions，因此都接受一个可选的 label 字符串。实现可以利用它让错误消息和调试输出更有用。选项参数始终是可选的，除非某个条目另有说明。

const y = builder.matmul(a, b, { label: 'decoder.proj' });

异常

操作会在调用时同步进行验证。除非某个条目列出了其他行为，否则操作会抛出：

• InvalidStateError DOMException

  构建器无法构建：已经调用过 build()，或者构建器的上下文已丢失。

• TypeError

  某个操作数由另一个 MLGraphBuilder 创建；某个操作数的数据类型不属于该操作的允许的数据类型；某个操作数的秩或形状对该操作无效（例如无法广播的形状，或超出有效范围的 axis）；或者某个选项值超出范围。

数据类型与秩

每个条目都有一个张量限制表格，每个操作数占一行（输出以斜体列出）：

• 允许的数据类型是规范允许的 MLOperandDataType 值。与 input 相同表示该操作数必须与另一个操作数具有相同的数据类型，任意表示允许所有数据类型。
• 必需的数据类型是每个实现至少必须支持的值。实现可以支持更多允许的类型，但不能少于必需的类型。仅使用必需类型的模型可以在各个实现之间移植。
• 允许的秩和必需的秩对维度数量的作用方式相同。N 表示任意秩。

当前上下文实际支持的数据类型和秩可在运行时通过 MLContext.opSupportLimits() 获得。返回的字典为每个操作提供一个成员，以方法名命名（例如 limits.conv2d 或 limits.add），其字典类型在各个条目中给出。

const limits = context.opSupportLimits();
const canUseFp16 = limits.softmax.input.dataTypes.includes('float16');
const maxRank = limits.add.a.rankRange.max;

广播

一些操作使用 NumPy 广播规则 组合不同形状的操作数。形状从末尾维度开始对齐，对于每一对维度，其大小要么相等，要么其中一个为 1。

• 可双向广播： 两个操作数都可以被拉伸。输出的秩是两个秩中较大的一个，每个输出维度是两个输入大小中较大的一个。用于逐元素二元操作和逻辑操作、prelu() 以及 where()。
• 可单向广播： 只有第一个操作数会被拉伸以匹配目标形状。用于 expand() 以及 gemm() 的 c 操作数。

逐元素二元操作

逐元素二元操作根据两个输入张量，一次一对元素地计算结果。输入必须可双向广播。

语法

add(a, b)
add(a, b, options)
// 对 sub()、mul()、div()、max()、min() 和 pow() 同理

参数

• a

  一个 MLOperand：第一个输入张量。

• b

  一个 MLOperand：第二个输入张量。

• options 可选

  一个 MLOperatorOptions 字典。

返回值

一个包含结果的 MLOperand。其秩为 a 和 b 的秩中较大的一个，每个维度为对应输入维度中较大的一个。

张量限制

支持限制键：add、sub、mul、div、max、min、pow（MLBinarySupportLimits）。

add()

逐元素加法：a + b。

sub()

逐元素减法：a - b。

mul()

逐元素乘法：a * b。

div()

逐元素除法：a / b。

max()

a 和 b 的逐元素最大值。

min()

a 和 b 的逐元素最小值。

pow()

逐元素幂运算：a 的每个元素的、对应 b 元素次幂。

示例

const a = builder.input('a', { dataType: 'float32', shape: [2, 3] });
const bias = builder.constant(
  { dataType: 'float32', shape: [3] }, new Float32Array([0.1, 0.2, 0.3]));
 
// bias 会沿第一个维度广播：输出形状为 [2, 3]。
const y = builder.add(a, bias);
console.log(y.shape); // [2, 3]

逐元素逻辑操作

比较和逻辑操作会生成一个 uint8 张量，其中每个元素为 1（真）或 0（假）。带有两个操作数的操作要求输入可双向广播。

语法

equal(a, b)            // notEqual, greater, greaterOrEqual, lesser, lesserOrEqual
logicalAnd(a, b)       // logicalOr, logicalXor
logicalNot(a)
isNaN(a)               // isInfinite
// 每个操作都接受一个可选的末尾 options 参数。

参数

• a

  一个 MLOperand：第一个（或唯一的）输入张量。

• b

  一个 MLOperand：第二个输入张量。logicalNot()、isNaN() 和 isInfinite() 不使用该参数。

• options 可选

  一个 MLOperatorOptions 字典。

返回值

一个数据类型为 uint8 的 MLOperand。对于双操作数的操作，其秩和维度遵循广播规则；对于单操作数的操作，其形状与 a 相同。

张量限制

equal()、notEqual()、greater()、greaterOrEqual()、lesser()、lesserOrEqual()：同名的支持限制键（MLBinarySupportLimits）。

logicalNot()：支持限制键 logicalNot（MLLogicalNotSupportLimits，包含成员 a 和 output）。

logicalAnd()、logicalOr()、logicalXor()：同名的支持限制键（MLBinarySupportLimits）。

isNaN()、isInfinite()：同名的支持限制键（MLLogicalNotSupportLimits）。

equal()

当 a 等于 b 时为 1，否则为 0。

notEqual()

当 a 不等于 b 时为 1，否则为 0。

greater()

当 a 大于 b 时为 1，否则为 0。

greaterOrEqual()

当 a 大于或等于 b 时为 1，否则为 0。

lesser()

当 a 小于 b 时为 1，否则为 0。

lesserOrEqual()

当 a 小于或等于 b 时为 1，否则为 0。

logicalNot()

a 的逻辑非。

logicalAnd()

a 和 b 的逻辑与。

logicalOr()

a 和 b 的逻辑或。

logicalXor()

a 和 b 的逻辑异或。

isNaN()

当 a 的元素不是数字（NaN）时为 1，否则为 0。

isInfinite()

当 a 的元素为正无穷或负无穷时为 1，否则为 0。

示例

// 仅保留大于阈值的值，其余位置置零。
const x = builder.input('x', { dataType: 'float32', shape: [4] });
const threshold = builder.constant('float32', 0.5);
const zero = builder.constant('float32', 0);
 
const mask = builder.greater(x, threshold);   // uint8：1 或 0
const y = builder.where(mask, x, zero);       // 参见 where()

逐元素一元操作

逐元素一元操作对一个输入张量的每个元素应用一个函数。输出与输入具有相同的形状。

语法

abs(input)
abs(input, options)
// 对 ceil()、cos()、erf()、exp()、floor()、identity()、log()、neg()、
// reciprocal()、roundEven()、sign()、sin()、sqrt() 和 tan() 同理

参数

• input

  一个 MLOperand：输入张量。

• options 可选

  一个 MLOperatorOptions 字典。

返回值

一个与 input 形状相同的 MLOperand。其数据类型与 input 的相同。

张量限制

支持限制键：方法名（MLSingleInputSupportLimits）。

abs()、neg()、sign()

ceil()、cos()、erf()、exp()、floor()、log()、reciprocal()、roundEven()、sin()、sqrt()、tan()

identity()

abs()

每个元素的绝对值。

ceil()

每个元素的向上取整：大于或等于它的最小整数。

cos()

每个元素的余弦（以弧度为单位）。

erf()

每个元素的误差函数 。

exp()

指数，即 e 的每个元素次幂。

floor()

每个元素的向下取整：小于或等于它的最大整数。

identity()

将输入的每个元素原样复制到输出。可用它将输入或常量操作数暴露为图的输出，或为某个操作数提供一个独立的节点。

log()

每个元素的自然对数。

neg()

每个元素的数值相反数（-x）。

reciprocal()

每个元素的倒数（1 / x）。

roundEven()

将每个元素舍入到最接近的整数，恰为一半时舍入到最接近的偶数值（“银行家舍入”）。例如，[0.1, 0.9, 1.1, 1.9, -3.5, -2.5, -1.5, 1.5, 2.5, 3.5] 得到 [0, 1, 1, 2, -4, -2, -2, 2, 2, 4]。

sign()

每个元素的符号：大于零时为 1，小于零时为 -1，否则为 0。

sin()

每个元素的正弦（以弧度为单位）。

sqrt()

每个元素的平方根。

tan()

每个元素的正切（以弧度为单位）。

示例

const x = builder.input('x', { dataType: 'float32', shape: [3] });
 
// 由一元操作和归约操作构建的向量欧几里得范数。
const norm = builder.sqrt(builder.reduceSum(builder.mul(x, x)));
console.log(norm.shape); // []

激活函数

激活函数逐元素应用（softmax() 和 prelu() 除外，下文另有说明），通常放在卷积或矩阵乘法之后。除非另有说明，每个激活函数接受一个输入张量，并返回形状和数据类型相同的张量。

以下所有激活函数都在同名的支持限制键下使用 MLSingleInputSupportLimits，prelu() 除外，它有自己的字典。

elu()

指数线性单元：max(0, x) + alpha * (exp(min(0, x)) - 1)。

elu(input)
elu(input, options)

• input

  一个 MLOperand。

• options 可选

  一个 MLEluOptions 字典（派生自 MLOperatorOptions）。

gelu()

高斯误差线性单元：0.5 * x * (1 + erf(x / sqrt(2)))。

gelu(input)
gelu(input, options)

hardSigmoid()

sigmoid 函数的一种非平滑近似，计算开销更低：max(0, min(1, alpha * x + beta))。

hardSigmoid(input)
hardSigmoid(input, options)

MLHardSigmoidOptions 字典接受：

hardSwish()

MobileNetV3 引入的函数：x * max(0, min(6, x + 3)) / 6。

hardSwish(input)
hardSwish(input, options)

leakyRelu()

带泄漏的修正线性函数：max(0, x) + alpha * min(0, x)。

leakyRelu(input)
leakyRelu(input, options)

MLLeakyReluOptions 字典接受：

linear()

线性函数：alpha * x + beta。

linear(input)
linear(input, options)

MLLinearOptions 字典接受：

prelu()

参数化修正线性函数：max(0, x) + slope * min(0, x)。与 leakyRelu() 不同，斜率是一个张量，通常在训练期间学得。slope 必须可双向广播到 input，输出的秩为两个秩中较大的一个。

prelu(input, slope)
prelu(input, slope, options)

• input

  一个 MLOperand：输入张量。

• slope

  一个 MLOperand：斜率张量。

支持限制键 prelu（MLPreluSupportLimits，包含成员 input、slope 和 output）。

relu()

修正线性函数：max(0, x)。

relu(input)
relu(input, options)

sigmoid()

sigmoid 函数：1 / (exp(-x) + 1)。

sigmoid(input)
sigmoid(input, options)

softmax()

输入沿给定轴的 softmax  值，使沿该轴的值均为正且和为 1。

softmax(input, axis)
softmax(input, axis, options)

• input

  一个 MLOperand：N 维输入张量。

• axis

  一个 unsigned long：计算 softmax 所沿的维度。它必须在 0 到 N-1 的范围内，其中 N 为 input 的秩。

softplus()

softplus 函数：ln(1 + exp(x))。

softplus(input)
softplus(input, options)

softsign()

softsign 函数：x / (1 + abs(x))。

softsign(input)
softsign(input, options)

tanh()

双曲正切：(exp(2 * x) - 1) / (exp(2 * x) + 1)。

tanh(input)
tanh(input, options)

示例

const logits = builder.input('logits', { dataType: 'float32', shape: [1, 10] });
const probabilities = builder.softmax(logits, 1);
 
const x = builder.input('x', { dataType: 'float32', shape: [1, 64] });
const slope = builder.constant({ dataType: 'float32', shape: [64] }, slopeData);
const activated = builder.prelu(x, slope);

卷积操作

卷积会在 4 维输入张量上滑动一个滤波器（卷积核）。输入、输出和滤波器的内存布局由 inputLayout 和 filterLayout 选项指定。平台处理效率最高的布局由 MLOpSupportLimits.preferredInputLayout 报告。

这两个操作在各自的支持限制键下都使用 MLConv2dSupportLimits，其成员为 input、filter、bias 和 output。

conv2d()

对 4 维 input 张量与 4 维 filter 张量计算 2 维卷积。

conv2d(input, filter)
conv2d(input, filter, options)

参数

• input

  一个 MLOperand：输入的 4 维张量，按照 inputLayout 解释。

• filter

  一个 MLOperand：滤波器 4 维张量，按照 filterLayout 和 groups 解释。

• options 可选

  一个 MLConv2dOptions 字典（派生自 MLOperatorOptions）：

filterLayout 的取值：

返回值

一个 MLOperand：保存卷积结果的 4 维张量，按照 inputLayout 布局。每个空间输出维度的计算方式如下（除法向下取整）：

outputSize = 1 + (inputSize - (filterSize - 1) * dilation - 1 + beginningPadding + endingPadding) / stride

张量限制

示例

const input = builder.input('input', { dataType: 'float32', shape: [1, 3, 224, 224] });
const filter = builder.constant({ dataType: 'float32', shape: [32, 3, 3, 3] }, filterData);
const bias = builder.constant({ dataType: 'float32', shape: [32] }, biasData);
 
const y = builder.conv2d(input, filter, {
  strides: [2, 2],
  padding: [1, 1, 1, 1],
  bias,
});
console.log(y.shape); // [1, 32, 112, 112]

convTranspose2d()

对 4 维 input 张量与 4 维 filter 张量计算 2 维转置卷积（有时称为反卷积）。它常用于对特征图进行上采样。

convTranspose2d(input, filter)
convTranspose2d(input, filter, options)

参数

• input

  一个 MLOperand：输入的 4 维张量，按照 inputLayout 解释。

• filter

  一个 MLOperand：滤波器 4 维张量，按照 filterLayout 和 groups 解释。

• options 可选

  一个 MLConvTranspose2dOptions 字典。它包含 conv2d() 中描述的 padding、strides、dilations、groups、inputLayout 和 bias 成员，此外还有：

filterLayout 的取值：

返回值

一个 MLOperand：保存结果的 4 维张量，按照 inputLayout 布局。除非给出了 outputSizes，否则每个空间输出维度（向下取整）为：

outputSize = (inputSize - 1) * stride + (filterSize - 1) * dilation + 1 - beginningPadding - endingPadding + outputPadding

张量限制

池化操作

池化通过为滑动窗口的每个位置计算一个值来缩减 4 维张量的空间维度。这三个操作共享相同的选项，区别仅在于应用于每个窗口内元素的函数。

语法

averagePool2d(input)
averagePool2d(input, options)
// 对 l2Pool2d() 和 maxPool2d() 同理

参数

• input

  一个 MLOperand：输入的 4 维张量，按照 layout 解释。

• options 可选

  一个 MLPool2dOptions 字典（派生自 MLOperatorOptions）：

返回值

一个 MLOperand：按照 layout 布局的 4 维张量。除非给出了 outputSizes，否则每个空间维度的计算方式如下：

outputSize = floor(1 + (inputSize - windowSize + beginningPadding + endingPadding) / stride)

当 outputShapeRounding 为 "ceil" 时，用 ceil 替换 floor。

张量限制

支持限制键：averagePool2d、l2Pool2d、maxPool2d（MLSingleInputSupportLimits）。

averagePool2d()、l2Pool2d()

maxPool2d()

averagePool2d()

计算每个窗口内各值的平均值。

l2Pool2d()

对每个窗口应用 L2 范数：即其元素平方和的平方根。

maxPool2d()

计算每个窗口内各值的最大值。

示例

const x = builder.input('x', { dataType: 'float32', shape: [1, 64, 56, 56] });
 
const halved = builder.maxPool2d(x, { windowDimensions: [2, 2], strides: [2, 2] });
console.log(halved.shape); // [1, 64, 28, 28]
 
// 全局平均池化：窗口默认为完整的空间大小。
const pooled = builder.averagePool2d(x);
console.log(pooled.shape); // [1, 64, 1, 1]

归一化操作

归一化操作会重新缩放激活值，使其具有受控的均值和方差。它们的区别在于统计量是在哪些值上计算的。

batchNormalization()

使用批归一化 对输入进行归一化。训练期间在批次上计算得到的每个特征的均值和方差，在推理时作为操作数提供：(input - mean) / sqrt(variance + epsilon) * scale + bias。

batchNormalization(input, mean, variance)
batchNormalization(input, mean, variance, options)

参数

• input

  一个 MLOperand：输入的 N 维张量。

• mean

  一个 MLOperand：输入特征均值的 1 维张量，其大小等于输入中由 axis 指定的维度的大小。

• variance

  一个 MLOperand：输入特征方差的 1 维张量，大小相同。

• options 可选

  一个 MLBatchNormalizationOptions 字典：

返回值

一个 MLOperand：归一化后的张量，与 input 的形状相同。

张量限制

支持限制键 batchNormalization（MLBatchNormalizationSupportLimits，其成员为 input、mean、variance、scale、bias 和 output）。

instanceNormalization()

使用实例归一化 对输入进行归一化。与批归一化不同，均值和方差是针对每个单独样本的每个特征即时计算的。

instanceNormalization(input)
instanceNormalization(input, options)

参数

• input

  一个 MLOperand：输入的 4 维张量。

• options 可选

  一个 MLInstanceNormalizationOptions 字典：

返回值

一个 MLOperand：归一化后的 4 维张量，与 input 的形状相同。

张量限制

支持限制键 instanceNormalization（MLNormalizationSupportLimits，其成员为 input、scale、bias 和 output）。

layerNormalization()

使用层归一化 对输入进行归一化。均值和方差是针对每个单独样本，在其各特征上即时计算的。它被广泛用于 Transformer 模型。

layerNormalization(input)
layerNormalization(input, options)

参数

• input

  一个 MLOperand：输入的 N 维张量。

• options 可选

  一个 MLLayerNormalizationOptions 字典：

返回值

一个 MLOperand：归一化后的张量，与 input 的形状相同。

张量限制

支持限制键 layerNormalization（MLNormalizationSupportLimits）。

示例

const hidden = builder.input('hidden', { dataType: 'float32', shape: [1, 128, 768] });
const gamma = builder.constant({ dataType: 'float32', shape: [768] }, gammaData);
const beta = builder.constant({ dataType: 'float32', shape: [768] }, betaData);
 
// 仅在最后一个维度上进行归一化。
const normalized = builder.layerNormalization(hidden, {
  axes: [2],
  scale: gamma,
  bias: beta,
  epsilon: 1e-12,
});

矩阵操作

gemm()

计算 BLAS 中的通用矩阵乘法 ：alpha * A * B + beta * C。A 是形状为 [M, K] 的 2 维张量（转置时为 [K, M]），B 的形状为 [K, N]（或 [N, K]），C 可单向广播为 [M, N]。

gemm(a, b)
gemm(a, b, options)

参数

• a

  一个 MLOperand：第一个 2 维张量，形状为 [M, K]，如果 aTranspose 为 true 则为 [K, M]。

• b

  一个 MLOperand：第二个 2 维张量，形状为 [K, N]，如果 bTranspose 为 true 则为 [N, K]。

• options 可选

  一个 MLGemmOptions 字典：

返回值

一个 MLOperand：形状为 [M, N] 的 2 维张量。

张量限制

支持限制键 gemm（MLGemmSupportLimits，其成员为 a、b、c 和 output）。

示例

// 全连接层：y = x * W^T + bias
const x = builder.input('x', { dataType: 'float32', shape: [8, 512] });
const w = builder.constant({ dataType: 'float32', shape: [1000, 512] }, weights);
const bias = builder.constant({ dataType: 'float32', shape: [1000] }, biasData);
 
const y = builder.gemm(x, w, { c: bias, bTranspose: true });
console.log(y.shape); // [8, 1000]

matmul()

计算两个张量的矩阵乘积。对于形状为 [M, K] 和 [K, N] 的 2 维输入，输出的形状为 [M, N]。如果任一输入的维度多于两个，则其最后两个维度被视为一组矩阵的堆叠；前导（批次）维度必须可双向广播，输出的秩为两个输入秩中较大的一个。

matmul(a, b)
matmul(a, b, options)

参数

• a

  一个 MLOperand：第一个张量，至少为 2 维。

• b

  一个 MLOperand：第二个张量，至少为 2 维。其倒数第二个维度的大小必须等于 a 最后一个维度的大小。

• options 可选

  一个 MLOperatorOptions 字典。

返回值

一个保存矩阵乘积的 MLOperand。

张量限制

支持限制键 matmul（MLBinarySupportLimits）。

示例

// 12 个注意力头的注意力分数：[1, 12, 128, 64] x [1, 12, 64, 128]
const q = builder.input('q', { dataType: 'float32', shape: [1, 12, 128, 64] });
const kT = builder.input('kT', { dataType: 'float32', shape: [1, 12, 64, 128] });
const scores = builder.matmul(q, kT);
console.log(scores.shape); // [1, 12, 128, 128]

triangular()

返回矩阵的上三角或下三角部分。如果输入的维度多于两个，则将其视为一批矩阵，结果的形状与输入相同。保留部分之外的元素被置为零。它通常用于构建因果注意力掩码。

triangular(input)
triangular(input, options)

参数

• input

  一个 MLOperand：输入张量，至少为 2 维。

• options 可选

  一个 MLTriangularOptions 字典：

返回值

一个与 input 形状相同的 MLOperand。

张量限制

支持限制键 triangular（MLSingleInputSupportLimits）。

示例

// input: [[7, 1, 2],
//         [9, 4, 8],
//         [2, 6, 3]]
const input = builder.constant(
  { dataType: 'float32', shape: [3, 3] },
  new Float32Array([7, 1, 2, 9, 4, 8, 2, 6, 3]));
 
builder.triangular(input);
// 上三角：            [[7, 1, 2], [0, 4, 8], [0, 0, 3]]
builder.triangular(input, { diagonal: 1 });
// 上三角，不包含主对角线： [[0, 1, 2], [0, 0, 8], [0, 0, 0]]
builder.triangular(input, { upper: false });
// 下三角：            [[7, 0, 0], [9, 4, 0], [2, 6, 3]]
builder.triangular(input, { upper: false, diagonal: 1 });
// 下三角，外加上方一条对角线：     [[7, 1, 0], [9, 4, 8], [2, 6, 3]]

归约操作

归约操作会将张量的一个或多个维度各自折叠为单个值，例如通过求和或取最大值。

argMax() 和 argMin()

argMax() 和 argMin() 返回沿某个轴的最大值或最小值的索引。当出现相同的值时，返回哪个索引由实现定义。

argMax(input, axis)
argMax(input, axis, options)
argMin(input, axis)
argMin(input, axis, options)

参数

• input

  一个 MLOperand：输入的 N 维张量。

• axis

  一个 unsigned long：要归约的维度，范围为 0 到 N-1。

• options 可选

  一个 MLArgMinMaxOptions 字典：

返回值

一个数据类型为 outputDataType 的 MLOperand，如果 keepDimensions 为 true，其秩等于输入的秩，否则为输入的秩减 1。取值范围为 0 到 S-1，其中 S 是输入沿 axis 的大小。如果 S 无法用 outputDataType 表示，则会抛出 TypeError。

张量限制

支持限制键 argMax、argMin（MLSingleInputSupportLimits）。

argMax()

沿 axis 的最大值的索引。

argMin()

沿 axis 的最小值的索引。

cumulativeSum()

沿某个轴计算值的累积（前缀）和。

cumulativeSum(input, axis)
cumulativeSum(input, axis, options)

参数

• input

  一个 MLOperand：输入张量。

• axis

  一个 unsigned long：求和所沿的轴，范围为 0 到 N-1。

• options 可选

  一个 MLCumulativeSumOptions 字典：

返回值

一个与 input 形状相同的 MLOperand。

张量限制

支持限制键 cumulativeSum（MLSingleInputSupportLimits）。

归约函数

这十个 reduce*() 操作共享同一个签名和同一组选项。每个操作都会对被归约维度上的值应用一个归约函数。

reduceSum(input)
reduceSum(input, options)
// 对 reduceL1()、reduceL2()、reduceLogSum()、reduceLogSumExp()、
// reduceMax()、reduceMean()、reduceMin()、reduceProduct() 和 reduceSumSquare() 同理

参数

• input

  一个 MLOperand：输入张量。

• options 可选

  一个 MLReduceOptions 字典：

返回值

一个秩为 0 到输入秩的 MLOperand，具体取决于 axes 和 keepDimensions。对标量进行归约会返回标量。

张量限制

支持限制键：方法名（MLSingleInputSupportLimits）。

reduceL1()、reduceSum()、reduceSumSquare()

reduceL2()、reduceLogSum()、reduceLogSumExp()、reduceMean()

reduceMax()、reduceMin()

reduceProduct()

reduceL1()

L1 范数 ：绝对值之和。

reduceL2()

L2 范数 ：平方和的平方根。

reduceLogSum()

各值之和的自然对数。

reduceLogSumExp()

各值的指数之和的自然对数。

reduceMax()

各值的最大值。

reduceMean()

各值的平均值。

reduceMin()

各值的最小值。

reduceProduct()

各值的乘积。

reduceSum()

各值之和。

reduceSumSquare()

各值的平方和。

示例

const x = builder.input('x', { dataType: 'float32', shape: [2, 3, 4] });
 
const total = builder.reduceSum(x);                                  // shape []
const perRow = builder.reduceMean(x, { axes: [2] });                 // shape [2, 3]
const kept = builder.reduceMax(x, { axes: [1, 2], keepDimensions: true }); // shape [2, 1, 1]
const best = builder.argMax(x, 2);                                   // int32, shape [2, 3]

形状与数据移动操作

这些操作会改变张量数据的类型、形状或排列方式，而（基本上）不改变数据本身的值。

cast()

将输入的每个元素转换为另一种数据类型。

cast(input, dataType)
cast(input, dataType, options)

• input

  一个 MLOperand：输入张量。

• dataType

  一个 MLOperandDataType：目标数据类型。

• options 可选

  一个 MLOperatorOptions 字典。

返回值： 一个 MLOperand，其形状与 input 相同，数据类型为 dataType。

支持限制键 cast（MLSingleInputSupportLimits）。

// 将 uint8 比较掩码转换为 float32，以便进行乘法运算。
const mask = builder.greater(x, threshold);
const maskF32 = builder.cast(mask, 'float32');
const y = builder.mul(x, maskF32);

clamp()

将输入的每个元素截断到最小值与最大值之间的范围内。

clamp(input)
clamp(input, options)

• input

  一个 MLOperand：输入张量。

• options 可选

  一个 MLClampOptions 字典：

两个限制值都会被类型转换为 input 的数据类型。

返回值： 一个 MLOperand，其形状与 input 相同。

支持限制键 clamp（MLSingleInputSupportLimits）。

// ReLU6
const relu6 = builder.clamp(x, { minValue: 0, maxValue: 6 });

concat()

沿某个轴拼接一组张量。

concat(inputs, axis)
concat(inputs, axis, options)

• inputs

  一个 MLOperand 对象的序列。除被拼接的维度外，所有张量的形状必须相同，且数据类型必须相同。

• axis

  一个 unsigned long：拼接所沿的维度，取值范围为 0 到 N-1。

• options 可选

  一个 MLOperatorOptions 字典。

返回值： 一个 MLOperand，其形状与各输入相同，只是沿 axis 的大小为各输入沿该轴大小之和。

支持限制键 concat（MLConcatSupportLimits，包含成员 inputs 和 output）。

const a = builder.input('a', { dataType: 'float32', shape: [1, 3] });
const b = builder.input('b', { dataType: 'float32', shape: [1, 5] });
console.log(builder.concat([a, b], 1).shape); // [1, 8]

expand()

按照 NumPy 广播规则，将输入中大小为 1 的每个维度扩展为更大的尺寸。输入必须可单向广播到 newShape：其每个维度要么为 1，要么等于 newShape 中对应的维度。

expand(input, newShape)
expand(input, newShape, options)

• input

  一个 MLOperand：输入张量。

• newShape

  一个 unsigned long 的序列：要扩展到的形状。

• options 可选

  一个 MLOperatorOptions 字典。

返回值： 一个 MLOperand，其形状为 newShape。

支持限制键 expand（MLSingleInputSupportLimits）。

pad()

通过在每个维度的边缘添加值来扩充张量。

pad(input, beginningPadding, endingPadding)
pad(input, beginningPadding, endingPadding, options)

• input

  一个 MLOperand：输入张量。

• beginningPadding

  一个长度为 N（input 的秩）的 unsigned long 序列：在每个维度中，内容之前要添加多少个值。

• endingPadding

  一个长度为 N 的 unsigned long 序列：在每个维度中，内容之后要添加多少个值。

• options 可选

  一个 MLPadOptions 字典：

MLPaddingMode 的取值：

返回值： 一个 MLOperand，其每个维度的大小为 beginningPadding + inputSize + endingPadding。

支持限制键 pad（MLSingleInputSupportLimits）。

// input: [[1, 2, 3],
//         [4, 5, 6]]
const input = builder.constant(
  { dataType: 'float32', shape: [2, 3] }, new Float32Array([1, 2, 3, 4, 5, 6]));
const begin = [1, 2];
const end = [1, 2];
 
builder.pad(input, begin, end);
// "constant": [[0,0,0,0,0,0,0], [0,0,1,2,3,0,0], [0,0,4,5,6,0,0], [0,0,0,0,0,0,0]]
 
builder.pad(input, begin, end, { mode: 'edge' });
// "edge":     [[1,1,1,2,3,3,3], [1,1,1,2,3,3,3], [4,4,4,5,6,6,6], [4,4,4,5,6,6,6]]
 
builder.pad(input, begin, end, { mode: 'reflection' });
// "reflection": [[6,5,4,5,6,5,4], [3,2,1,2,3,2,1], [6,5,4,5,6,5,4], [3,2,1,2,3,2,1]]

reshape()

改变张量的逻辑形状，而无需复制或改变其内容。newShape 所隐含的元素数量必须等于 input 中的元素数量。

reshape(input, newShape)
reshape(input, newShape, options)

• input

  一个 MLOperand：输入张量。

• newShape

  一个 unsigned long 的序列：输出的形状。

• options 可选

  一个 MLOperatorOptions 字典。

返回值： 一个 MLOperand，其值与 input 相同，形状为 newShape。

支持限制键 reshape（MLSingleInputSupportLimits）。

const x = builder.input('x', { dataType: 'float32', shape: [1, 64, 7, 7] });
const flat = builder.reshape(x, [1, 64 * 7 * 7]);

reverse()

沿给定的轴反转元素的顺序。

reverse(input)
reverse(input, options)

• input

  一个 MLOperand：输入张量。

• options 可选

  一个 MLReverseOptions 字典：

返回值： 一个 MLOperand，其形状与 input 相同。

支持限制键 reverse（MLSingleInputSupportLimits）。

slice()

从输入中提取子张量。

slice(input, starts, sizes)
slice(input, starts, sizes, options)

• input

  一个 MLOperand：输入张量。

• starts

  一个长度为 N 的 unsigned long 序列：在每个维度中开始切片的索引。每个值必须在 0 到该维度大小减 1 的范围内。

• sizes

  一个长度为 N 的 unsigned long 序列：在每个维度中要取的元素数量。大小不能为 0，且 start + size 不能超过该维度的大小。

• options 可选

  一个 MLSliceOptions 字典：

返回值： 一个 MLOperand，其秩与 input 相同，包含所选区域。

支持限制键 slice（MLSingleInputSupportLimits）。

const x = builder.input('x', { dataType: 'float32', shape: [4, 6] });
// 第 1 至 2 行，第 0 至 3 列。
const part = builder.slice(x, [1, 0], [2, 4]);
console.log(part.shape); // [2, 4]

split()

沿某个轴将张量拆分为若干子张量。

split(input, splits)
split(input, splits, options)

• input

  一个 MLOperand：输入张量。

• splits

  一个 unsigned long，或一个 unsigned long 的序列。若为数字，则表示大小相等的输出个数，且必须能整除 input 沿 axis 的大小。若为序列，则给出每个输出沿 axis 的大小，且其总和必须等于 input 沿 axis 的大小。

• options 可选

  一个 MLSplitOptions 字典：

返回值： 一个 MLOperand 的序列。如果 splits 是数字，则序列包含相应数量的元素，每个元素的形状与 input 相同，只是沿 axis 的大小为原大小除以 splits。如果 splits 是序列，则每个条目对应一个输出，第 i 个输出沿 axis 的大小为 splits[i]。

支持限制键 split（MLSplitSupportLimits，包含成员 input 和 outputs）。

const qkv = builder.input('qkv', { dataType: 'float32', shape: [1, 128, 2304] });
const [q, k, v] = builder.split(qkv, 3, { axis: 2 });
console.log(q.shape); // [1, 128, 768]

tile()

沿每个维度将张量重复给定的次数。

tile(input, repetitions)
tile(input, repetitions, options)

• input

  一个 MLOperand：输入 N 维张量。

• repetitions

  一个 unsigned long 的序列：每个维度要重复的次数。其长度必须等于 input 的秩；对于应保持原大小的维度，请使用 1。

• options 可选

  一个 MLOperatorOptions 字典。

返回值： 一个 MLOperand，其每个维度的大小为输入大小乘以重复次数。

支持限制键 tile（MLSingleInputSupportLimits）。

transpose()

排列（置换）张量的各个维度。

transpose(input)
transpose(input, options)

• input

  一个 MLOperand：输入 N 维张量。

• options 可选

  一个 MLTransposeOptions 字典：

返回值： 一个 MLOperand，其第 i 个维度为输入的第 permutation[i] 个维度。

支持限制键 transpose（MLSingleInputSupportLimits）。

// NHWC 转 NCHW
const nhwc = builder.input('x', { dataType: 'float32', shape: [1, 224, 224, 3] });
const nchw = builder.transpose(nhwc, { permutation: [0, 3, 1, 2] });
console.log(nchw.shape); // [1, 3, 224, 224]

收集与散布操作

这些操作按照 索引 张量给出的位置，从张量中读取值，或向张量中写入值。索引值必须为 int32、uint32 或 int64 类型，并且可以为负数以便从维度末尾开始计数：有效值位于 -S（含）到 S（不含）的范围内，其中 S 是被索引维度的大小。

gather()

根据索引，沿某个轴收集输入的值。

gather(input, indices)
gather(input, indices, options)

• input

  一个 MLOperand：要从中收集的 N 维张量。

• indices

  一个 MLOperand：指向 input 的 axis 维度的索引张量。

• options 可选

  一个 MLGatherOptions 字典：

返回值： 一个秩为 rank(input) + rank(indices) - 1 的 MLOperand。

支持限制键 gather（MLGatherSupportLimits，包含成员 input、indices 和 output）。

// 嵌入查找：30000 x 768 的表，16 个 token id。
const table = builder.constant({ dataType: 'float32', shape: [30000, 768] }, embeddings);
const ids = builder.input('ids', { dataType: 'int32', shape: [16] });
const vectors = builder.gather(table, ids, { axis: 0 });
console.log(vectors.shape); // [16, 768]

gatherElements()

沿某个轴收集输入中的单个元素：每个输出元素都读取自 input 中的某个位置，该位置沿 axis 的索引由 indices 的对应元素给出。

gatherElements(input, indices)
gatherElements(input, indices, options)

• input

  一个 MLOperand：要从中收集的 N 维张量。

• indices

  一个 MLOperand：索引，其秩与 input 相同。

• options 可选

  一个 MLGatherOptions 字典（参见 gather()）；axis 默认为 0。

返回值： 一个 MLOperand，其秩与 input 相同。

支持限制键 gatherElements（MLGatherSupportLimits）。

gatherND()

使用完整坐标收集输入的切片。indices 的最后一个维度保存坐标：形状为 [10, 1] 的 indices 张量保存 10 个单轴索引，形状为 [4, 3] 则保存 4 个三维坐标。

gatherND(input, indices)
gatherND(input, indices, options)

• input

  一个 MLOperand：要从中收集的 N 维张量。

• indices

  一个 MLOperand：指向 input 的坐标。每个值必须在 -S 到 S-1 的范围内（S 是对应输入维度的大小）。

• options 可选

  一个 MLOperatorOptions 字典。

返回值： 一个秩为 rank(input) + rank(indices) - shape(indices)[-1] - 1 的 MLOperand。

支持限制键 gatherND（MLGatherSupportLimits）。

scatterElements()

将 updates 中的值写入 input 的副本，写入位置为沿某个轴由 indices 给出的位置。

scatterElements(input, indices, updates)
scatterElements(input, indices, updates, options)

• input

  一个 MLOperand：用于初始化输出的 N 维张量。

• indices

  一个 MLOperand：沿 axis 要写入的位置。

• updates

  一个 MLOperand：新的值，其形状与 indices 相同。

• options 可选

  一个 MLScatterOptions 字典：

返回值： 一个 MLOperand，其形状与 input 相同。

支持限制键 scatterElements（MLScatterSupportLimits，包含成员 input、indices、updates 和 output）。

scatterND()

使用完整坐标，将 updates 中的切片写入 input 的副本。indices 的最后一个维度保存坐标，与 gatherND() 相同。

scatterND(input, indices, updates)
scatterND(input, indices, updates, options)

• input

  一个 MLOperand：用于初始化输出的 N 维张量。

• indices

  一个 MLOperand：输出中要写入的坐标。

• updates

  一个 MLOperand：要写入的新值或切片。

• options 可选

  一个 MLOperatorOptions 字典。

返回值： 一个 MLOperand，其形状与 input 相同。

支持限制键 scatterND（MLScatterSupportLimits）。

where()

根据 condition（非零为真，零为假），逐元素地从 trueValue 或 falseValue 中选取值。这三个张量必须可双向广播。condition 通常是比较或逻辑操作的输出。

where(condition, trueValue, falseValue)
where(condition, trueValue, falseValue, options)

• condition

  一个 MLOperand：条件张量。

• trueValue

  一个 MLOperand：条件为真处所选取的值。

• falseValue

  一个 MLOperand：条件为假处所选取的值。

• options 可选

  一个 MLOperatorOptions 字典。

返回值： 一个 MLOperand，其秩为各输入秩中的最大值，其各维度为各输入对应维度中的最大值。

支持限制键 where（MLWhereSupportLimits，包含成员 condition、trueValue、falseValue 和 output）。

// 因果注意力掩码：保留下三角，其余部分填充为 -inf。
const scores = builder.input('scores', { dataType: 'float32', shape: [1, 12, 128, 128] });
const ones = builder.constant({ dataType: 'uint8', shape: [128, 128] }, new Uint8Array(128 * 128).fill(1));
const lower = builder.triangular(ones, { upper: false });
const masked = builder.where(lower, scores, builder.constant('float32', -Infinity));

量化操作

量化将浮点值映射为低精度整数并可还原，从而减小模型体积并降低内存带宽占用。两个操作都接受 scale 和 zeroPoint 张量，它们可以比输入更小，因为它们可按块广播：它们的秩必须与 input 相同，且 input 的每个维度必须是 scale 对应维度的整数倍。这使得逐张量、逐通道和逐块量化成为可能。

缩放因子（scale）的值必须为正且非零；否则行为由实现定义（可能得到正确结果、错误结果或编译失败）。

dequantizeLinear()

将量化后的整数张量转换为浮点：output = (input - zeroPoint) * scale。

dequantizeLinear(input, scale, zeroPoint)
dequantizeLinear(input, scale, zeroPoint, options)

• input

  一个 MLOperand：量化后的输入张量。

• scale

  一个 MLOperand：用于相乘的缩放因子，可与 input 按块广播。

• zeroPoint

  一个 MLOperand：用于相减的零点，形状与 scale 相同。

• options 可选

  一个 MLOperatorOptions 字典。

返回值： 一个 MLOperand，包含反量化后的值，形状与 input 相同，数据类型与 scale 相同。

支持限制键 dequantizeLinear（MLQuantizeDequantizeLinearSupportLimits，成员为 input、scale、zeroPoint 和 output）。

quantizeLinear()

将浮点张量转换为量化后的整数张量。例如，对于 uint8 输出：output = clamp(roundEven(input / scale) + zeroPoint, 0, 255)。

quantizeLinear(input, scale, zeroPoint)
quantizeLinear(input, scale, zeroPoint, options)

• input

  一个 MLOperand：浮点输入张量。

• scale

  一个 MLOperand：用于相除的缩放因子，可与 input 按块广播。

• zeroPoint

  一个 MLOperand：用于相加的零点，形状与 scale 相同。其数据类型决定输出类型。

• options 可选

  一个 MLOperatorOptions 字典。

返回值： 一个 MLOperand，包含量化后的值，形状与 input 相同，数据类型与 zeroPoint 相同。

支持限制键 quantizeLinear（MLQuantizeDequantizeLinearSupportLimits）。

// 逐张量 int8 量化往返。
const x = builder.input('x', { dataType: 'float32', shape: [1, 16] });
const scale = builder.constant({ dataType: 'float32', shape: [1, 1] }, new Float32Array([0.05]));
const zeroPoint = builder.constant({ dataType: 'int8', shape: [1, 1] }, new Int8Array([0]));
 
const q = builder.quantizeLinear(x, scale, zeroPoint);   // int8
const restored = builder.dequantizeLinear(q, scale, zeroPoint); // float32

循环神经网络操作

循环操作逐个时间步处理输入序列，同时携带隐藏状态。每种网络类型都有两种形式：遍历所有时间步的完整操作（gru()、lstm()），以及只计算单个时间步的单元操作（gruCell()、lstmCell()）。

共用的枚举：

在下面的形状中，对于 "forward" 和 "backward"，numDirections 为 1；对于 "both"，则为 2。

gru()

在序列上运行门控循环单元（GRU） 网络，使用更新门、重置门和新门。

gru(input, weight, recurrentWeight, steps, hiddenSize)
gru(input, weight, recurrentWeight, steps, hiddenSize, options)

参数

• input

  一个 MLOperand：形状为 [steps, batchSize, inputSize] 的 3 维张量。

• weight

  一个 MLOperand：形状为 [numDirections, 3 * hiddenSize, inputSize] 的 3 维张量。第二个维度中的门顺序遵循 layout。

• recurrentWeight

  一个 MLOperand：形状为 [numDirections, 3 * hiddenSize, hiddenSize] 的 3 维张量。

• steps

  一个 unsigned long：时间步的数量。必须大于 0。

• hiddenSize

  一个 unsigned long：隐藏状态中的特征数量。

• options 可选

  一个 MLGruOptions 字典：

返回值

一个 MLOperand 序列。第一个是形状为 [numDirections, batchSize, hiddenSize] 的 3 维张量：最后一个时间步的输出。如果 returnSequence 为 true，第二个是形状为 [steps, numDirections, batchSize, hiddenSize] 的 4 维张量，包含每个时间步的输出。

张量限制

支持限制键 gru（MLGruSupportLimits，成员为 input、weight、recurrentWeight、bias、recurrentBias、initialHiddenState、output0 和 output1）。

gruCell()

计算 GRU 网络的单个时间步。

gruCell(input, weight, recurrentWeight, hiddenState, hiddenSize)
gruCell(input, weight, recurrentWeight, hiddenState, hiddenSize, options)

参数

• input

  一个 MLOperand：形状为 [batchSize, inputSize] 的 2 维张量。

• weight

  一个 MLOperand：形状为 [3 * hiddenSize, inputSize] 的 2 维张量。

• recurrentWeight

  一个 MLOperand：形状为 [3 * hiddenSize, hiddenSize] 的 2 维张量。

• hiddenState

  一个 MLOperand：形状为 [batchSize, hiddenSize] 的 2 维张量。

• hiddenSize

  一个 unsigned long：隐藏状态中的特征数量。

• options 可选

  一个 MLGruCellOptions 字典，包含 gru() 中描述的成员 resetAfter、layout 和 activations，以及：

返回值

一个 MLOperand：形状为 [batchSize, hiddenSize] 的 2 维张量，包含新的隐藏状态。

张量限制

支持限制键 gruCell（MLGruCellSupportLimits，成员为 input、weight、recurrentWeight、hiddenState、bias、recurrentBias 和 output）。

lstm()

在序列上运行长短期记忆（LSTM） 网络，使用输入门、输出门、遗忘门和单元门。

lstm(input, weight, recurrentWeight, steps, hiddenSize)
lstm(input, weight, recurrentWeight, steps, hiddenSize, options)

参数

• input

  一个 MLOperand：形状为 [steps, batchSize, inputSize] 的 3 维张量。

• weight

  一个 MLOperand：形状为 [numDirections, 4 * hiddenSize, inputSize] 的 3 维张量。门的顺序遵循 layout。

• recurrentWeight

  一个 MLOperand：形状为 [numDirections, 4 * hiddenSize, hiddenSize] 的 3 维张量。

• steps

  一个 unsigned long：时间步的数量。必须大于 0。

• hiddenSize

  一个 unsigned long：隐藏状态中的特征数量。

• options 可选

  一个 MLLstmOptions 字典：