ExecuTorch 运行时 API 参考

ExecuTorch C++ API 为导出的 PyTorch 模型提供了设备端执行框架。

有关运行时 API 的教程样式介绍，请查看运行时教程及其简化版本。

有关 API 如何发展和弃用过程的详细信息，请参阅 ExecuTorch API 生命周期和弃用策略。

模型加载和执行

类程序

反序列化的 ExecuTorch 程序二进制文件。

公共类型

enum 类验证 ： uint8_t

程序在解析数据之前可以执行的验证类型。

值：

enumerator 最小

对数据进行最低限度的验证，确保标头显示正确。

运行时开销最小。

枚举器 InternalConsistency

对数据进行全面验证，确保内部指针自洽，并且数据未被截断或明显损坏。可能无法捕获所有类型的损坏，但应在解析期间防止非法内存操作。

将具有更高的运行时开销，并随着 proram 数据的复杂性而扩展。

枚举 HeaderStatus

描述 ExecuTorch 程序头文件的存在。

值：

枚举器 CompatibleVersion

存在 ExecuTorch 程序头文件，并且其版本与此版本的运行时兼容。

枚举器 IncompatibleVersion

存在 ExecuTorch 程序头文件，但其版本与此版本的运行时不兼容。

枚举器 NotPresent

不存在 ExecuTorch 程序标头。

枚举器 ShortData

提供的数据太短，无法找到程序标头。

公共函数

结果<const void*> get_constant_buffer_data（size_t buffer_idx， size_t nbytes） const

获取 Program 中索引为 buffer_idx的常量缓冲区。

参数

• buffer_idx – [in] 缓冲区在 constant_buffer 中的索引。

• nbytes – [in] 要从缓冲区读取的字节数。

返回

具有相应索引的缓冲区。

size_t num_methods（） const

返回程序中方法的数目。

结果<const char*> get_method_name（size_t method_index） const

返回特定索引处的方法名称。

参数

method_index – [in] 要检索的方法名称的索引。必须小于 返回的值。num_methods()

返回

请求的方法的名称。指针归 Program 所有，并且与 Program 具有相同的生存期。

结果<方法> load_method（const char *method_name， MemoryManager *memory_manager，EventTracer *event_tracer = nullptr） const

加载命名方法并准备执行。

参数

• method_name – [in] 要加载的方法的名称。

• memory_manager – [in] 在初始化和执行 loaded 方法期间使用的分配器。如果为 null，则运行时将使用 分配临时内存。memory_manager.temp_allocator()et_pal_allocate()

• event_tracer – [in] 用于此方法运行的事件跟踪器。

返回

成功时加载的方法，失败时出错。

结果<MethodMeta> method_meta（const char *method_name） const

收集命名方法的元数据。

参数

method_name – [in] 要获取元数据的方法的名称。

ET_DEPRECATED 结果< const char * > get_output_flattening_encoding （const char *method_name=“forward”） const

已弃用：获取输出的 pytree 编码字符串。已弃用，因为此功能最终会从核心程序中移动到更高级别的结构中，但目前不存在。

参数

method_name – [in] 要获取其编码的方法的名称。

返回

输出的 pytree 编码字符串

公共静态函数

static ET_NODISCARD Result< 程序>加载 （DataLoader *loader， Verification verification=Verification：：Minimal）

从提供的加载程序加载程序。Program 将保存一个指向 loader 的指针，该指针必须比返回的 Program 实例长。

参数

• loader – [in] 从中加载程序数据的源。Program 将保存指向此 loader 的指针，该指针必须比返回的 Program 实例长。

• verification – [in] 返回 success 之前要执行的验证类型。

静态内联ET_DEPRECATED ET_NODISCARD Result< 程序>加载 （DataLoader *loader， Verification verification=Verification：：Minimal）

DEPRECATED： 请改用小写字母。load()

static HeaderStatus check_header（const void *data， size_t 大小)

在提供的数据中查找 ExecuTorch 程序头文件。

参数

• data – [in] 可能包含 ExecuTorch 程序的文件开头的数据。

• size – [in] 的大小（以字节为单位）。必须为 >= 。datakMinHeadBytes

返回

描述数据中存在标头的值。

公共静态属性

static constexpr size_t kMinHeadBytes = 64

调用 .check_header

class 方法

executorch 程序的可执行方法。映射到 python 方法，如原始 nn.模块。forward()

公共函数

内联方法（方法 &&rhs） noexcept

Move ctor.获取以前由 拥有的资源的所有权，并保留未初始化状态。rhsrhs

ET_NODISCARD Error set_input （const EValue &input_evalue， size_t input_idx）

将内部输入值设置为等效于提供的值。

参数

• input_evalue – [in] 要复制到方法输入中的 evalue。如果 evalue 是一个张量，则在大多数情况下都会复制数据，因此此处传入的张量并不总是需要比此调用长寿。但是在某些情况下，Method 将保留指向张量数据的指针。根据方法的内存计划，输入可能没有预先为其分配缓冲区空间。在这种情况下，执行程序将在此处作为输入提供的张量的内存别名，而不是将输入深度复制到内存计划的竞技场中。

• input_idx – [in] 要设置的输入的从零开始的索引。必须小于 inputs_size（） 返回的值。

返回

Error：：Ok 表示成功，失败时为 non-Ok。

ET_NODISCARD 错误 set_inputs （const executorch：：aten：：ArrayRef< EValue > &input_evalues）

设置所有方法输入的值。

有关行为的更详细描述，请参阅 set_input（） 。

参数

input_evalues – [in] 所有方法输入的新值。每个元素的类型必须与相应输入的类型匹配。如果元素的值是张量，则尝试允许动态形状，但 dtype 必须始终一致。

返回

Error：：Ok 表示成功，失败时为 non-Ok。

ET_NODISCARD 错误set_output_data_ptr （void *buffer、size_t size、size_t output_idx）

将指定方法输出的数据缓冲区设置为提供的值。

注意：根据该方法的内存计划，输出张量可能没有预先为其分配缓冲区空间，在这种情况下，执行程序会将这些张量指向此处提供的缓冲区，因此用户应注意此内存的寿命比执行程序的寿命更长。

参数

• buffer – [in] 要将指定张量指向的内存块。

• size – [in] 缓冲区的长度（以字节为单位），必须>= 指定张量的 nbytes。

• output_idx – [in] 要为其设置data_ptr的输出的索引。必须对应于一个 tensor，并且该 tensor 必须没有由 memory plan 分配的缓冲区。

返回

Error：：Ok 表示成功，失败时为 non-Ok。

ET_NODISCARD 误差get_outputs （EValue *output_evalues， size_t length）

将方法的输出复制到提供的数组中。

警告：输出包含内部张量输出的浅表副本。请不要更改返回的 Tensor 元素。

TODO（T139259264）：添加检查以检测输出更改或深拷贝输出。

参数

• output_evalues – [in] 要将输出复制到的数组。第一个元素将设置为相应的输出值。数组的其余部分将设置为 EValue 值 None。outputs_size()

• length – [in] 数组的大小（以元素为单位）。必须大于或等于 。output_evaluesoutputs_size()

返回

Error：：Ok 表示成功，失败时为 non-Ok。

ET_NODISCARD 误差get_inputs （EValue *input_evalues， size_t length）

将方法的输入复制到提供的数组中。

警告： input 包含内部 Tensor Inputs 的浅表副本。请不要更改返回的 Tensor 元素。

参数

• input_evalues – [in] 要将输入复制到的数组。第一个元素将设置为相应的 input 值。数组的其余部分将设置为 EValue 值 None。inputs_size()

• length – [in] 数组的大小（以元素为单位）。必须大于或等于 。input_evaluesinputs_size()

返回

Error：：Ok 表示成功，失败时为 non-Ok。

ET_NODISCARD 错误执行 （）

执行该方法。

注意：如果该方法已使用 API 部分执行，则将失败。step()

返回

Error：：Ok 表示成功，失败时为 non-Ok。

ET_EXPERIMENTAL ET_NODISCARD 错误步骤 （）

实验性：推进/执行方法中的单个指令。

返回值

• Error：：Ok – 步骤成功

• non-Ok – 步骤失败

• Error：：EndOfMethod – 方法成功完成执行

ET_DEPRECATED ET_NODISCARD 错误 experimental_step （）

已弃用：请改用。step()

ET_EXPERIMENTAL ET_NODISCARD 错误 reset_execution （）

实验性：将执行状态重置为 Method 的开头。用于 API。step()

返回值

• 错误：正常 – 成功

• Error：：InvalidState – 如果在基于步骤的执行到达 Method 末尾之前调用。这意味着无法恢复在执行过程中失败的方法。

ET_DEPRECATED ET_NODISCARD 错误 experimental_reset_execution （）

已弃用：请改用。reset_execution()

MethodMeta method_meta（） const

返回与调用 Method 对应的 MethodMeta。

size_t inputs_size（） const

返回 Method 期望的输入数。

size_t outputs_size（） const

返回 Method 返回的输出数。

const EValue &get_output（size_t i） const

检索指定索引处的输出。

ET_DEPRECATED const EValue & get_input （size_t i） const

已弃用：改用 MethodMeta 访问元数据，并使用 set_input 更新 Method 输入。

ET_DEPRECATED EValue & mutable_input （size_t i）

已弃用：改用 MethodMeta 访问元数据，并使用 set_input 更新 Method 输入。

ET_DEPRECATED EValue & mutable_output （size_t i）

已弃用：改用 MethodMeta 访问元数据，并使用 get_output 检索 Method 输出。

类 MethodMeta

描述 ExecuTorch 程序中的方法。

用于创建 MethodMeta 对象的程序必须比 MethodMeta 长。它与 Method 是分开的，因此可以访问此信息，而无需支付加载完整 Method 的初始化成本。

公共函数

const char *name（） const

获取此方法的名称。

返回

方法名称。

size_t num_inputs（） const

获取此方法的输入数。

返回

输入的数量。

结果<Tag> input_tag（size_t index） const

获取指定输入的标签。

参数

index – [in] 要查找的输入的索引。

返回

input 的 tag 只能是 [Tensor， Int， Bool， Double， String]。

结果<TensorInfo> input_tensor_meta（size_t index） const

获取有关指定输入的元数据。

参数

index – [in] 要查找的输入的索引。

返回

成功时的元数据，或失败时的错误。仅对 tag：：Tensor 有效

size_t num_outputs（） const

获取此方法的输出数。

返回

输出的数量。

结果<标签> output_tag（size_t 索引） const

获取指定输出的 tag。

参数

index – [in] 要查找的输出的索引。

返回

output 的 tag 只能是 [Tensor， Int， Bool， Double， String]。

结果<TensorInfo> output_tensor_meta（size_t index） const

获取有关指定输出的元数据。

参数

index – [in] 要查找的输出的索引。

返回

成功时的元数据，或失败时的错误。仅对 tag：：Tensor 有效

size_t num_memory_planned_buffers（） const

获取此方法所需的内存计划缓冲区数。

返回

内存计划缓冲区的数量。

结果<int64_t> memory_planned_buffer_size（size_t index） const

获取指定内存计划缓冲区的大小（以字节为单位）。

参数

index – [in] 要查找的缓冲区的索引。

返回

成功时的大小（以字节为单位），失败时为错误。

内联 ET_DEPRECATED size_t num_non_const_buffers （） const

已弃用：请改用 num_memory_planned_buffers（）。

inline Result<int64_t> non_const_buffer_size（size_t index） const

已弃用： 请改用 memory_planned_buffer_size（）。

类 DataLoader

从数据源加载。

有关常见实现，请参阅 //executorch/extension/data_loader。

公共函数

虚拟ET_NODISCARD结果<FreeableBuffer > 加载（size_t 偏移量、size_t大小、const SegmentInfo &segment_info） const =0

从基础数据源加载数据。

注意：这必须是线程安全的。如果此调用修改了公共状态，则实现必须执行自己的锁定。

参数

• offset – 数据源中要从中开始加载的字节偏移量。

• size – 要加载的字节数。

• segment_info – 有关正在加载的分段的信息。

返回

a 拥有加载的数据。FreeableBuffer

内联虚拟ET_NODISCARD错误 load_into （size_t offset， size_t size， const SegmentInfo &segment_info， void *buffer） const

将数据从基础数据源加载到提供的缓冲区中。

注意：这必须是线程安全的。如果此调用修改了公共状态，则实现必须执行自己的锁定。

参数

• offset – 数据源中要从中开始加载的字节偏移量。

• size – 要加载的字节数。

• segment_info – 有关正在加载的分段的信息。

• buffer – 要将数据加载到其中的缓冲区。必须至少指向字节的内存。size

返回

指示加载是否成功的 Error 。

虚拟ET_NODISCARD结果<size_t > 大小 （） const =0

返回基础数据源的长度，通常为文件大小。

struct SegmentInfo

描述区段的内容。

公共类型

enum 类类型

表示区段的用途。

值：

enumerator 程序

实际程序的数据。

enumerator 常量

保存常量张量数据。

enumerator 后端

用于初始化后端的数据。

枚举器 可变

用于初始化可变张量的数据。

公共会员

类型 segment_type

区段的类型。

size_t segment_index

区段列表中区段的索引。未定义 节目区段。

const char *descriptor

一个可选的以 null 结尾的字符串，用于描述分段。对于分段，这是后端 ID。对于其他分段类型，为 Null。Backend

类 MemoryAllocator

一个基于大小执行简单分配并返回指向内存地址的指针的类。它将具有特定大小的缓冲区添加书签。分配只是检查空间并随每个分配请求增加 cur_ 指针。

简单示例：

用户在堆中分配 100 字节长的内存。uint8_t* memory_pool = malloc（100 * sizeof（uint8_t））;MemoryAllocator allocator（100， memory_pool） // 在 Executor 中传递分配器对象

在后台，ExecuTorch 将调用 allocator.allocate（） 来继续迭代cur_指针

由 executorch：：runtime：：internal：:P latformMemoryAllocator 子类化

公共函数

inline MemoryAllocator（uint32_t 大小，uint8_t *base_address)

构造给定 的新内存分配器 ，从提供的 .sizebase_address

参数

• size – [in] 缓冲区的大小（以字节为单位）。base_address

• base_address – [in] 要从中分配的缓冲区。不获取此缓冲区的所有权，因此它必须在 MemoryAllocator 的生存期内有效。

内联虚拟 void *allocate（size_t 大小，size_t对齐 = kDefaultAlignment)

分配内存字节数。size

参数

• size – [in] 要分配的字节数。

• alignment – [in] 返回的指针的最小对齐方式。必须是 2 的幂。

返回值

nullptr – 内存不足，或者不是 2 的幂。alignment

返回

成功时将指针对齐到分配的内存。

template<typename T>
inline T *allocateInstance（size_t 对齐 = 对齐（T))

为 T 类型的实例分配足够大的缓冲区。请注意，不会初始化内存。

例：

auto p = memory_allocator->allocateInstance<MyType>();

参数

alignment – [in] 返回的指针的最小对齐方式。必须是 2 的幂。默认为 T 的自然对齐方式。

返回值

nullptr – 内存不足，或者不是 2 的幂。alignment

返回

成功时将指针对齐到分配的内存。

template<typename T>
inline T *allocateList（size_t size， size_t 对齐 = alignof（T))

分配类型 T 的块数，其中每个块的大小等于 sizeof（T） 字节。size

参数

• size – [in] 要分配的内存块数。

• alignment – [in] 返回的指针的最小对齐方式。必须是 2 的幂。默认为 T 的自然对齐方式。

返回值

nullptr – 内存不足，或者不是 2 的幂。alignment

返回

成功时将指针对齐到分配的内存。

公共静态属性

static constexpr size_t kDefaultAlignment = alignof（void*)

此类返回的内存的默认对齐方式。确保结构体的指针字段将对齐。但是，较大的类型（如）可能不是，具体取决于工具链和架构。long double

类 HierarchicalAllocator

一组可用于表示设备内存层次结构的缓冲区。

公共函数

内联显式 HierarchicalAllocator（Span<Span<uint8_t>> 缓冲区)

使用给定的缓冲区数组构造一个新的分层分配器。

• 内存 ID 基于索引 into ： 将具有内存 ID 。buffersbuffers[N]N

• buffers.size()必须为 >= 。MethodMeta::num_non_const_buffers()

• buffers[N].size()必须为 >= 。MethodMeta::non_const_buffer_size(N)

inline ET_DEPRECATED HierarchicalAllocator（uint32_t n_allocators， MemoryAllocator *allocators)

已弃用：请改用 span。

内联 ET_NODISCARD 结果< void * > get_offset_address （uint32_t memory_id、size_t offset_bytes、size_t size_bytes）

返回与给定缓冲区的基址的字节偏移量处的地址，该地址至少指向内存。offset_bytessize_bytes

参数

• memory_id – [in] 层次结构中缓冲区的 ID。

• offset_bytes – [in] 指定缓冲区的偏移量（以字节为单位）。

• size_bytes – [in] 偏移量应可用的内存量。

返回

成功后，请求的字节偏移量的地址将进入指定的缓冲区。失败时，非 Ok 错误。

类 MemoryManager

在 Method 加载和执行期间使用的分配器的容器类。

此类整合了 Method 加载和执行的所有动态内存需求。这可以允许基于堆和无堆的执行（与某些嵌入式场景相关），并且总体上提供了对内存使用的更多控制。

但是，此类无法确保所有分配都被考虑在内，因为 kernel 和 backend implementations可以自由使用单独的方式来分配内存（例如，对于暂存空间之类的东西）。但我们确实建议后端和内核尽可能使用这些提供的分配器。

公共函数

内联显式 MemoryManager（MemoryAllocator *method_allocator， HierarchicalAllocator *planned_memory = nullptr，MemoryAllocator *temp_allocator = nullptr)

构造新的 MemoryManager。

参数

• method_allocator – [in] 加载 Method 并分配其内部结构时使用的分配器。必须比使用它的 Method 活得更久。

• planned_memory – [in] 执行 Method 时用于可变张量数据的内存计划缓冲区。必须比使用它的 Method 活得更久。如果 Method 不使用任何内存计划的张量数据，则可能是。此 HierarchicalAllocator 中缓冲区的大小必须与嵌入在 Program 中的相应 and 值一致。nullptrMethodMeta::num_memory_planned_buffers()MethodMeta::memory_planned_buffer_size(N)

• temp_allocator – [in] 在内核或委托执行期间分配临时数据时使用的分配器。必须比使用它的 Method 活得更久。如果 Method 不使用分配临时数据的内核或委托，则可能是这样。在执行期间，此分配器将在每次内核或 delegate 调用后重置。nullptr

内联 ET_DEPRECATED MemoryManager（__attribute__（（未使用）） MemoryAllocator *constant_allocator， HierarchicalAllocator *non_constant_allocator、MemoryAllocator *runtime_allocator、MemoryAllocator *temporary_allocator)

已弃用：使用 constructor without instead。constant_allocator

TODO（T162089316）：在所有用户迁移到新 ctor 后删除此项。

内联 MemoryAllocator *method_allocator（） const

返回运行时在加载 Method 时将用于分配内部结构的分配器。在加载其关联的 Method 后，不得使用。

内联 HierarchicalAllocator *planned_memory（） const

返回用于可变张量数据的内存计划缓冲区。

内联 MemoryAllocator *temp_allocator（） const

返回用于在内核或 delegate 执行期间分配临时数据的分配器。

在执行期间，此分配器将在每次内核或 delegate 调用后重置。

值

struct EValue

公共函数

inline EValue（executorch：：aten：：Scalar s)

使用 Scalar 的隐式值构造 EValue。

template<typename T>
inline executorch：：aten：：optional<T> toOptional（） 常量

将 EValue 转换为可表示 T 和未初始化状态的可选对象。

union 有效负载

union TriviallyCopyablePayload

类 Tensor

一个最小的 Tensor 类型，其 API 是 at：：Tensor 的源兼容子集。

注意：此类的实例不拥有给定给它的 TensorImpl，这意味着调用方必须保证 TensorImpl 的生存期比指向它的任何 Tensor 实例长。

有关此处使用的 return/parameter 类型以及它们与 at：：Tensor 的关系的详细信息，请参阅有关 TensorImpl 的文档。

公共类型

使用 SizesType = TensorImpl：：SizesType

用于 的元素的类型。sizes()

使用 DimOrderType = TensorImpl：：DimOrderType

用于 的元素的类型。dim_order()

使用 StridesType = TensorImpl：：StridesType

用于 的元素的类型。strides()

公共函数

内联 TensorImpl *unsafeGetTensorImpl（） const

返回指向底层 TensorImpl 的指针。

注意：客户端应警惕直接在 TensorImpl 上操作，而不是在 Tensor 上操作。破坏东西很容易。

内联 size_t nbytes（） const

返回张量的大小（以字节为单位）。

注意：仅返回活动空间，而不返回基础数据 blob 的总容量。

内联 ssize_t size（ssize_t dim） const

返回给定维度的张量大小。

注意：size（） 故意不返回 SizeType，即使它返回 SizeType 数组的元素。这是为了帮助使此方法的调用与 at：：Tensor 更兼容，并与此类和 ETensor 中的其余方法更加一致。

内联 ssize_t dim（） const

返回张量的维度数。

内联 ssize_t numel（） const

返回张量中的元素数。

内联 ScalarType scalar_type（） const

返回张量中元素的类型（int32、float、bool 等）。

内联 ssize_t element_size（） const

返回张量的一个元素的大小（以字节为单位）。

内联 const ArrayRef<SizesType> sizes（） const

返回每个维度的张量大小。

内联 const ArrayRef<DimOrderType> dim_order（） ） const

返回维度在内存中的布局顺序。

内联 const ArrayRef<StridesType> strides（） const

返回张量在每个维度上的步幅。

内联 TensorShapeDynamism shape_dynamism（） const

返回张量形状的可变性。

template<typename T>
inline const T *const_data_ptr（） const

返回指向常量基础数据 blob 的 T 类型的指针。

内联 const void *const_data_ptr（） const

返回指向常量基础数据 blob 的指针。

template<typename T>
inline T *mutable_data_ptr（） const

返回指向可变基础数据 blob 的 T 类型的指针。

内联 void *mutable_data_ptr（） const

返回指向可变基础数据 blob 的指针。

template<typename T> 内联 ET_DEPRECATED T * data_ptr （） const

已弃用：请改用 const_data_ptr 或 mutable_data_ptr。

内联 ET_DEPRECATED void * data_ptr （） const

已弃用：请改用 const_data_ptr 或 mutable_data_ptr。

内联 ET_DEPRECATED void set_data （void *ptr） const

DEPRECATED：更改张量别名data_ptr。不释放以前指向的数据，不假定新 ptr 的所有权语义。at：：Tensor 中不存在此 api，因此内核开发人员应避免使用它。