Scan

Scan - 24

版本

  • 名称: Scan (GitHub)

  • : main

  • 起始版本24

  • 函数: False

  • 支持级别: SupportType.COMMON

  • 形状推断: True

此版本的操作符已可用于版本 24 及以上

摘要

Scan 可用于迭代一个或多个 scan_input 张量,构造零个或多个 scan_output 张量。它结合了通用递归、函数式编程中的 scan、fold、map 和 zip 等概念,旨在实现 RNN 类结构在序列到序列处理中的泛化。其他张量(此处称为 state_variables)可用于在从一个元素迭代到另一个元素时携带状态(类似于 RNN 中的隐藏状态,在循环的上下文中也称为循环依赖)。许多常见用法涉及单个 scan_input 张量(可获得类似于 scan、fold 和 map 的功能)。当使用多个 scan_input 时,会获得类似于 zip 的行为。

属性 body 必须是一个图,指定每次迭代要执行的计算。它接收 state_variables 的当前值和 scan_inputs 的当前迭代元素作为输入。它必须返回 state_variables 的(更新后的)值和零个或多个 scan_output_element 张量。scan_output_element 张量的值在所有迭代中被连接起来,以生成 scan 结构的 scan_output 值(类似于 RNN 类结构的连接的中间隐藏状态值)。所有输出张量(state_variables 和 scan_output_element 张量)在循环的每次迭代中都要求具有相同的形状(为实现高效内存分配而施加的限制)。

请注意,传递给 body 子图的迭代元素没有序列轴。它的秩比相应 scan_input 的秩少一。

scan 操作返回 state_variables 的最终值以及 scan_outputs。

可选属性 scan_input_directions 指定每个 scan input 的方向(前向或后向)。如果省略此属性,所有序列都将按前向方向扫描。可以通过在 scan_inputs 中指定相同的张量输入两次来执行双向扫描,一次指定前向方向,一次指定后向方向。

该操作的 scan_output 是通过在每次迭代中连接 body 生成的 scan_output_element 值来产生的。可选属性 scan_output_directions 指定了在每次迭代中构建 scan_output 的方向(通过将 scan_output_element 追加或前置到 scan_output)的扫描方向。如果省略此属性,scan_output_element 将在每次迭代中被追加到 scan_output。

可选属性 scan_input_axes 指定要扫描的每个 scan_input 的轴。如果省略,则每个 scan_input 将在轴 0 上进行扫描。例如,如果轴 0 是批次轴,轴 1 是要扫描的时间轴,则指定轴值为 1。请注意,扫描非零轴可能不如扫描轴零的效率高。

可选属性 scan_output_axes 指定了累积 scan_outputs 的轴。例如,如果轴 1 是输入和输出都要扫描的时间轴,则指定 scan_input 轴和 scan_output 轴值为 1。

请注意,由于 ONNX 限制,操作的最后一个参数才能是可变数量的,initial-states 和 scan-inputs 被一起列为一个输入参数。类似地,final-states 和 scan-outputs 被一起列为一个输出参数。num_scan_inputs 属性指示 scan_inputs 的数量 M。

的行为

Scan <
    num_scan_inputs = m,
    body = loop-body,
    scan_input_axes = [axis_1, ..., axis_m]
> (init_1, ..., init_n, scan_1, ..., scan_m)

等同于以下伪代码

// scan_i.shape[axis_i] denotes the (max) sequence-length of scan_i
// scan_i.shape[axis_i] is required to be equal to scan_j.shape[axis_j] for all i,j.
sequence_length = scan_1.shape[axis_1];

// initialize state-variables
st_1 = init_1; ... st_n = init_n;
// initialize scan-output variables: [] denotes an empty tensor
scan_out_1 = []; ...; scan_out_k = [];
// identify number of iterations:

// execute loop
for (int t = 0; t < sequence_length; ++t) {
    // generate the scan-input elements: the notation T<axis=k>[t] indicates the sub-tensor
    // of rank one less than T obtained by indexing T at position t along axis k.
    si_1 = scan_1<axis=axis_1>[t];
    ... ;
    si_m = scan_m<axis=axis_m>[t];
    // execute loop-body
    st_1, ..., st_n, so_1, ..., so_k = loop-body(st_1, ..., st_n, si_1, ..., si_m)
    // accumulate the scan-output elements
    scan_out_1 = Concat<axis=0>(scan_out_1, so_1); ... ; scan_out_k = Concat<axis=0>(scan_out_k, so_k);
}

return st_1, ..., st_n, scan_out_1, ..., scan_out_k;

示例用法:使用 Scan 编码 RNN

以下示例展示了如何将一个简单的 RNN(基于输入张量 %X、权重张量 %Wi、递归权重张量 %Ri、偏置张量 %Wbi 和 %Rbi,以及初始隐藏状态 %H_0)编码为 ScanLoop。请注意,loop-body 是一个嵌套图,它直接计算

的值是在外部图中计算的,它们需要作为额外的 state_variables 传入。

graph rnn-encoding {
  %H_0 = ...
  %X = ...
  %Y_h, %Y = Scan[body = <graph rnn-cell-1>, num_scan_inputs=1](%H_0, %X)
  return %Y, %Y_h
}

graph rnn-cell-1 (
  %H_tminus1[FLOAT, tensor]
  %X_t[FLOAT, tensor]
) {
  %Wi = ...
  %Ri = ...
  %Wbi = ...
  %Rbi = ...
  %t1 = X_t * (Wi^T)
  %t2 = H_tminus1*(Ri^T)
  %t3 = Add(%t1, %t2)
  %t4 = Add(%t3, %Wbi)
  %t5 = Add(%t4, %Rbi)
  %Ht = Tanh(%t5)
  %Accumulate = Identity(%Ht)
  return %Ht, %Accumulate
}

属性

  • body - GRAPH (必需)

    每次迭代运行的图。它有 N+M 个输入:(循环状态变量……,scan_input_elts……)。它有 N+K 个输出:(循环状态变量……,scan_output_elts……)。每个 scan_output 是通过在每次循环迭代结束时连接指定的 scan_output_elt 值而创建的。如果这些值在循环迭代之间的维度发生变化,则会报错。

  • num_scan_inputs - INT (必需)

    指定 scan_inputs 数量 M 的属性。

  • scan_input_axes - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 的要扫描的轴(序列轴)。如果省略,则对于每个 scan_input,将使用 0 作为扫描轴。轴的负值表示从后往前计算维度。可接受的范围是 [-r, r-1],其中 r = rank(input)。

  • scan_input_directions - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 张量的扫描方向:0 表示前向方向,1 表示后向方向。如果省略,则所有 scan_input 张量都将按前向方向扫描。

  • scan_output_axes - INTS :

    可选的 K 个标志列表。列表中的第 i 个元素指定第 i 个 scan_output 的轴。scan outputs 沿着指定的轴累积。如果省略,则对于每个 scan_output,将使用 0 作为扫描轴。轴的负值表示从后往前计算维度。可接受的范围是 [-r, r-1]。

  • scan_output_directions - INTS :

    可选的 K 个标志列表,每个 scan_output 一个。列表中的第 i 个元素指定第 i 个 scan_output 在每次迭代中是通过追加还是前置新值来构建:0 表示追加,1 表示前置。如果省略,所有 scan_output 张量都将通过在每次迭代中追加值来生成。

输入

输入数量介于 1 到 2147483647 之间。

  • initial_state_and_scan_inputs (可变数量) - V

    循环 N 个状态变量的初始值,后跟 M 个 scan_inputs

输出

1 到 2147483647 个输出之间。

  • final_state_and_scan_outputs (可变数量) - V

    循环 N 个状态变量的最终值,后跟 K 个 scan_outputs

类型约束

  • V 在 ( tensor(bfloat16), tensor(bool), tensor(complex128), tensor(complex64), tensor(double), tensor(float), tensor(float16), tensor(float4e2m1), tensor(float8e4m3fn), tensor(float8e4m3fnuz), tensor(float8e5m2), tensor(float8e5m2fnuz), tensor(float8e8m0), tensor(int16), tensor(int32), tensor(int4), tensor(int64), tensor(int8), tensor(string), tensor(uint16), tensor(uint32), tensor(uint4), tensor(uint64), tensor(uint8) )

    IRv12 及之前的 Tensor 类型。

Scan - 23

版本

  • 名称: Scan (GitHub)

  • : main

  • 起始版本23

  • 函数: False

  • 支持级别: SupportType.COMMON

  • 形状推断: True

此版本的操作符已可用于版本 23 及以上

摘要

Scan 可用于迭代一个或多个 scan_input 张量,构造零个或多个 scan_output 张量。它结合了通用递归、函数式编程中的 scan、fold、map 和 zip 等概念,旨在实现 RNN 类结构在序列到序列处理中的泛化。其他张量(此处称为 state_variables)可用于在从一个元素迭代到另一个元素时携带状态(类似于 RNN 中的隐藏状态,在循环的上下文中也称为循环依赖)。许多常见用法涉及单个 scan_input 张量(可获得类似于 scan、fold 和 map 的功能)。当使用多个 scan_input 时,会获得类似于 zip 的行为。

属性 body 必须是一个图,指定每次迭代要执行的计算。它接收 state_variables 的当前值和 scan_inputs 的当前迭代元素作为输入。它必须返回 state_variables 的(更新后的)值和零个或多个 scan_output_element 张量。scan_output_element 张量的值在所有迭代中被连接起来,以生成 scan 结构的 scan_output 值(类似于 RNN 类结构的连接的中间隐藏状态值)。所有输出张量(state_variables 和 scan_output_element 张量)在循环的每次迭代中都要求具有相同的形状(为实现高效内存分配而施加的限制)。

请注意,传递给 body 子图的迭代元素没有序列轴。它的秩比相应 scan_input 的秩少一。

scan 操作返回 state_variables 的最终值以及 scan_outputs。

可选属性 scan_input_directions 指定每个 scan input 的方向(前向或后向)。如果省略此属性,所有序列都将按前向方向扫描。可以通过在 scan_inputs 中指定相同的张量输入两次来执行双向扫描,一次指定前向方向,一次指定后向方向。

该操作的 scan_output 是通过在每次迭代中连接 body 生成的 scan_output_element 值来产生的。可选属性 scan_output_directions 指定了在每次迭代中构建 scan_output 的方向(通过将 scan_output_element 追加或前置到 scan_output)的扫描方向。如果省略此属性,scan_output_element 将在每次迭代中被追加到 scan_output。

可选属性 scan_input_axes 指定要扫描的每个 scan_input 的轴。如果省略,则每个 scan_input 将在轴 0 上进行扫描。例如,如果轴 0 是批次轴,轴 1 是要扫描的时间轴,则指定轴值为 1。请注意,扫描非零轴可能不如扫描轴零的效率高。

可选属性 scan_output_axes 指定了累积 scan_outputs 的轴。例如,如果轴 1 是输入和输出都要扫描的时间轴,则指定 scan_input 轴和 scan_output 轴值为 1。

请注意,由于 ONNX 限制,操作的最后一个参数才能是可变数量的,initial-states 和 scan-inputs 被一起列为一个输入参数。类似地,final-states 和 scan-outputs 被一起列为一个输出参数。num_scan_inputs 属性指示 scan_inputs 的数量 M。

的行为

Scan <
    num_scan_inputs = m,
    body = loop-body,
    scan_input_axes = [axis_1, ..., axis_m]
> (init_1, ..., init_n, scan_1, ..., scan_m)

等同于以下伪代码

// scan_i.shape[axis_i] denotes the (max) sequence-length of scan_i
// scan_i.shape[axis_i] is required to be equal to scan_j.shape[axis_j] for all i,j.
sequence_length = scan_1.shape[axis_1];

// initialize state-variables
st_1 = init_1; ... st_n = init_n;
// initialize scan-output variables: [] denotes an empty tensor
scan_out_1 = []; ...; scan_out_k = [];
// identify number of iterations:

// execute loop
for (int t = 0; t < sequence_length; ++t) {
    // generate the scan-input elements: the notation T<axis=k>[t] indicates the sub-tensor
    // of rank one less than T obtained by indexing T at position t along axis k.
    si_1 = scan_1<axis=axis_1>[t];
    ... ;
    si_m = scan_m<axis=axis_m>[t];
    // execute loop-body
    st_1, ..., st_n, so_1, ..., so_k = loop-body(st_1, ..., st_n, si_1, ..., si_m)
    // accumulate the scan-output elements
    scan_out_1 = Concat<axis=0>(scan_out_1, so_1); ... ; scan_out_k = Concat<axis=0>(scan_out_k, so_k);
}

return st_1, ..., st_n, scan_out_1, ..., scan_out_k;

示例用法:使用 Scan 编码 RNN

以下示例展示了如何将一个简单的 RNN(基于输入张量 %X、权重张量 %Wi、递归权重张量 %Ri、偏置张量 %Wbi 和 %Rbi,以及初始隐藏状态 %H_0)编码为 ScanLoop。请注意,loop-body 是一个嵌套图,它直接计算

的值是在外部图中计算的,它们需要作为额外的 state_variables 传入。

graph rnn-encoding {
  %H_0 = ...
  %X = ...
  %Y_h, %Y = Scan[body = <graph rnn-cell-1>, num_scan_inputs=1](%H_0, %X)
  return %Y, %Y_h
}

graph rnn-cell-1 (
  %H_tminus1[FLOAT, tensor]
  %X_t[FLOAT, tensor]
) {
  %Wi = ...
  %Ri = ...
  %Wbi = ...
  %Rbi = ...
  %t1 = X_t * (Wi^T)
  %t2 = H_tminus1*(Ri^T)
  %t3 = Add(%t1, %t2)
  %t4 = Add(%t3, %Wbi)
  %t5 = Add(%t4, %Rbi)
  %Ht = Tanh(%t5)
  %Accumulate = Identity(%Ht)
  return %Ht, %Accumulate
}

属性

  • body - GRAPH (必需)

    每次迭代运行的图。它有 N+M 个输入:(循环状态变量……,scan_input_elts……)。它有 N+K 个输出:(循环状态变量……,scan_output_elts……)。每个 scan_output 是通过在每次循环迭代结束时连接指定的 scan_output_elt 值而创建的。如果这些值在循环迭代之间的维度发生变化,则会报错。

  • num_scan_inputs - INT (必需)

    指定 scan_inputs 数量 M 的属性。

  • scan_input_axes - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 的要扫描的轴(序列轴)。如果省略,则对于每个 scan_input,将使用 0 作为扫描轴。轴的负值表示从后往前计算维度。可接受的范围是 [-r, r-1],其中 r = rank(input)。

  • scan_input_directions - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 张量的扫描方向:0 表示前向方向,1 表示后向方向。如果省略,则所有 scan_input 张量都将按前向方向扫描。

  • scan_output_axes - INTS :

    可选的 K 个标志列表。列表中的第 i 个元素指定第 i 个 scan_output 的轴。scan outputs 沿着指定的轴累积。如果省略,则对于每个 scan_output,将使用 0 作为扫描轴。轴的负值表示从后往前计算维度。可接受的范围是 [-r, r-1]。

  • scan_output_directions - INTS :

    可选的 K 个标志列表,每个 scan_output 一个。列表中的第 i 个元素指定第 i 个 scan_output 在每次迭代中是通过追加还是前置新值来构建:0 表示追加,1 表示前置。如果省略,所有 scan_output 张量都将通过在每次迭代中追加值来生成。

输入

输入数量介于 1 到 2147483647 之间。

  • initial_state_and_scan_inputs (可变数量) - V

    循环 N 个状态变量的初始值,后跟 M 个 scan_inputs

输出

1 到 2147483647 个输出之间。

  • final_state_and_scan_outputs (可变数量) - V

    循环 N 个状态变量的最终值,后跟 K 个 scan_outputs

类型约束

  • V 在 ( tensor(bfloat16), tensor(bool), tensor(complex128), tensor(complex64), tensor(double), tensor(float), tensor(float16), tensor(float4e2m1), tensor(float8e4m3fn), tensor(float8e4m3fnuz), tensor(float8e5m2), tensor(float8e5m2fnuz), tensor(int16), tensor(int32), tensor(int4), tensor(int64), tensor(int8), tensor(string), tensor(uint16), tensor(uint32), tensor(uint4), tensor(uint64), tensor(uint8) )

    IRv11 及之前的 Tensor 类型。

Scan - 21

版本

  • 名称: Scan (GitHub)

  • : main

  • since_version: 21

  • 函数: False

  • 支持级别: SupportType.COMMON

  • 形状推断: True

此版本的操作符自 版本 21 起可用。

摘要

Scan 可用于迭代一个或多个 scan_input 张量,构造零个或多个 scan_output 张量。它结合了通用递归、函数式编程中的 scan、fold、map 和 zip 等概念,旨在实现 RNN 类结构在序列到序列处理中的泛化。其他张量(此处称为 state_variables)可用于在从一个元素迭代到另一个元素时携带状态(类似于 RNN 中的隐藏状态,在循环的上下文中也称为循环依赖)。许多常见用法涉及单个 scan_input 张量(可获得类似于 scan、fold 和 map 的功能)。当使用多个 scan_input 时,会获得类似于 zip 的行为。

属性 body 必须是一个图,指定每次迭代要执行的计算。它接收 state_variables 的当前值和 scan_inputs 的当前迭代元素作为输入。它必须返回 state_variables 的(更新后的)值和零个或多个 scan_output_element 张量。scan_output_element 张量的值在所有迭代中被连接起来,以生成 scan 结构的 scan_output 值(类似于 RNN 类结构的连接的中间隐藏状态值)。所有输出张量(state_variables 和 scan_output_element 张量)在循环的每次迭代中都要求具有相同的形状(为实现高效内存分配而施加的限制)。

请注意,传递给 body 子图的迭代元素没有序列轴。它的秩比相应 scan_input 的秩少一。

scan 操作返回 state_variables 的最终值以及 scan_outputs。

可选属性 scan_input_directions 指定每个 scan input 的方向(前向或后向)。如果省略此属性,所有序列都将按前向方向扫描。可以通过在 scan_inputs 中指定相同的张量输入两次来执行双向扫描,一次指定前向方向,一次指定后向方向。

该操作的 scan_output 是通过在每次迭代中连接 body 生成的 scan_output_element 值来产生的。可选属性 scan_output_directions 指定了在每次迭代中构建 scan_output 的方向(通过将 scan_output_element 追加或前置到 scan_output)的扫描方向。如果省略此属性,scan_output_element 将在每次迭代中被追加到 scan_output。

可选属性 scan_input_axes 指定要扫描的每个 scan_input 的轴。如果省略,则每个 scan_input 将在轴 0 上进行扫描。例如,如果轴 0 是批次轴,轴 1 是要扫描的时间轴,则指定轴值为 1。请注意,扫描非零轴可能不如扫描轴零的效率高。

可选属性 scan_output_axes 指定了累积 scan_outputs 的轴。例如,如果轴 1 是输入和输出都要扫描的时间轴,则指定 scan_input 轴和 scan_output 轴值为 1。

请注意,由于 ONNX 限制,操作的最后一个参数才能是可变数量的,initial-states 和 scan-inputs 被一起列为一个输入参数。类似地,final-states 和 scan-outputs 被一起列为一个输出参数。num_scan_inputs 属性指示 scan_inputs 的数量 M。

的行为

Scan <
    num_scan_inputs = m,
    body = loop-body,
    scan_input_axes = [axis_1, ..., axis_m]
> (init_1, ..., init_n, scan_1, ..., scan_m)

等同于以下伪代码

// scan_i.shape[axis_i] denotes the (max) sequence-length of scan_i
// scan_i.shape[axis_i] is required to be equal to scan_j.shape[axis_j] for all i,j.
sequence_length = scan_1.shape[axis_1];

// initialize state-variables
st_1 = init_1; ... st_n = init_n;
// initialize scan-output variables: [] denotes an empty tensor
scan_out_1 = []; ...; scan_out_k = [];
// identify number of iterations:

// execute loop
for (int t = 0; t < sequence_length; ++t) {
    // generate the scan-input elements: the notation T<axis=k>[t] indicates the sub-tensor
    // of rank one less than T obtained by indexing T at position t along axis k.
    si_1 = scan_1<axis=axis_1>[t];
    ... ;
    si_m = scan_m<axis=axis_m>[t];
    // execute loop-body
    st_1, ..., st_n, so_1, ..., so_k = loop-body(st_1, ..., st_n, si_1, ..., si_m)
    // accumulate the scan-output elements
    scan_out_1 = Concat<axis=0>(scan_out_1, so_1); ... ; scan_out_k = Concat<axis=0>(scan_out_k, so_k);
}

return st_1, ..., st_n, scan_out_1, ..., scan_out_k;

示例用法:使用 Scan 编码 RNN

以下示例展示了如何将一个简单的 RNN(基于输入张量 %X、权重张量 %Wi、递归权重张量 %Ri、偏置张量 %Wbi 和 %Rbi,以及初始隐藏状态 %H_0)编码为 ScanLoop。请注意,loop-body 是一个嵌套图,它直接计算

的值是在外部图中计算的,它们需要作为额外的 state_variables 传入。

graph rnn-encoding {
  %H_0 = ...
  %X = ...
  %Y_h, %Y = Scan[body = <graph rnn-cell-1>, num_scan_inputs=1](%H_0, %X)
  return %Y, %Y_h
}

graph rnn-cell-1 (
  %H_tminus1[FLOAT, tensor]
  %X_t[FLOAT, tensor]
) {
  %Wi = ...
  %Ri = ...
  %Wbi = ...
  %Rbi = ...
  %t1 = X_t * (Wi^T)
  %t2 = H_tminus1*(Ri^T)
  %t3 = Add(%t1, %t2)
  %t4 = Add(%t3, %Wbi)
  %t5 = Add(%t4, %Rbi)
  %Ht = Tanh(%t5)
  %Accumulate = Identity(%Ht)
  return %Ht, %Accumulate
}

属性

  • body - GRAPH (必需)

    每次迭代运行的图。它有 N+M 个输入:(循环状态变量……,scan_input_elts……)。它有 N+K 个输出:(循环状态变量……,scan_output_elts……)。每个 scan_output 是通过在每次循环迭代结束时连接指定的 scan_output_elt 值而创建的。如果这些值在循环迭代之间的维度发生变化,则会报错。

  • num_scan_inputs - INT (必需)

    指定 scan_inputs 数量 M 的属性。

  • scan_input_axes - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 的要扫描的轴(序列轴)。如果省略,则对于每个 scan_input,将使用 0 作为扫描轴。轴的负值表示从后往前计算维度。可接受的范围是 [-r, r-1],其中 r = rank(input)。

  • scan_input_directions - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 张量的扫描方向:0 表示前向方向,1 表示后向方向。如果省略,则所有 scan_input 张量都将按前向方向扫描。

  • scan_output_axes - INTS :

    可选的 K 个标志列表。列表中的第 i 个元素指定第 i 个 scan_output 的轴。scan outputs 沿着指定的轴累积。如果省略,则对于每个 scan_output,将使用 0 作为扫描轴。轴的负值表示从后往前计算维度。可接受的范围是 [-r, r-1]。

  • scan_output_directions - INTS :

    可选的 K 个标志列表,每个 scan_output 一个。列表中的第 i 个元素指定第 i 个 scan_output 在每次迭代中是通过追加还是前置新值来构建:0 表示追加,1 表示前置。如果省略,所有 scan_output 张量都将通过在每次迭代中追加值来生成。

输入

输入数量介于 1 到 2147483647 之间。

  • initial_state_and_scan_inputs (可变数量) - V

    循环 N 个状态变量的初始值,后跟 M 个 scan_inputs

输出

1 到 2147483647 个输出之间。

  • final_state_and_scan_outputs (可变数量) - V

    循环 N 个状态变量的最终值,后跟 K 个 scan_outputs

类型约束

  • V 在 ( tensor(bfloat16), tensor(bool), tensor(complex128), tensor(complex64), tensor(double), tensor(float), tensor(float16), tensor(float8e4m3fn), tensor(float8e4m3fnuz), tensor(float8e5m2), tensor(float8e5m2fnuz), tensor(int16), tensor(int32), tensor(int4), tensor(int64), tensor(int8), tensor(string), tensor(uint16), tensor(uint32), tensor(uint4), tensor(uint64), tensor(uint8) )

    IRv10 及之前的 Tensor 类型。

Scan - 19

版本

  • 名称: Scan (GitHub)

  • : main

  • since_version: 19

  • 函数: False

  • 支持级别: SupportType.COMMON

  • 形状推断: True

此版本的操作符自 版本 19 起可用。

摘要

Scan 可用于迭代一个或多个 scan_input 张量,构造零个或多个 scan_output 张量。它结合了通用递归、函数式编程中的 scan、fold、map 和 zip 等概念,旨在实现 RNN 类结构在序列到序列处理中的泛化。其他张量(此处称为 state_variables)可用于在从一个元素迭代到另一个元素时携带状态(类似于 RNN 中的隐藏状态,在循环的上下文中也称为循环依赖)。许多常见用法涉及单个 scan_input 张量(可获得类似于 scan、fold 和 map 的功能)。当使用多个 scan_input 时,会获得类似于 zip 的行为。

属性 body 必须是一个图,指定每次迭代要执行的计算。它接收 state_variables 的当前值和 scan_inputs 的当前迭代元素作为输入。它必须返回 state_variables 的(更新后的)值和零个或多个 scan_output_element 张量。scan_output_element 张量的值在所有迭代中被连接起来,以生成 scan 结构的 scan_output 值(类似于 RNN 类结构的连接的中间隐藏状态值)。所有输出张量(state_variables 和 scan_output_element 张量)在循环的每次迭代中都要求具有相同的形状(为实现高效内存分配而施加的限制)。

请注意,传递给 body 子图的迭代元素没有序列轴。它的秩比相应 scan_input 的秩少一。

scan 操作返回 state_variables 的最终值以及 scan_outputs。

可选属性 scan_input_directions 指定每个 scan input 的方向(前向或后向)。如果省略此属性,所有序列都将按前向方向扫描。可以通过在 scan_inputs 中指定相同的张量输入两次来执行双向扫描,一次指定前向方向,一次指定后向方向。

该操作的 scan_output 是通过在每次迭代中连接 body 生成的 scan_output_element 值来产生的。可选属性 scan_output_directions 指定了在每次迭代中构建 scan_output 的方向(通过将 scan_output_element 追加或前置到 scan_output)的扫描方向。如果省略此属性,scan_output_element 将在每次迭代中被追加到 scan_output。

可选属性 scan_input_axes 指定要扫描的每个 scan_input 的轴。如果省略,则每个 scan_input 将在轴 0 上进行扫描。例如,如果轴 0 是批次轴,轴 1 是要扫描的时间轴,则指定轴值为 1。请注意,扫描非零轴可能不如扫描轴零的效率高。

可选属性 scan_output_axes 指定了累积 scan_outputs 的轴。例如,如果轴 1 是输入和输出都要扫描的时间轴,则指定 scan_input 轴和 scan_output 轴值为 1。

请注意,由于 ONNX 限制,操作的最后一个参数才能是可变数量的,initial-states 和 scan-inputs 被一起列为一个输入参数。类似地,final-states 和 scan-outputs 被一起列为一个输出参数。num_scan_inputs 属性指示 scan_inputs 的数量 M。

的行为

Scan <
    num_scan_inputs = m,
    body = loop-body,
    scan_input_axes = [axis_1, ..., axis_m]
> (init_1, ..., init_n, scan_1, ..., scan_m)

等同于以下伪代码

// scan_i.shape[axis_i] denotes the (max) sequence-length of scan_i
// scan_i.shape[axis_i] is required to be equal to scan_j.shape[axis_j] for all i,j.
sequence_length = scan_1.shape[axis_1];

// initialize state-variables
st_1 = init_1; ... st_n = init_n;
// initialize scan-output variables: [] denotes an empty tensor
scan_out_1 = []; ...; scan_out_k = [];
// identify number of iterations:

// execute loop
for (int t = 0; t < sequence_length; ++t) {
    // generate the scan-input elements: the notation T<axis=k>[t] indicates the sub-tensor
    // of rank one less than T obtained by indexing T at position t along axis k.
    si_1 = scan_1<axis=axis_1>[t];
    ... ;
    si_m = scan_m<axis=axis_m>[t];
    // execute loop-body
    st_1, ..., st_n, so_1, ..., so_k = loop-body(st_1, ..., st_n, si_1, ..., si_m)
    // accumulate the scan-output elements
    scan_out_1 = Concat<axis=0>(scan_out_1, so_1); ... ; scan_out_k = Concat<axis=0>(scan_out_k, so_k);
}

return st_1, ..., st_n, scan_out_1, ..., scan_out_k;

示例用法:使用 Scan 编码 RNN

以下示例展示了如何将一个简单的 RNN(基于输入张量 %X、权重张量 %Wi、递归权重张量 %Ri、偏置张量 %Wbi 和 %Rbi,以及初始隐藏状态 %H_0)编码为 ScanLoop。请注意,loop-body 是一个嵌套图,它直接计算

的值是在外部图中计算的,它们需要作为额外的 state_variables 传入。

graph rnn-encoding {
  %H_0 = ...
  %X = ...
  %Y_h, %Y = Scan[body = <graph rnn-cell-1>, num_scan_inputs=1](%H_0, %X)
  return %Y, %Y_h
}

graph rnn-cell-1 (
  %H_tminus1[FLOAT, tensor]
  %X_t[FLOAT, tensor]
) {
  %Wi = ...
  %Ri = ...
  %Wbi = ...
  %Rbi = ...
  %t1 = X_t * (Wi^T)
  %t2 = H_tminus1*(Ri^T)
  %t3 = Add(%t1, %t2)
  %t4 = Add(%t3, %Wbi)
  %t5 = Add(%t4, %Rbi)
  %Ht = Tanh(%t5)
  %Accumulate = Identity(%Ht)
  return %Ht, %Accumulate
}

属性

  • body - GRAPH (必需)

    每次迭代运行的图。它有 N+M 个输入:(循环状态变量……,scan_input_elts……)。它有 N+K 个输出:(循环状态变量……,scan_output_elts……)。每个 scan_output 是通过在每次循环迭代结束时连接指定的 scan_output_elt 值而创建的。如果这些值在循环迭代之间的维度发生变化,则会报错。

  • num_scan_inputs - INT (必需)

    指定 scan_inputs 数量 M 的属性。

  • scan_input_axes - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 的要扫描的轴(序列轴)。如果省略,则对于每个 scan_input,将使用 0 作为扫描轴。轴的负值表示从后往前计算维度。可接受的范围是 [-r, r-1],其中 r = rank(input)。

  • scan_input_directions - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 张量的扫描方向:0 表示前向方向,1 表示后向方向。如果省略,则所有 scan_input 张量都将按前向方向扫描。

  • scan_output_axes - INTS :

    可选的 K 个标志列表。列表中的第 i 个元素指定第 i 个 scan_output 的轴。scan outputs 沿着指定的轴累积。如果省略,则对于每个 scan_output,将使用 0 作为扫描轴。轴的负值表示从后往前计算维度。可接受的范围是 [-r, r-1]。

  • scan_output_directions - INTS :

    可选的 K 个标志列表,每个 scan_output 一个。列表中的第 i 个元素指定第 i 个 scan_output 在每次迭代中是通过追加还是前置新值来构建:0 表示追加,1 表示前置。如果省略,所有 scan_output 张量都将通过在每次迭代中追加值来生成。

输入

输入数量介于 1 到 2147483647 之间。

  • initial_state_and_scan_inputs (可变数量) - V

    循环 N 个状态变量的初始值,后跟 M 个 scan_inputs

输出

1 到 2147483647 个输出之间。

  • final_state_and_scan_outputs (可变数量) - V

    循环 N 个状态变量的最终值,后跟 K 个 scan_outputs

类型约束

  • V 在 ( tensor(bfloat16), tensor(bool), tensor(complex128), tensor(complex64), tensor(double), tensor(float), tensor(float16), tensor(float8e4m3fn), tensor(float8e4m3fnuz), tensor(float8e5m2), tensor(float8e5m2fnuz), tensor(int16), tensor(int32), tensor(int64), tensor(int8), tensor(string), tensor(uint16), tensor(uint32), tensor(uint64), tensor(uint8) )

    IRv9 及之前的 Tensor 类型。

Scan - 16

版本

  • 名称: Scan (GitHub)

  • : main

  • since_version: 16

  • 函数: False

  • 支持级别: SupportType.COMMON

  • 形状推断: True

此版本的运算符自 版本 16 起可用。

摘要

Scan 可用于迭代一个或多个 scan_input 张量,构造零个或多个 scan_output 张量。它结合了通用递归、函数式编程中的 scan、fold、map 和 zip 等概念,旨在实现 RNN 类结构在序列到序列处理中的泛化。其他张量(此处称为 state_variables)可用于在从一个元素迭代到另一个元素时携带状态(类似于 RNN 中的隐藏状态,在循环的上下文中也称为循环依赖)。许多常见用法涉及单个 scan_input 张量(可获得类似于 scan、fold 和 map 的功能)。当使用多个 scan_input 时,会获得类似于 zip 的行为。

属性 body 必须是一个图,指定每次迭代要执行的计算。它接收 state_variables 的当前值和 scan_inputs 的当前迭代元素作为输入。它必须返回 state_variables 的(更新后的)值和零个或多个 scan_output_element 张量。scan_output_element 张量的值在所有迭代中被连接起来,以生成 scan 结构的 scan_output 值(类似于 RNN 类结构的连接的中间隐藏状态值)。所有输出张量(state_variables 和 scan_output_element 张量)在循环的每次迭代中都要求具有相同的形状(为实现高效内存分配而施加的限制)。

请注意,传递给 body 子图的迭代元素没有序列轴。它的秩比相应 scan_input 的秩少一。

scan 操作返回 state_variables 的最终值以及 scan_outputs。

可选属性 scan_input_directions 指定每个 scan input 的方向(前向或后向)。如果省略此属性,所有序列都将按前向方向扫描。可以通过在 scan_inputs 中指定相同的张量输入两次来执行双向扫描,一次指定前向方向,一次指定后向方向。

该操作的 scan_output 是通过在每次迭代中连接 body 生成的 scan_output_element 值来产生的。可选属性 scan_output_directions 指定了在每次迭代中构建 scan_output 的方向(通过将 scan_output_element 追加或前置到 scan_output)的扫描方向。如果省略此属性,scan_output_element 将在每次迭代中被追加到 scan_output。

可选属性 scan_input_axes 指定要扫描的每个 scan_input 的轴。如果省略,则每个 scan_input 将在轴 0 上进行扫描。例如,如果轴 0 是批次轴,轴 1 是要扫描的时间轴,则指定轴值为 1。请注意,扫描非零轴可能不如扫描轴零的效率高。

可选属性 scan_output_axes 指定了累积 scan_outputs 的轴。例如,如果轴 1 是输入和输出都要扫描的时间轴,则指定 scan_input 轴和 scan_output 轴值为 1。

请注意,由于 ONNX 限制,操作的最后一个参数才能是可变数量的,initial-states 和 scan-inputs 被一起列为一个输入参数。类似地,final-states 和 scan-outputs 被一起列为一个输出参数。num_scan_inputs 属性指示 scan_inputs 的数量 M。

的行为

Scan <
    num_scan_inputs = m,
    body = loop-body,
    scan_input_axes = [axis_1, ..., axis_m]
> (init_1, ..., init_n, scan_1, ..., scan_m)

等同于以下伪代码

// scan_i.shape[axis_i] denotes the (max) sequence-length of scan_i
// scan_i.shape[axis_i] is required to be equal to scan_j.shape[axis_j] for all i,j.
sequence_length = scan_1.shape[axis_1];

// initialize state-variables
st_1 = init_1; ... st_n = init_n;
// initialize scan-output variables: [] denotes an empty tensor
scan_out_1 = []; ...; scan_out_k = [];
// identify number of iterations:

// execute loop
for (int t = 0; t < sequence_length; ++t) {
    // generate the scan-input elements: the notation T<axis=k>[t] indicates the sub-tensor
    // of rank one less than T obtained by indexing T at position t along axis k.
    si_1 = scan_1<axis=axis_1>[t];
    ... ;
    si_m = scan_m<axis=axis_m>[t];
    // execute loop-body
    st_1, ..., st_n, so_1, ..., so_k = loop-body(st_1, ..., st_n, si_1, ..., si_m)
    // accumulate the scan-output elements
    scan_out_1 = Concat<axis=0>(scan_out_1, so_1); ... ; scan_out_k = Concat<axis=0>(scan_out_k, so_k);
}

return st_1, ..., st_n, scan_out_1, ..., scan_out_k;

示例用法:使用 Scan 编码 RNN

以下示例展示了如何将一个简单的 RNN(基于输入张量 %X、权重张量 %Wi、递归权重张量 %Ri、偏置张量 %Wbi 和 %Rbi,以及初始隐藏状态 %H_0)编码为 ScanLoop。请注意,loop-body 是一个嵌套图,它直接计算

的值是在外部图中计算的,它们需要作为额外的 state_variables 传入。

graph rnn-encoding {
  %H_0 = ...
  %X = ...
  %Y_h, %Y = Scan[body = <graph rnn-cell-1>, num_scan_inputs=1](%H_0, %X)
  return %Y, %Y_h
}

graph rnn-cell-1 (
  %H_tminus1[FLOAT, tensor]
  %X_t[FLOAT, tensor]
) {
  %Wi = ...
  %Ri = ...
  %Wbi = ...
  %Rbi = ...
  %t1 = X_t * (Wi^T)
  %t2 = H_tminus1*(Ri^T)
  %t3 = Add(%t1, %t2)
  %t4 = Add(%t3, %Wbi)
  %t5 = Add(%t4, %Rbi)
  %Ht = Tanh(%t5)
  %Accumulate = Identity(%Ht)
  return %Ht, %Accumulate
}

属性

  • body - GRAPH (必需)

    每次迭代运行的图。它有 N+M 个输入:(循环状态变量……,scan_input_elts……)。它有 N+K 个输出:(循环状态变量……,scan_output_elts……)。每个 scan_output 是通过在每次循环迭代结束时连接指定的 scan_output_elt 值而创建的。如果这些值在循环迭代之间的维度发生变化,则会报错。

  • num_scan_inputs - INT (必需)

    指定 scan_inputs 数量 M 的属性。

  • scan_input_axes - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 的要扫描的轴(序列轴)。如果省略,则对于每个 scan_input,将使用 0 作为扫描轴。轴的负值表示从后往前计算维度。可接受的范围是 [-r, r-1],其中 r = rank(input)。

  • scan_input_directions - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 张量的扫描方向:0 表示前向方向,1 表示后向方向。如果省略,则所有 scan_input 张量都将按前向方向扫描。

  • scan_output_axes - INTS :

    可选的 K 个标志列表。列表中的第 i 个元素指定第 i 个 scan_output 的轴。scan outputs 沿着指定的轴累积。如果省略,则对于每个 scan_output,将使用 0 作为扫描轴。轴的负值表示从后往前计算维度。可接受的范围是 [-r, r-1]。

  • scan_output_directions - INTS :

    可选的 K 个标志列表,每个 scan_output 一个。列表中的第 i 个元素指定第 i 个 scan_output 在每次迭代中是通过追加还是前置新值来构建:0 表示追加,1 表示前置。如果省略,所有 scan_output 张量都将通过在每次迭代中追加值来生成。

输入

输入数量介于 1 到 2147483647 之间。

  • initial_state_and_scan_inputs (可变数量) - V

    循环 N 个状态变量的初始值,后跟 M 个 scan_inputs

输出

1 到 2147483647 个输出之间。

  • final_state_and_scan_outputs (可变数量) - V

    循环 N 个状态变量的最终值,后跟 K 个 scan_outputs

类型约束

  • V 在 ( tensor(bfloat16), tensor(bool), tensor(complex128), tensor(complex64), tensor(double), tensor(float), tensor(float16), tensor(int16), tensor(int32), tensor(int64), tensor(int8), tensor(string), tensor(uint16), tensor(uint32), tensor(uint64), tensor(uint8) )

    IRv4 及之前的 Tensor 类型。

Scan - 11

版本

  • 名称: Scan (GitHub)

  • : main

  • 起始版本: 11

  • 函数: False

  • 支持级别: SupportType.COMMON

  • 形状推断: True

此版本的运算符自 版本 11 起可用。

摘要

Scan 可用于迭代一个或多个 scan_input 张量,构造零个或多个 scan_output 张量。它结合了通用递归、函数式编程中的 scan、fold、map 和 zip 等概念,旨在实现 RNN 类结构在序列到序列处理中的泛化。其他张量(此处称为 state_variables)可用于在从一个元素迭代到另一个元素时携带状态(类似于 RNN 中的隐藏状态,在循环的上下文中也称为循环依赖)。许多常见用法涉及单个 scan_input 张量(可获得类似于 scan、fold 和 map 的功能)。当使用多个 scan_input 时,会获得类似于 zip 的行为。

属性 body 必须是一个图,指定每次迭代要执行的计算。它接收 state_variables 的当前值和 scan_inputs 的当前迭代元素作为输入。它必须返回 state_variables 的(更新后的)值和零个或多个 scan_output_element 张量。scan_output_element 张量的值在所有迭代中被连接起来,以生成 scan 结构的 scan_output 值(类似于 RNN 类结构的连接的中间隐藏状态值)。所有输出张量(state_variables 和 scan_output_element 张量)在循环的每次迭代中都要求具有相同的形状(为实现高效内存分配而施加的限制)。

请注意,传递给 body 子图的迭代元素没有序列轴。它的秩比相应 scan_input 的秩少一。

scan 操作返回 state_variables 的最终值以及 scan_outputs。

可选属性 scan_input_directions 指定每个 scan input 的方向(前向或后向)。如果省略此属性,所有序列都将按前向方向扫描。可以通过在 scan_inputs 中指定相同的张量输入两次来执行双向扫描,一次指定前向方向,一次指定后向方向。

该操作的 scan_output 是通过在每次迭代中连接 body 生成的 scan_output_element 值来产生的。可选属性 scan_output_directions 指定了在每次迭代中构建 scan_output 的方向(通过将 scan_output_element 追加或前置到 scan_output)的扫描方向。如果省略此属性,scan_output_element 将在每次迭代中被追加到 scan_output。

可选属性 scan_input_axes 指定要扫描的每个 scan_input 的轴。如果省略,则每个 scan_input 将在轴 0 上进行扫描。例如,如果轴 0 是批次轴,轴 1 是要扫描的时间轴,则指定轴值为 1。请注意,扫描非零轴可能不如扫描轴零的效率高。

可选属性 scan_output_axes 指定了累积 scan_outputs 的轴。例如,如果轴 1 是输入和输出都要扫描的时间轴,则指定 scan_input 轴和 scan_output 轴值为 1。

请注意,由于 ONNX 限制,操作的最后一个参数才能是可变数量的,initial-states 和 scan-inputs 被一起列为一个输入参数。类似地,final-states 和 scan-outputs 被一起列为一个输出参数。num_scan_inputs 属性指示 scan_inputs 的数量 M。

的行为

Scan <
    num_scan_inputs = m,
    body = loop-body,
    scan_input_axes = [axis_1, ..., axis_m]
> (init_1, ..., init_n, scan_1, ..., scan_m)

等同于以下伪代码

// scan_i.shape[axis_i] denotes the (max) sequence-length of scan_i
// scan_i.shape[axis_i] is required to be equal to scan_j.shape[axis_j] for all i,j.
sequence_length = scan_1.shape[axis_1];

// initialize state-variables
st_1 = init_1; ... st_n = init_n;
// initialize scan-output variables: [] denotes an empty tensor
scan_out_1 = []; ...; scan_out_k = [];
// identify number of iterations:

// execute loop
for (int t = 0; t < sequence_length; ++t) {
    // generate the scan-input elements: the notation T<axis=k>[t] indicates the sub-tensor
    // of rank one less than T obtained by indexing T at position t along axis k.
    si_1 = scan_1<axis=axis_1>[t];
    ... ;
    si_m = scan_m<axis=axis_m>[t];
    // execute loop-body
    st_1, ..., st_n, so_1, ..., so_k = loop-body(st_1, ..., st_n, si_1, ..., si_m)
    // accumulate the scan-output elements
    scan_out_1 = Concat<axis=0>(scan_out_1, so_1); ... ; scan_out_k = Concat<axis=0>(scan_out_k, so_k);
}

return st_1, ..., st_n, scan_out_1, ..., scan_out_k;

示例用法:使用 Scan 编码 RNN

以下示例展示了如何将一个简单的 RNN(基于输入张量 %X、权重张量 %Wi、递归权重张量 %Ri、偏置张量 %Wbi 和 %Rbi,以及初始隐藏状态 %H_0)编码为 ScanLoop。请注意,loop-body 是一个嵌套图,它直接计算

的值是在外部图中计算的,它们需要作为额外的 state_variables 传入。

graph rnn-encoding {
  %H_0 = ...
  %X = ...
  %Y_h, %Y = Scan[body = <graph rnn-cell-1>, num_scan_inputs=1](%H_0, %X)
  return %Y, %Y_h
}

graph rnn-cell-1 (
  %H_tminus1[FLOAT, tensor]
  %X_t[FLOAT, tensor]
) {
  %Wi = ...
  %Ri = ...
  %Wbi = ...
  %Rbi = ...
  %t1 = X_t * (Wi^T)
  %t2 = H_tminus1*(Ri^T)
  %t3 = Add(%t1, %t2)
  %t4 = Add(%t3, %Wbi)
  %t5 = Add(%t4, %Rbi)
  %Ht = Tanh(%t5)
  %Accumulate = Identity(%Ht)
  return %Ht, %Accumulate
}

属性

  • body - GRAPH (必需)

    每次迭代运行的图。它有 N+M 个输入:(循环状态变量……,scan_input_elts……)。它有 N+K 个输出:(循环状态变量……,scan_output_elts……)。每个 scan_output 是通过在每次循环迭代结束时连接指定的 scan_output_elt 值而创建的。如果这些值在循环迭代之间的维度发生变化,则会报错。

  • num_scan_inputs - INT (必需)

    指定 scan_inputs 数量 M 的属性。

  • scan_input_axes - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 的要扫描的轴(序列轴)。如果省略,则对于每个 scan_input,将使用 0 作为扫描轴。轴的负值表示从后往前计算维度。可接受的范围是 [-r, r-1],其中 r = rank(input)。

  • scan_input_directions - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 张量的扫描方向:0 表示前向方向,1 表示后向方向。如果省略,则所有 scan_input 张量都将按前向方向扫描。

  • scan_output_axes - INTS :

    可选的 K 个标志列表。列表中的第 i 个元素指定第 i 个 scan_output 的轴。scan outputs 沿着指定的轴累积。如果省略,则对于每个 scan_output,将使用 0 作为扫描轴。轴的负值表示从后往前计算维度。可接受的范围是 [-r, r-1]。

  • scan_output_directions - INTS :

    可选的 K 个标志列表,每个 scan_output 一个。列表中的第 i 个元素指定第 i 个 scan_output 在每次迭代中是通过追加还是前置新值来构建:0 表示追加,1 表示前置。如果省略,所有 scan_output 张量都将通过在每次迭代中追加值来生成。

输入

输入数量介于 1 到 2147483647 之间。

  • initial_state_and_scan_inputs (可变数量) - V

    循环 N 个状态变量的初始值,后跟 M 个 scan_inputs

输出

1 到 2147483647 个输出之间。

  • final_state_and_scan_outputs (可变数量) - V

    循环 N 个状态变量的最终值,后跟 K 个 scan_outputs

类型约束

  • V 在 ( tensor(bool), tensor(complex128), tensor(complex64), tensor(double), tensor(float), tensor(float16), tensor(int16), tensor(int32), tensor(int64), tensor(int8), tensor(string), tensor(uint16), tensor(uint32), tensor(uint64), tensor(uint8) )

    所有张量类型

Scan - 9

版本

  • 名称: Scan (GitHub)

  • : main

  • 起始版本: 9

  • 函数: False

  • 支持级别: SupportType.COMMON

  • 形状推断: True

此版本的运算符自 版本 9 起可用。

摘要

Scan 可用于迭代一个或多个 scan_input 张量,构造零个或多个 scan_output 张量。它结合了通用递归、函数式编程中的 scan、fold、map 和 zip 等概念,旨在实现 RNN 类结构在序列到序列处理中的泛化。其他张量(此处称为 state_variables)可用于在从一个元素迭代到另一个元素时携带状态(类似于 RNN 中的隐藏状态,在循环的上下文中也称为循环依赖)。许多常见用法涉及单个 scan_input 张量(可获得类似于 scan、fold 和 map 的功能)。当使用多个 scan_input 时,会获得类似于 zip 的行为。

属性 body 必须是一个图,指定每次迭代要执行的计算。它接收 state_variables 的当前值和 scan_inputs 的当前迭代元素作为输入。它必须返回 state_variables 的(更新后的)值和零个或多个 scan_output_element 张量。scan_output_element 张量的值在所有迭代中被连接起来,以生成 scan 结构的 scan_output 值(类似于 RNN 类结构的连接的中间隐藏状态值)。所有输出张量(state_variables 和 scan_output_element 张量)在循环的每次迭代中都要求具有相同的形状(为实现高效内存分配而施加的限制)。

请注意,传递给 body 子图的迭代元素没有序列轴。它的秩比相应 scan_input 的秩少一。

scan 操作返回 state_variables 的最终值以及 scan_outputs。

可选属性 scan_input_directions 指定每个 scan input 的方向(前向或后向)。如果省略此属性,所有序列都将按前向方向扫描。可以通过在 scan_inputs 中指定相同的张量输入两次来执行双向扫描,一次指定前向方向,一次指定后向方向。

该操作的 scan_output 是通过在每次迭代中连接 body 生成的 scan_output_element 值来产生的。可选属性 scan_output_directions 指定了在每次迭代中构建 scan_output 的方向(通过将 scan_output_element 追加或前置到 scan_output)的扫描方向。如果省略此属性,scan_output_element 将在每次迭代中被追加到 scan_output。

可选属性 scan_input_axes 指定要扫描的每个 scan_input 的轴。如果省略,则每个 scan_input 将在轴 0 上进行扫描。例如,如果轴 0 是批次轴,轴 1 是要扫描的时间轴,则指定轴值为 1。请注意,扫描非零轴可能不如扫描轴零的效率高。

可选属性 scan_output_axes 指定了累积 scan_outputs 的轴。例如,如果轴 1 是输入和输出都要扫描的时间轴,则指定 scan_input 轴和 scan_output 轴值为 1。

请注意,由于 ONNX 限制,操作的最后一个参数才能是可变数量的,initial-states 和 scan-inputs 被一起列为一个输入参数。类似地,final-states 和 scan-outputs 被一起列为一个输出参数。num_scan_inputs 属性指示 scan_inputs 的数量 M。

的行为

Scan <
    num_scan_inputs = m,
    body = loop-body,
    scan_input_axes = [axis_1, ..., axis_m]
> (init_1, ..., init_n, scan_1, ..., scan_m)

等同于以下伪代码

// scan_i.shape[axis_i] denotes the (max) sequence-length of scan_i
// scan_i.shape[axis_i] is required to be equal to scan_j.shape[axis_j] for all i,j.
sequence_length = scan_1.shape[axis_1];

// initialize state-variables
st_1 = init_1; ... st_n = init_n;
// initialize scan-output variables: [] denotes an empty tensor
scan_out_1 = []; ...; scan_out_k = [];
// identify number of iterations:

// execute loop
for (int t = 0; t < sequence_length; ++t) {
    // generate the scan-input elements: the notation T<axis=k>[t] indicates the sub-tensor
    // of rank one less than T obtained by indexing T at position t along axis k.
    si_1 = scan_1<axis=axis_1>[t];
    ... ;
    si_m = scan_m<axis=axis_m>[t];
    // execute loop-body
    st_1, ..., st_n, so_1, ..., so_k = loop-body(st_1, ..., st_n, si_1, ..., si_m)
    // accumulate the scan-output elements
    scan_out_1 = Concat<axis=0>(scan_out_1, so_1); ... ; scan_out_k = Concat<axis=0>(scan_out_k, so_k);
}

return st_1, ..., st_n, scan_out_1, ..., scan_out_k;

示例用法:使用 Scan 编码 RNN

以下示例展示了如何将一个简单的 RNN(基于输入张量 %X、权重张量 %Wi、递归权重张量 %Ri、偏置张量 %Wbi 和 %Rbi,以及初始隐藏状态 %H_0)编码为 ScanLoop。请注意,loop-body 是一个嵌套图,它直接计算

的值是在外部图中计算的,它们需要作为额外的 state_variables 传入。

graph rnn-encoding {
  %H_0 = ...
  %X = ...
  %Y_h, %Y = Scan[body = <graph rnn-cell-1>, num_scan_inputs=1](%H_0, %X)
  return %Y, %Y_h
}

graph rnn-cell-1 (
  %H_tminus1[FLOAT, tensor]
  %X_t[FLOAT, tensor]
) {
  %Wi = ...
  %Ri = ...
  %Wbi = ...
  %Rbi = ...
  %t1 = X_t * (Wi^T)
  %t2 = H_tminus1*(Ri^T)
  %t3 = Add(%t1, %t2)
  %t4 = Add(%t3, %Wbi)
  %t5 = Add(%t4, %Rbi)
  %Ht = Tanh(%t5)
  %Accumulate = Identity(%Ht)
  return %Ht, %Accumulate
}

属性

  • body - GRAPH (必需)

    每次迭代运行的图。它有 N+M 个输入:(循环状态变量……,scan_input_elts……)。它有 N+K 个输出:(循环状态变量……,scan_output_elts……)。每个 scan_output 是通过在每次循环迭代结束时连接指定的 scan_output_elt 值而创建的。如果这些值在循环迭代之间的维度发生变化,则会报错。

  • num_scan_inputs - INT (必需)

    指定 scan_inputs 数量 M 的属性。

  • scan_input_axes - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 的要扫描的轴(序列轴)。如果省略,则对于每个 scan_input,将使用 0 作为扫描轴。

  • scan_input_directions - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 张量的扫描方向:0 表示前向方向,1 表示后向方向。如果省略,则所有 scan_input 张量都将按前向方向扫描。

  • scan_output_axes - INTS :

    可选的 K 个标志列表。列表中的第 i 个元素指定第 i 个 scan_output 的轴。scan outputs 沿着指定的轴累积。如果省略,则对于每个 scan_output,将使用 0 作为扫描轴。

  • scan_output_directions - INTS :

    可选的 K 个标志列表,每个 scan_output 一个。列表中的第 i 个元素指定第 i 个 scan_output 在每次迭代中是通过追加还是前置新值来构建:0 表示追加,1 表示前置。如果省略,所有 scan_output 张量都将通过在每次迭代中追加值来生成。

输入

输入数量介于 1 到 2147483647 之间。

  • initial_state_and_scan_inputs (可变数量) - V

    循环 N 个状态变量的初始值,后跟 M 个 scan_inputs

输出

1 到 2147483647 个输出之间。

  • final_state_and_scan_outputs (可变数量) - V

    循环 N 个状态变量的最终值,后跟 K 个 scan_outputs

类型约束

  • V 在 ( tensor(bool), tensor(complex128), tensor(complex64), tensor(double), tensor(float), tensor(float16), tensor(int16), tensor(int32), tensor(int64), tensor(int8), tensor(string), tensor(uint16), tensor(uint32), tensor(uint64), tensor(uint8) )

    所有张量类型

Scan - 8

版本

  • 名称: Scan (GitHub)

  • : main

  • 起始版本8

  • 函数: False

  • 支持级别: SupportType.COMMON

  • 形状推断: True

此运算符版本自版本 8 起可用。

摘要

Scan 可用于迭代一个或多个 scan_input 张量,构造零个或多个 scan_output 张量。它结合了通用递归、函数式编程中的 scan、fold、map 和 zip 等概念,旨在实现 RNN 类结构在序列到序列处理中的泛化。其他张量(此处称为 state_variables)可用于在从一个元素迭代到另一个元素时携带状态(类似于 RNN 中的隐藏状态,在循环的上下文中也称为循环依赖)。所有这些张量在循环的每次迭代中都要求具有相同的形状(为实现高效内存分配而施加的限制)。许多常见用法涉及单个 scan_input 张量(可获得类似于 scan、fold 和 map 的功能)。当使用多个 scan_input 时,会获得类似于 zip 的行为。

属性 body 必须是一个图,指定每次迭代要执行的计算。它接收 state_variables 的当前值和 scan_inputs 的当前迭代元素作为输入。它必须返回 state_variables 的(更新后的)值和零个或多个 scan_output_element 张量。scan_output_element 张量的值在所有迭代中被连接起来,以生成 scan 结构的 scan_output 值(类似于 RNN 类结构的连接的中间隐藏状态值)。

scan 操作返回 state_variables 的最终值以及 scan_outputs。

该操作支持批处理,并且要求批次轴为 0。当使用多个 scan_input 张量时,它们必须具有相同的批次大小,并且必须具有相同的最大序列长度(序列轴或扫描轴的维度)。序列轴或扫描轴要求为 1。

该操作有一个可选的 sequence_lens 输入(形状为 [BATCH_SIZE]),允许可变长度的序列,长度小于或等于最大序列长度。如果未指定此输入,则所有序列都被假定长度等于最大序列长度。对于可变长度输入序列,scan_outputs 将包含一个与输入长度相同的序列,并填充到最大序列长度。

可选属性 directions 可用于以反向方向扫描序列。如果省略此属性,所有序列都将按前向方向扫描。可以通过在 scan_inputs 中指定相同的张量输入两次来执行双向扫描,一次指定前向方向,一次指定后向方向。

请注意,由于 ONNX 限制,操作的最后一个参数才能是可变数量的,initial-states 和 scan-inputs 被一起列为一个输入参数。类似地,final-states 和 scan-outputs 被一起列为一个输出参数。num_scan_inputs 属性指示 scan_inputs 的数量 M。

的行为

Scan <
    num_scan_inputs = m,
    body = loop-body
> (sequence_lengths, init_1, ..., init_n, scan_1, ..., scan_m)

等同于以下伪代码

// T.shape[0] denotes the batch-size of T
// The batch-size of scan_1, ..., scan_m are all required to be equal
batch_size = scan_1.shape[0];

// scan_i.shape[1] denotes the (max) sequence-length of scan_i
// scan_i.shape[1] is required to be equal to scan_j.shape[1] for all i,j.
max_sequence_length = scan_1.shape[1];

for (int batch = 0; batch < batch_size; ++batch) {
    // initialize state-variables
    st_1 = init_1; ... st_n = init_n;
    // initialize scan-output variables: [] denotes an empty tensor
    scan_out_1 = []; ...; scan_out_k = [];
    // identify number of iterations:
    N = (sequence_lengths specified) ? sequence_lengths[batch] : max_sequence_length;

    // execute loop
    for (int t = 0; t < N; ++t) {
        // generate the scan-input elements: the notation T<axis=k>[t] indicates the sub-tensor
        // of rank one less than T obtained by indexing T at position t along axis k.
        si_1 = (scan_1<axis=0>[batch])<axis=1>[t];
        ... ;
        si_m = (scan_m<axis=0>[batch])<axis=1>[t];
        // execute loop-body
        st_1, ..., st_n, so_1, ..., so_k = loop-body(st_1, ..., st_n, si_1, ..., si_m)
        // accumulate the scan-output elements
        scan_out_1 = Concat<axis=0>(scan_out_1, so_1); ... ; scan_out_k = Concat<axis=0>(scan_out_k, so_k);
    }
    // accumulate the outputs for this batch:
    bst_1[batch] = st_1; ..., bst_n[batch] = st_n;
    // Note scan-outputs will have size max_sequence_length, but only first N values will be meaningful.
    // The remaining values have an undefined value.
    b_scan_out_1[batch] = scan_out_1; ...; b_scan_out_k[batch] = scan_out_k;
}
return bst_1, ..., bst_n, b_scan_out_1, ..., b_scan_out_k;

示例用法:使用 Scan 编码 RNN

以下示例展示了如何将一个简单的 RNN(基于输入张量 %X、权重张量 %Wi、递归权重张量 %Ri、偏置张量 %Wbi 和 %Rbi,以及初始隐藏状态 %H_0)编码为 ScanLoop。请注意,loop-body 是一个嵌套图,它直接计算

的值是在外部图中计算的,它们需要作为额外的 state_variables 传入。

graph rnn-encoding {
  %H_0 = ...
  %X = ...
  %Y_h, %Y = Scan[body = <graph rnn-cell-1>, num_scan_inputs=1]("", %H_0, %X)
  return %Y, %Y_h
}

graph rnn-cell-1 (
  %H_tminus1[FLOAT, tensor]
  %X_t[FLOAT, tensor]
) {
  %Wi = ...
  %Ri = ...
  %Wbi = ...
  %Rbi = ...
  %t1 = X_t * (Wi^T)
  %t2 = H_tminus1*(Ri^T)
  %t3 = Add(%t1, %t2)
  %t4 = Add(%t3, %Wbi)
  %t5 = Add(%t4, %Rbi)
  %Ht = Tanh(%t5)
  %Accumulate = Identity(%Ht)
  return %Ht, %Accumulate
}

属性

  • body - GRAPH (必需)

    每次迭代运行的图。它有 N+M 个输入:(循环状态变量……,scan_input_elts……)。它有 N+K 个输出:(循环状态变量……,scan_output_elts……)。每个 scan_output 是通过在每次循环迭代结束时连接指定的 scan_output_elt 值而创建的。如果这些值在循环迭代之间的维度发生变化,则会报错。

  • directions - INTS :

    可选的 M 个标志列表。列表中的第 i 个元素指定第 i 个 scan_input 张量的扫描方向:0 表示前向方向,1 表示后向方向。如果省略,则所有 scan_input 张量都将按前向方向扫描。

  • num_scan_inputs - INT (必需)

    指定 scan_inputs 数量 M 的属性。

输入

介于 2 到 2147483647 之间的输入。

  • sequence_lens (可选, 异构) - I

    可选的张量,指定批次中序列的长度。如果未指定此输入,则所有序列都假定为最大序列长度(scan_input 张量的序列轴的维度)。

  • initial_state_and_scan_inputs (可变数量) - V

    循环 N 个状态变量的初始值,后跟 M 个 scan_inputs

输出

1 到 2147483647 个输出之间。

  • final_state_and_scan_outputs (可变数量) - V

    循环 N 个状态变量的最终值,后跟 K 个 scan_outputs

类型约束

  • I 在 ( tensor(int64) )

    Int64 张量

  • V 在 ( tensor(bool), tensor(complex128), tensor(complex64), tensor(double), tensor(float), tensor(float16), tensor(int16), tensor(int32), tensor(int64), tensor(int8), tensor(string), tensor(uint16), tensor(uint32), tensor(uint64), tensor(uint8) )

    所有张量类型