Tensor

功能说明

定义Tensor变量。

函数原型

Tensor(dtype, shape, scope, name, enable_buffer_reuse=False, is_workspace=False, is_atomic_add=False，

max_mem_size=None, init_value=None)

参数说明

表1 参数说明
参数名称	输入/输出	含义
dtype	输入	指定Tensor对象的数据类型，取值： uint8、int8、uint16、int16、float16、uint32、int32、float32、uint64、int64
shape	输入	指定Tensor对象的形状，支持List、Tuple类型，List、Tuple中的元素可以为立即数（int、float）、Scalar（int、uint）或Expr（int、uint）。不建议使用float类型的立即数。 shape的大小需要注意以下约束： shape的大小不能超过8维。 shape大小请根据实际需要设置，但不能超过scope指定的存储单元的大小，存储单元的大小可通过get_soc_spec查询。
scope	输入	Tensor 内存类型范围，指定Tensor对象的所在buffer空间，取值： scope_cbuf：L1 Buffer scope_cbuf_out：L1OUT Buffer scope_ubuf ： Unified Buffer scope_gm： Global Memory 其中scope_gm代表外部存储，其他为内部存储，只有将外部存储中的数据搬运到内部存储中，才能完成相应的计算；当scope为gm时，不能在for_range内部定义Tensor。
name	输入	Tensor名字，string类型。名字支持数字0-9,A-Z,a-z及下划线组成的字符串，不支持以数字开头。 tensor 的名字需要保持唯一。说明： scope为scope_gm时，不支持为"__fake_tensor"。
enable_buffer_reuse	输入	保留参数，不建议使用。
is_workspace	输入	bool值，默认值为False。当该值为True时，代表当前Tensor是用于中间存储数据，而不用于输入输出。当取值为True时，需要保证scope为scope_gm，同时，不包含在输入输出中，即输入输出的Tensor的name中不含workspace中的Tensor。
is_atomic_add	输入	是否进行初始化GM空间，默认值为False。当设置为True时，默认将GM空间初始化为0。当设置为False时，GM空间不进行初始化。当该值为True时，需要保证scope为scope_gm。说明：仅算子在网络中执行的场景下，此参数才生效。网络执行时，Graph Engine会根据此参数判断是否进行GM的空间初始化。
max_mem_size	输入	Tensor所占据的空间大小。当shape中不含变量时，用户可以不指定该值，或者指定max_mem_size为shape中各元素乘积再乘上dtype_size。当shape中包含变量时，用户既可以指定一个常数max_mem_size，且max_mem_size必须大于等于shape中各元素乘积再乘上dtype_size，并且为dtype_size的整数倍数；也可以不指定max_mem_size，程序运行时拿到shape的具体数值再分配内存（动态shape Tensor）。但当tensor的is_workspace字段为True时，必须指定max_mem_size。
init_value	输入	Tensor的初始值，为单个元素或list/tuple类型的值。注意：该参数为预留参数，当前版本暂不支持。

支持的型号

Atlas 200/300/500 推理产品

Atlas 训练系列产品

Atlas推理系列产品（Ascend 310P处理器）AI Core

Atlas推理系列产品（Ascend 310P处理器）Vector Core

Atlas A2训练系列产品/Atlas 800I A2推理产品

Atlas 200/500 A2推理产品

注意事项

当Tensor总容量超出对应内存类型的总容量时，编译时报错。

例如，下面示例中，data_a的数据量为1025*1024Byte，大于L1 Buffer的内存总容量1MB。

import numpy as np
import sys
from tbe import tik
import tvm

def buffer_allocate_test6():
    tik_instance = tik.Tik()
    data_a = tik_instance.Tensor("int8", (1025 * 1024,), name="data_a", scope=tik.scope_cbuf)
    tik_instance.BuildCCE(kernel_name="buffer_allocate_test",inputs=[],outputs=[])
    return tik_instance

if __name__ == "__main__":
    tik_instance = buffer_allocate_test6()

编译报错：

RuntimeError: Applied buffer size(1049600B) more than available buffer size(1048576B).

当Tensor定义在某作用域内，离开作用域后，如果再次访问，则在编译时报错。

例如，下面示例中，data_a_l1仅定义在new_stmt_scope作用域中，离开该作用域，执行data_move再次使用data_a_l1时报错。

import numpy as np
import sys
from tbe import tik
import tvm

def tensor_outrange_examine_test6():
    tik_instance = tik.Tik()
    data_a = tik_instance.Tensor("float16", (128,), name="data_a", scope=tik.scope_gm)
    data_b = tik_instance.Tensor("float16", (128,), name="data_b", scope=tik.scope_gm)
    with tik_instance.new_stmt_scope():
        data_a_ub = tik_instance.Tensor("float16", (128,), name="data_a_ub", scope=tik.scope_ubuf)
        data_a_l1 = tik_instance.Tensor("float16", (128,), name="data_a_l1", scope=tik.scope_cbuf)
    tik_instance.data_move(data_a_l1, data_a, 0, 1, 128 // 16, 0, 0)
    tik_instance.data_move(data_a_ub, data_a_l1, 0, 1, 128 // 16, 0, 0)
    tik_instance.data_move(data_b, data_a_ub, 0, 1, 128 // 16, 0, 0)
    tik_instance.BuildCCE(kernel_name="tensor_outrange_examine", inputs=[data_a], outputs=[data_b])
    return tik_instance

编译报错：

RuntimeError: This tensor is not defined in this scope.

Tensor离开作用域后，这部分内存空间容量可以再次使用。

例如，下面示例中data_a_ub1和data_a_ub2离开作用域后，其占用的内存空间62*2*1024B=126976B，可以被data_b_ub使用：

import numpy as np
import sys
from tbe import tik
import tvm

def double_buffer_test6():
    tik_instance = tik.Tik()
    data_a = tik_instance.Tensor("int8", (124 *1024,), name="data_a", scope=tik.scope_ubuf)
    with tik_instance.for_range(0, 2):
        data_a_ub1 = tik_instance.Tensor("int8", (62 * 1024,), name="data_a_ub1", scope=tik.scope_ubuf)
        data_a_ub2 = tik_instance.Tensor("int8", (62 * 1024,), name="data_a_ub2", scope=tik.scope_ubuf)
    data_b_ub = tik_instance.Tensor("int8", (125 * 1024,), name="data_b_ub", scope=tik.scope_ubuf)
    tik_instance.BuildCCE(kernel_name="tbe_double_buffer_no_loop", inputs=[ ], outputs=[ ])
    return tik_instance
if __name__ == "__main__":
    tik_instance = double_buffer_test6()

如果data_b_ub超出Unified Buffer的内存容量，则编译报错：

RuntimeError: Tensor data_b_ub applies buffer size(128000B) more than available buffer size(126976B).

用户定义的tensor在内存分配时会对起始地址进行对齐，不同scope的对齐要求请参见通用约束。
用户需特别注意因地址对齐导致的超出对应内存类型的总容量时，会引起编译报错。

返回值

Tensor类的实例。

调用示例

from tbe import tik
tik_instance = tik.Tik()
data_A = tik_instance.Tensor("float16", (128,), name="data_A", scope=tik.scope_gm)

父主题： 数据定义