ExecuTorch 运行时 API 参考

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

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

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

模型加载和执行

class Program

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

公共类型

enum class Verification : uint8_t

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

值

enumerator Minimal

对数据进行最小化验证，确保标头看起来正确。

运行时开销最小。

enumerator InternalConsistency

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

运行时开销会更高，并随程序数据的复杂性而扩展。

enum HeaderStatus

描述 ExecuTorch 程序标头的存在状态。

值

enumerator CompatibleVersion

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

enumerator IncompatibleVersion

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

enumerator NotPresent

不存在 ExecuTorch 程序标头。

enumerator ShortData

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

公共函数

Result<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

返回程序中的方法数量。

Result<const char*> get_method_name(size_t method_index) const

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

参数

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

返回值

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

Result<Method> load_method(const char *method_name, MemoryManager *memory_manager, EventTracer *event_tracer = nullptr) const

加载指定名称的方法并准备执行。

参数

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

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

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

返回值

成功加载的方法，失败时返回错误。

Result<MethodMeta> method_meta(const char *method_name) const

收集指定名称方法的元数据。

参数

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

ET_DEPRECATED Result< const char * > get_output_flattening_encoding (const char *method_name="forward") const

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

参数

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

返回值

输出的 pytree 编码字符串

公共静态函数

static ET_NODISCARD Result< Program > load (DataLoader *loader, Verification verification=Verification::Minimal)

从提供的加载器加载Program。Program 将持有指向加载器的指针，该加载器的生命周期必须长于返回的Program实例。

参数

• loader – [in] 用于加载程序数据的源。Program 将持有指向此加载器的指针，该加载器的生命周期必须长于返回的Program实例。

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

static inline ET_DEPRECATED ET_NODISCARD Result< Program > Load (DataLoader *loader, Verification verification=Verification::Minimal)

已弃用：请改用小写load()。

static HeaderStatus check_header(const void *data, size_t size)

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

参数

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

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

返回值

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

公共静态属性

static constexpr size_t kMinHeadBytes = 64

调用check_header所需的最小字节数。

class Method

executorch 程序的可执行方法。映射到原始 nn.Module 上的 Python 方法，如forward()。

公共函数

inline Method(Method &&rhs) noexcept

移动构造函数。获取先前由rhs拥有的资源的所有权，并将rhs置于未初始化状态。

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，失败时返回非 Ok。

ET_NODISCARD Error set_inputs (const executorch::aten::ArrayRef< EValue > &input_evalues)

设置所有方法输入的值。

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

参数

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

返回值

成功时返回 Error::Ok，失败时返回非 Ok。

ET_NODISCARD Error set_output_data_ptr (void *buffer, size_t size, size_t output_idx)

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

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

参数

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

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

• output_idx – [in] 要为其设置 data_ptr 的输出索引。必须对应于张量，并且该张量不得具有内存计划分配的缓冲区。

返回值

成功时返回 Error::Ok，失败时返回非 Ok。

ET_NODISCARD Error get_outputs (EValue *output_evalues, size_t length)

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

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

TODO(T139259264)：添加检查以检测输出突变，或深层复制输出。

参数

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

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

返回值

成功时返回 Error::Ok，失败时返回非 Ok。

ET_NODISCARD Error get_inputs (EValue *input_evalues, size_t length)

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

警告：输入包含内部张量输入的浅拷贝。请不要更改返回的 Tensor 元素。

参数

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

• length – [in] input_evalues 数组中元素的长度。必须大于或等于 inputs_size()。

返回值

成功时返回 Error::Ok，失败时返回非 Ok。

ET_NODISCARD Error execute ()

执行方法。

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

返回值

成功时返回 Error::Ok，失败时返回非 Ok。

ET_EXPERIMENTAL ET_NODISCARD Error step ()

实验性功能：在方法中前进/执行单条指令。

返回值

• Error::Ok – step 成功

• non-Ok – step 失败

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

ET_DEPRECATED ET_NODISCARD Error experimental_step ()

已弃用：请改用 step()。

ET_EXPERIMENTAL ET_NODISCARD Error reset_execution ()

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

返回值

• Error:Ok – 成功时

• Error::InvalidState – 如果在基于 step 的执行到达 Method 结尾之前调用。这意味着无法恢复执行中失败的 Method。

ET_DEPRECATED ET_NODISCARD Error 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 输出。

class MethodMeta

描述 ExecuTorch 程序中的一个方法。

用于创建 MethodMeta 对象的程序必须比 MethodMeta 存活更久。它与 Method 分开，以便可以在不支付加载完整 Method 的初始化成本的情况下访问此信息。

公共函数

const char *name() const

获取此方法的名称。

返回值

方法名称。

size_t num_inputs() const

获取此方法的输入数量。

返回值

输入数量。

Result<Tag> input_tag(size_t index) const

获取指定输入的标签。

参数

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

返回值

输入的标签，只能是 [Tensor, Int, Bool, Double, String]。

Result<TensorInfo> input_tensor_meta(size_t index) const

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

参数

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

返回值

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

size_t num_outputs() const

获取此方法的输出数量。

返回值

输出数量。

Result<Tag> output_tag(size_t index) const

获取指定输出的标签。

参数

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

返回值

输出的标签，只能是 [Tensor, Int, Bool, Double, String]。

Result<TensorInfo> output_tensor_meta(size_t index) const

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

参数

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

返回值

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

size_t num_memory_planned_buffers() const

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

返回值

内存规划缓冲区的数量。

Result<int64_t> memory_planned_buffer_size(size_t index) const

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

参数

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

返回值

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

ET_EXPERIMENTAL size_t num_instructions () const

获取此方法中的指令数量。

返回值

指令数量。

inline 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()。

class DataLoader

从数据源加载数据。

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

公共函数

virtual ET_NODISCARD Result< FreeableBuffer > load (size_t offset, size_t size, const SegmentInfo &segment_info) const =0

从底层数据源加载数据。

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

参数

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

• size – 要加载的字节数。

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

返回值

拥有加载数据的 FreeableBuffer。

inline virtual ET_NODISCARD Error load_into (size_t offset, size_t size, const SegmentInfo &segment_info, void *buffer) const

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

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

参数

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

• size – 要加载的字节数。

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

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

返回值

指示加载是否成功的 Error。

virtual ET_NODISCARD Result< size_t > size () const =0

返回底层数据源的长度，通常是文件大小。

struct SegmentInfo

描述段的内容。

公共类型

enum class Type

表示段的用途。

值

enumerator Program

实际程序的数据。

enumerator Constant

保存常量张量数据。

enumerator Backend

用于初始化后端的数据。

enumerator Mutable

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

公共成员

Type segment_type

段的类型。

size_t segment_index

段在段列表中的索引。对于程序段，未定义。

const char *descriptor

描述段的可选的、空终止的字符串。对于 Backend 段，这是后端 ID。对于其他段类型，为空。

class MemoryAllocator

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

简单示例

// 用户在堆中分配一个 100 字节长的内存。 uint8_t* memory_pool = malloc(100 * sizeof(uint8_t)); MemoryAllocator allocator(100, memory_pool) // 在 Executor 中传递 allocator 对象

在底层，ExecuTorch 将调用 allocator.allocate() 以保持迭代 cur_ 指针

子类：executorch::runtime::internal::PlatformMemoryAllocator

公共函数

inline MemoryAllocator(uint32_t size, uint8_t *base_address)

构造一个给定 size 的新内存分配器，从提供的 base_address 开始。

参数

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

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

inline virtual void *allocate(size_t size, size_t alignment = kDefaultAlignment)

分配 size 字节的内存。

参数

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

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

返回值

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

返回值

成功时指向已分配内存的对齐指针。

template<typename T>
inline T *allocateInstance(size_t alignment = alignof(T))

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

示例

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

参数

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

返回值

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

返回值

成功时指向已分配内存的对齐指针。

template<typename T>
inline T *allocateList(size_t size, size_t alignment = alignof(T))

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

参数

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

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

返回值

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

返回值

成功时指向已分配内存的对齐指针。

公共静态属性

static constexpr size_t kDefaultAlignment = alignof(void*)

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

class HierarchicalAllocator

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

公共函数

inline explicit HierarchicalAllocator(Span<Span<uint8_t>> buffers)

构造具有给定缓冲区数组的新分层分配器。

• 内存 ID 基于 buffers 的索引：buffers[N] 将具有内存 ID 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 代替。

inline ET_NODISCARD Result< void * > get_offset_address (uint32_t memory_id, size_t offset_bytes, size_t size_bytes)

返回给定缓冲区的基地址偏移 offset_bytes 字节处的地址，该地址指向至少 size_bytes 大小的内存。

参数

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

• offset_bytes – [in] 指定缓冲区的字节偏移量。

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

返回值

成功时，返回指定缓冲区中请求的字节偏移地址。失败时，返回非 Ok 错误。

class MemoryManager

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

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

然而，此类不能确保所有分配都被考虑在内，因为内核和后端实现可以自由使用单独的方式来分配内存（例如，用于临时空间）。但我们建议后端和内核尽可能使用这些提供的分配器。

公共函数

inline explicit MemoryManager(MemoryAllocator *method_allocator, HierarchicalAllocator *planned_memory = nullptr, MemoryAllocator *temp_allocator = nullptr)

构造一个新的 MemoryManager。

参数

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

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

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

inline ET_DEPRECATED MemoryManager(MemoryAllocator *constant_allocator, HierarchicalAllocator *non_constant_allocator, MemoryAllocator *runtime_allocator, MemoryAllocator *temporary_allocator)

已弃用：请使用不带 constant_allocator 的构造函数代替。

TODO(T162089316): 一旦所有用户迁移到新的 ctor，就移除此项。

inline MemoryAllocator *method_allocator() const

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

inline HierarchicalAllocator *planned_memory() const

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

inline MemoryAllocator *temp_allocator() const

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

此分配器将在每次内核或委托调用后重置。

值

struct EValue

公共函数

inline EValue(executorch::aten::Scalar s)

使用 Scalar 的隐式值构造 EValue。

template<typename T>
inline executorch::aten::optional<T> toOptional() const

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

union Payload

union TriviallyCopyablePayload

class Tensor

最小的 Tensor 类型，其 API 是 at::Tensor 的源码兼容子集。

注意：此类的实例不拥有赋予它的 TensorImpl，这意味着调用者必须保证 TensorImpl 的生命周期长于指向它的任何 Tensor 实例。

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

公共类型

using SizesType = TensorImpl::SizesType

用于 sizes() 元素的类型。

using DimOrderType = TensorImpl::DimOrderType

用于 dim_order() 元素的类型。

using StridesType = TensorImpl::StridesType

用于 strides() 元素的类型。

公共函数

inline TensorImpl *unsafeGetTensorImpl() const

返回指向底层 TensorImpl 的指针。

注意：客户端应谨慎操作 TensorImpl 而不是 Tensor。很容易出错。

inline size_t nbytes() const

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

注意：仅返回存活空间，而不是底层数据 blob 的总容量。

inline ssize_t size(ssize_t dim) const

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

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

inline ssize_t dim() const

返回张量的维度数。

inline ssize_t numel() const

返回张量中的元素数量。

inline ScalarType scalar_type() const

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

inline ssize_t element_size() const

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

inline const ArrayRef<SizesType> sizes() const

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

inline const ArrayRef<DimOrderType> dim_order() const

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

inline const ArrayRef<StridesType> strides() const

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

inline TensorShapeDynamism shape_dynamism() const

返回张量形状的可变性。

template<typename T>
inline const T *const_data_ptr() const

返回指向常量底层数据 blob 的 T 类型指针。

inline const void *const_data_ptr() const

返回指向常量底层数据 blob 的指针。

template<typename T>
inline T *mutable_data_ptr() const

返回指向可变底层数据 blob 的 T 类型指针。

inline void *mutable_data_ptr() const

返回指向可变底层数据 blob 的指针。

template<typename T> inline ET_DEPRECATED T * data_ptr () const

已弃用：请使用 const_data_ptr 或 mutable_data_ptr 代替。

inline ET_DEPRECATED void * data_ptr () const

已弃用：请使用 const_data_ptr 或 mutable_data_ptr 代替。

inline ET_DEPRECATED void set_data (void *ptr) const

已弃用：更改张量别名化的 data_ptr。不释放先前指向的数据，不承担新 ptr 的所有权语义。此 API 在 at::Tensor 中不存在，因此内核开发人员应避免使用它。