在 C++ 中管理 Tensor 内存¶
Tensor 是 ExecuTorch 中的基本数据结构，表示用于神经网络和其他数值计算的多维数组。在 ExecuTorch 中，Tensor 类不拥有其元数据（大小、步长、维度顺序）或数据，从而保持运行时轻量级。用户负责提供所有这些内存缓冲区，并确保元数据和数据的生命周期长于 Tensor 实例。虽然这种设计轻量且灵活，特别是对于微型嵌入式系统，但它给用户带来了沉重负担。如果您的环境需要最少的动态分配、小的二进制占用空间或有限的 C++ 标准库支持，您需要接受这种权衡并坚持使用常规的 Tensor 类型。
想象一下您正在使用 Module 接口，并且需要将 Tensor 传递给 forward() 方法。您将需要单独声明和维护至少 sizes 数组和数据，有时还有 strides，这通常会导致以下模式
#include <executorch/extension/module/module.h>
using namespace executorch::aten;
using namespace executorch::extension;
SizesType sizes[] = {2, 3};
DimOrderType dim_order[] = {0, 1};
StridesType strides[] = {3, 1};
float data[] = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f};
TensorImpl tensor_impl(
ScalarType::Float,
std::size(sizes),
sizes,
data,
dim_order,
strides);
// ...
module.forward(Tensor(&tensor_impl));
您必须确保 sizes、dim_order、strides 和 data 保持有效。这使得代码维护变得困难且容易出错。用户一直在努力管理生命周期，许多人创建了自己的临时托管 tensor 抽象来将所有部分整合在一起，这导致了生态系统的碎片化和不一致。
引入 TensorPtr¶
为了缓解这些问题，ExecuTorch 提供了 TensorPtr，一个管理 tensor 数据及其动态元数据生命周期的智能指针。
有了 TensorPtr，用户不再需要单独担心元数据的生命周期。数据所有权取决于它是通过指针传递还是作为 std::vector 移动到 TensorPtr 中。所有内容都捆绑在一起并自动管理，使您能够专注于实际计算。
以下是使用方法
#include <executorch/extension/module/module.h>
#include <executorch/extension/tensor/tensor.h>
using namespace executorch::extension;
auto tensor = make_tensor_ptr(
{2, 3}, // sizes
{1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f}); // data
// ...
module.forward(tensor);
数据现在由 tensor 实例拥有，因为它是作为 vector 提供的。要创建一个非拥有 TensorPtr，只需通过指针传递数据即可。type 会根据数据 vector（float）自动推断。strides 和 dim_order 会根据 sizes 自动计算为默认值，如果未显式指定为额外参数的话。
Module::forward() 中的 EValue 直接接受 TensorPtr，确保无缝集成。EValue 现在可以通过智能指针隐式构造，指向它可以容纳的任何类型。这允许 TensorPtr 在传递给 forward() 时被隐式解引用，EValue 将持有 TensorPtr 指向的 Tensor。
API 概述¶
TensorPtr 实际上是 std::shared_ptr<Tensor> 的别名，因此您可以轻松使用它而无需复制数据和元数据。每个 Tensor 实例可以拥有自己的数据或引用外部数据。
创建 Tensor¶
有几种方法可以创建 TensorPtr。
创建标量 Tensor¶
您可以创建一个标量 tensor，即零维度的 tensor 或其中一个大小为零的 tensor。
提供单个数据值
auto tensor = make_tensor_ptr(3.14);
生成的 tensor 将包含一个类型为 double 的单个值 3.14，类型会自动推断。
提供带类型的单个数据值
auto tensor = make_tensor_ptr(42, ScalarType::Float);
现在整数 42 将被转换为 float，tensor 将包含一个类型为 float 的单个值 42。
拥有来自 Vector 的数据¶
当您提供 sizes 和数据 vector 时，TensorPtr 会拥有数据和 sizes 的所有权。
提供数据 Vector
auto tensor = make_tensor_ptr(
{2, 3}, // sizes
{1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f}); // data (float)
类型会从数据 vector 自动推断为 ScalarType::Float。
提供带类型的数据 Vector
如果您提供一种类型的数据但指定了另一种标量类型，数据将被转换为给定的类型。
auto tensor = make_tensor_ptr(
{1, 2, 3, 4, 5, 6}, // data (int)
ScalarType::Double); // double scalar type
在此示例中，即使数据 vector 包含整数，我们也指定标量类型为 Double。整数被转换为 double，并且新的数据 vector 由 TensorPtr 拥有。由于此示例中跳过了 sizes 参数，因此 tensor 是一个维度，其大小等于数据 vector 的长度。请注意，不允许反向转换，即从浮点类型转换为整型，因为这会丢失精度。类似地，不允许将其他类型转换为 Bool。
将数据 Vector 作为 std::vector<uint8_t> 提供
您还可以提供 std::vector<uint8_t> 形式的原始数据，并指定 sizes 和标量类型。数据将根据提供的类型重新解释。
std::vector<uint8_t> data = /* raw data */;
auto tensor = make_tensor_ptr(
{2, 3}, // sizes
std::move(data), // data as uint8_t vector
ScalarType::Int); // int scalar type
数据 vector 必须足够大，以根据提供的 sizes 和标量类型容纳所有元素。
来自原始指针的非拥有数据¶
您可以创建一个引用现有数据但不拥有所有权的 TensorPtr。
提供原始数据
float data[] = {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f};
auto tensor = make_tensor_ptr(
{2, 3}, // sizes
data, // raw data pointer
ScalarType::Float); // float scalar type
TensorPtr 不拥有数据，因此您必须确保 data 保持有效。
提供带自定义删除器的原始数据
如果您希望 TensorPtr 管理数据的生命周期，您可以提供一个自定义删除器。
auto* data = new double[6]{1.0, 2.0, 3.0, 4.0, 5.0, 6.0};
auto tensor = make_tensor_ptr(
{2, 3}, // sizes
data, // data pointer
ScalarType::Double, // double scalar type
TensorShapeDynamism::DYNAMIC_BOUND, // default dynamism
[](void* ptr) { delete[] static_cast<double*>(ptr); });
当 TensorPtr 被销毁时（即智能指针被重置且不再有对底层 Tensor 的引用时），它将调用自定义删除器。
共享现有 Tensor¶
由于 TensorPtr 是 std::shared_ptr<Tensor>，您可以轻松创建一个共享现有 Tensor 的 TensorPtr。对共享数据所做的任何更改都将反映在所有共享同一数据的实例中。
共享现有 TensorPtr
auto tensor = make_tensor_ptr({2, 3}, {1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f});
auto tensor_copy = tensor;
现在 tensor 和 tensor_copy 指向相同的数据和元数据。
查看现有 Tensor¶
您可以从现有 Tensor 创建一个 TensorPtr，复制其属性并引用相同的数据。
查看现有 Tensor
Tensor original_tensor = /* some existing tensor */;
auto tensor = make_tensor_ptr(original_tensor);
现在新创建的 TensorPtr 引用与原始 tensor 相同的数据，但拥有自己的元数据副本，因此它可以以不同方式解释或“查看”数据，但对数据的任何修改也将反映在原始 Tensor 中。
克隆 Tensor¶
要创建一个新的 TensorPtr，它拥有现有 tensor 数据的副本
Tensor original_tensor = /* some existing tensor */;
auto tensor = clone_tensor_ptr(original_tensor);
新创建的 TensorPtr 拥有自己的数据副本，因此可以独立修改和管理数据。同样，您可以创建现有 TensorPtr 的克隆。
auto original_tensor = make_tensor_ptr(/* ... */);
auto tensor = clone_tensor_ptr(original_tensor);
请注意，无论原始 TensorPtr 是否拥有数据，新创建的 TensorPtr 都将拥有数据的副本。
调整 Tensor 大小¶
TensorShapeDynamism 枚举指定了 tensor 形状的可变性
STATIC：tensor 的形状不能更改。DYNAMIC_BOUND：tensor 的形状可以更改，但包含的元素数量不能超过其根据初始 sizes 创建时原本拥有的元素数量。DYNAMIC：tensor 的形状可以任意更改。目前，DYNAMIC是DYNAMIC_BOUND的别名。
调整 tensor 大小时，必须遵守其 dynamism 设置。只有形状设置为 DYNAMIC 或 DYNAMIC_BOUND 的 tensor 才允许调整大小，并且不能将 DYNAMIC_BOUND 的 tensor 调整为包含比最初更多元素的数量。
auto tensor = make_tensor_ptr(
{2, 3}, // sizes
{1, 2, 3, 4, 5, 6}, // data
ScalarType::Int,
TensorShapeDynamism::DYNAMIC_BOUND);
// Initial sizes: {2, 3}
// Number of elements: 6
resize_tensor_ptr(tensor, {2, 2});
// The tensor sizes are now {2, 2}
// Number of elements is 4 < initial 6
resize_tensor_ptr(tensor, {1, 3});
// The tensor sizes are now {1, 3}
// Number of elements is 3 < initial 6
resize_tensor_ptr(tensor, {3, 2});
// The tensor sizes are now {3, 2}
// Number of elements is 6 == initial 6
resize_tensor_ptr(tensor, {6, 1});
// The tensor sizes are now {6, 1}
// Number of elements is 6 == initial 6
便捷辅助函数¶
ExecuTorch 提供了几个便捷辅助函数来创建 tensor。
使用 for_blob 和 from_blob 创建非拥有 Tensor¶
这些辅助函数允许您创建不拥有数据的 tensor。
使用 from_blob()
float data[] = {1.0f, 2.0f, 3.0f};
auto tensor = from_blob(
data, // data pointer
{3}, // sizes
ScalarType::Float); // float scalar type
使用流畅语法和 for_blob()
double data[] = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0};
auto tensor = for_blob(data, {2, 3}, ScalarType::Double)
.strides({3, 1})
.dynamism(TensorShapeDynamism::STATIC)
.make_tensor_ptr();
使用自定义删除器和 from_blob()
int* data = new int[3]{1, 2, 3};
auto tensor = from_blob(
data, // data pointer
{3}, // sizes
ScalarType::Int, // int scalar type
[](void* ptr) { delete[] static_cast<int*>(ptr); });
当 TensorPtr 被销毁时，它将调用自定义删除器。
创建空 Tensor¶
empty() 创建一个指定 sizes 的未初始化 tensor。
auto tensor = empty({2, 3});
empty_like() 创建一个与现有 TensorPtr 具有相同 sizes 的未初始化 tensor。
TensorPtr original_tensor = /* some existing tensor */;
auto tensor = empty_like(original_tensor);
而 empty_strided() 创建一个指定 sizes 和 strides 的未初始化 tensor。
auto tensor = empty_strided({2, 3}, {3, 1});
创建填充特定值的 Tensor¶
full()、zeros() 和 ones() 分别创建一个填充有提供值、零或一的 tensor。
auto tensor_full = full({2, 3}, 42.0f);
auto tensor_zeros = zeros({2, 3});
auto tensor_ones = ones({3, 4});
与 empty() 类似，还有额外的辅助函数 full_like()、full_strided()、zeros_like()、zeros_strided()、ones_like() 和 ones_strided()，用于创建与现有 TensorPtr 具有相同属性或具有自定义 strides 的填充 tensor。
创建随机 Tensor¶
rand() 创建一个填充有 0 到 1 之间随机值的 tensor。
auto tensor_rand = rand({2, 3});
randn() 创建一个填充有来自正态分布的随机值的 tensor。
auto tensor_randn = randn({2, 3});
randint() 创建一个填充有指定 min（包含）和 max（不包含）整数之间的随机整数的 tensor。
auto tensor_randint = randint(0, 10, {2, 3});
创建标量 Tensor¶
除了使用单个数据值的 make_tensor_ptr() 外，您还可以使用 scalar_tensor() 创建一个标量 tensor。
auto tensor = scalar_tensor(3.14f);
请注意，scalar_tensor() 函数期望一个 Scalar 类型的值。在 ExecuTorch 中，Scalar 可以表示 bool、int 或浮点类型，但不能表示像 Half 或 BFloat16 等类型，对于这些类型您需要使用 make_tensor_ptr() 来跳过 Scalar 类型。
关于 EValue 和生命周期管理的注意事项¶
Module 接口期望数据以 EValue 的形式出现，EValue 是一个变体类型，可以容纳 Tensor 或其他标量类型。当您将 TensorPtr 传递给期望 EValue 的函数时，您可以解引用 TensorPtr 以获取底层 Tensor。
TensorPtr tensor = /* create a TensorPtr */
//...
module.forward(tensor);
或者甚至是一个 EValue vector 用于多个参数。
TensorPtr tensor = /* create a TensorPtr */
TensorPtr tensor2 = /* create another TensorPtr */
//...
module.forward({tensor, tensor2});
但是，请注意：EValue 不会持有 TensorPtr 中的动态数据和元数据。它仅持有一个常规的 Tensor，该 Tensor 不拥有数据或元数据，而是使用原始指针引用它们。您需要确保 TensorPtr 在 EValue 使用期间保持有效。
这同样适用于使用诸如 set_input() 或 set_output() 等期望 EValue 的函数时。
与 ATen 的互操作性¶
如果您的代码在编译时启用了预处理器标志 USE_ATEN_LIB，所有 TensorPtr API 将在底层使用 at:: API。例如，TensorPtr 变为 std::shared_ptr<at::Tensor>。这使得与 PyTorch ATen 库的集成无缝进行。
API 等效表¶
下表列出了 TensorPtr 创建函数与其对应的 ATen API 的对应关系
ATen |
ExecuTorch |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
最佳实践¶
谨慎管理生命周期：尽管
TensorPtr处理内存管理，但要确保任何非拥有的数据（例如，使用from_blob()时）在 tensor 使用期间保持有效。使用便捷函数：利用辅助函数来实现常见的 tensor 创建模式，以编写更简洁、更易读的代码。
注意数据所有权：了解您的 tensor 是拥有自己的数据还是引用外部数据，以避免意外的副作用或内存泄漏。
确保 TensorPtr 的生命周期长于 EValue：将 tensor 传递给期望
EValue的模块时，确保TensorPtr在EValue使用期间保持有效。
结论¶
ExecuTorch 中的 TensorPtr 通过将数据和动态元数据捆绑到一个智能指针中，简化了 tensor 内存管理。这种设计消除了用户管理多个数据部分的需要，并确保了更安全、更易于维护的代码。
通过提供与 PyTorch 的 ATen 库类似的接口，ExecuTorch 简化了新 API 的采用，使开发人员能够轻松过渡，没有陡峭的学习曲线。
