运行时 API 参考¶
ExecuTorch C++ API 为导出的 PyTorch 模型提供了设备端执行框架。
有关运行时 API 的教程式介绍,请查阅运行时教程及其简化版本。
有关 API 如何演变和弃用过程的详细信息,请参阅ExecuTorch API 生命周期和弃用策略。
模型加载与执行¶
-
class Program¶
反序列化的 ExecuTorch 程序二进制文件。
公有类型
公有函数
-
Result<const void*> get_constant_buffer_data(size_t buffer_idx, size_t nbytes) const¶
获取 Program 中索引为 buffer_idx 的常量缓冲区。
- 参数
buffer_idx – [输入] 常量缓冲区中缓冲区的索引。
nbytes – [输入] 要从缓冲区读取的字节数。
- 返回值
具有相应索引的缓冲区。
-
Result<const NamedDataMap*> get_named_data_map() const¶
从程序中获取命名数据映射。
- 返回值
命名数据映射。
-
size_t num_methods() const¶
返回程序中的方法数量。
-
Result<const char*> get_method_name(size_t method_index) const¶
返回特定索引处的方法名称。
- 参数
method_index – [输入] 要检索的方法名称的索引。必须小于 num_methods() 返回的值。
- 返回值
请求的方法名称。指针由 Program 所有,其生命周期与 Program 相同。
-
Result<Method> load_method(const char *method_name, MemoryManager *memory_manager, EventTracer *event_tracer = nullptr, const NamedDataMap *named_data_map = nullptr) const¶
加载命名方法并准备执行。
- 参数
method_name – [输入] 要加载的方法名称。
memory_manager – [输入] 在加载方法的初始化和执行期间使用的分配器。如果 memory_manager.temp_allocator() 为空,运行时将使用 et_pal_allocate() 分配临时内存。
event_tracer – [输入] 此方法运行时使用的事件跟踪器。
named_data_map – [输入] 一个可选的 {名称, blob} 映射,用于解析 PTE 外部的数据(如果存在)。
- 返回值
成功时返回加载的方法,失败时返回错误。
-
Result<MethodMeta> method_meta(const char *method_name) const¶
为命名方法收集元数据。
- 参数
method_name – [输入] 要获取元数据的方法名称。
- ET_DEPRECATED Result< const char * > get_output_flattening_encoding (const char *method_name="forward") const
已弃用:获取输出的 pytree 编码字符串。此功能已弃用,因为它最终将移出核心程序,进入更高级别的结构中,但目前该结构尚不存在。
- 参数
method_name – [输入] 要获取编码的方法名称。
- 返回值
输出的 pytree 编码字符串
公有静态函数
- static ET_NODISCARD Result< Program > load (DataLoader *loader, Verification verification=Verification::Minimal)
从提供的 loader 加载 Program。Program 将持有指向 loader 的指针,该 loader 的生命周期必须长于返回的 Program 实例。
- 参数
loader – [输入] 加载程序数据的来源。Program 将持有指向此 loader 的指针,该 loader 的生命周期必须长于返回的 Program 实例。
verification – [输入] 在返回成功之前要进行的验证类型。
- 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 – [输入] 文件开头可能包含 ExecuTorch 程序的数据。
size – [输入] data 的大小(字节)。必须 >= kMinHeadBytes。
- 返回值
描述数据中头部存在性的值。
公有静态属性
-
static constexpr size_t kMinHeadBytes = 64¶
调用 check_header 所需的最小字节数。
-
Result<const void*> get_constant_buffer_data(size_t buffer_idx, size_t nbytes) const¶
-
class Method¶
executorch 程序的可执行方法。映射到原始 nn.Module 上的 Python 方法,如 forward()。
公有函数
- ET_NODISCARD Error set_input (const EValue &input_evalue, size_t input_idx)
将内部输入值设置为与提供的值相等。
- 参数
input_evalue – [输入] 要复制到方法输入中的 evalue。如果 evalue 是一个张量,数据在大多数情况下会被复制,因此此处传入的张量不总是需要比此调用具有更长的生命周期。但在某些情况下,Method 将保留指向张量数据的指针。根据方法的内存规划,输入可能没有预分配的缓冲区空间。在这种情况下,executor 将直接引用此处作为输入提供的张量的内存,而不是将输入深度复制到内存规划区域。
input_idx – [输入] 要设置的输入的从零开始的索引。必须小于 inputs_size() 返回的值。
- 返回值
成功时返回 Error::Ok,失败时返回非 Ok 值。
- ET_NODISCARD Error set_inputs (const executorch::aten::ArrayRef< EValue > &input_evalues)
设置所有方法输入的值。
有关行为的更详细描述,请参阅 set_input()。
- 参数
input_evalues – [输入] 所有方法输入的新值。每个元素的类型必须与相应输入的类型匹配。如果元素的值是张量,会尝试允许动态形状,但 dtype 必须始终一致。
- 返回值
成功时返回 Error::Ok,失败时返回非 Ok 值。
- ET_NODISCARD Error set_output_data_ptr (void *buffer, size_t size, size_t output_idx)
将指定方法输出的数据缓冲区设置为提供的值。
注意:根据方法的内存规划,输出张量可能没有为其预分配缓冲区空间,在这种情况下,executor 将把这些张量指向此处提供的缓冲区,因此用户应确保此内存的生命周期长于 executor forward。
- 参数
buffer – [输入] 要让指定张量指向的内存块。
size – [输入] 缓冲区的长度(字节),必须 >= 指定张量的 nbytes。
output_idx – [输入] 要设置 data_ptr 的输出索引。必须对应一个张量,且该张量不能已由内存规划分配缓冲区。
- 返回值
成功时返回 Error::Ok,失败时返回非 Ok 值。
- ET_NODISCARD Error get_outputs (EValue *output_evalues, size_t length)
将方法的输出复制到提供的数组中。
警告:输出包含内部张量输出的浅拷贝。请勿修改返回的张量元素。
待办(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)
将方法的输入复制到提供的数组中。
警告:输入包含内部张量输入的浅拷贝。请勿修改返回的张量元素。
- 参数
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 – 步进成功
non-Ok – 步进失败
Error::EndOfMethod – 方法执行成功完成
- ET_DEPRECATED ET_NODISCARD Error experimental_step ()
已弃用:请使用
step()
代替。
- ET_EXPERIMENTAL ET_NODISCARD Error reset_execution ()
- ET_DEPRECATED ET_NODISCARD Error experimental_reset_execution ()
已弃用:请使用
reset_execution()
代替。
-
MethodMeta method_meta() const¶
返回对应于调用方的 MethodMeta。
- 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] 要查找的缓冲区索引。
- 返回值
成功时返回大小(以字节为单位),失败时返回错误。
-
bool uses_backend(const char *backend_name) const¶
检查此方法是否使用了后端。
- 参数
backend_name – [in] 要搜索的后端名称。
- 返回值
如果此方法使用了后端,则返回 true,否则返回 false。
-
size_t num_backends() const¶
获取此方法中使用的后端数量。
- 返回值
后端名称的总数。
-
Result<const char*> get_backend_name(size_t index) const¶
获取给定索引处的后端名称。
- 参数
index – [in] 后端名称的索引。
- 返回值
成功时返回一个包含后端名称(作为 C 风格字符串)的 Result,如果索引无效则返回错误。
- 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() 代替。
-
const char *name() const¶
-
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
返回底层数据源的长度,通常是文件大小。
-
class MemoryAllocator¶
一个基于大小进行简单分配并返回内存地址指针的类。它会标记特定大小的缓冲区。每次分配请求都会简单地检查空间并增长
cur_
指针。简单示例
// User allocates a 100 byte long memory in the heap. uint8_t* memory_pool = malloc(100 * sizeof(uint8_t)); MemoryAllocator allocator(100, memory_pool) // Pass allocator object in the Executor
在底层,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 的幂。- 返回值
成功时返回指向已分配内存的对齐指针。
公有静态属性
-
static constexpr size_t kDefaultAlignment = alignof(void*)¶
此类返回的内存的默认对齐方式。确保结构的指针字段是对齐的。然而,像
long double
这样的更大类型可能不会对齐,这取决于工具链和架构。
-
inline MemoryAllocator(uint32_t size, uint8_t *base_address)¶
-
class HierarchicalAllocator¶
可用于表示设备内存层次结构的缓冲器组。
公有函数
-
inline explicit HierarchicalAllocator(Span<Span<uint8_t>> buffers)¶
使用给定的缓冲器数组构造新的层次结构分配器。
内存 ID 基于在
buffers
中的索引:buffers[N]
将具有内存 IDN
。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 错误。
-
inline explicit HierarchicalAllocator(Span<Span<uint8_t>> buffers)¶
-
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] 在内核或 delegate 执行期间分配临时数据时使用的分配器。其生命周期必须长于使用它的 Method。如果 Method 不使用分配临时数据的内核或 delegate,则可以为
nullptr
。此分配器将在执行期间每次内核或 delegate 调用后重置。
-
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¶
-
inline HierarchicalAllocator *planned_memory() const¶
返回用于可变张量数据的内存规划缓冲器。
-
inline MemoryAllocator *temp_allocator() const¶
返回在内核或 delegate 执行期间用于分配临时数据的分配器。
此分配器将在执行期间每次内核或 delegate 调用后重置。
-
inline explicit MemoryManager(MemoryAllocator *method_allocator, HierarchicalAllocator *planned_memory = nullptr, MemoryAllocator *temp_allocator = nullptr)¶
值¶
-
struct EValue¶
公有函数
-
class Tensor¶
一个最小的 Tensor 类型,其 API 是 at::Tensor 的源兼容子集。
注意:此类的实例不拥有给定的 TensorImpl,这意味着调用方必须保证 TensorImpl 的生命周期长于指向它的任何 Tensor 实例。
有关此处使用的返回/参数类型及其与 at::Tensor 的关系,请参阅 TensorImpl 的文档。
公有类型
-
using DimOrderType = TensorImpl::DimOrderType¶
dim_order()
元素使用的类型。
公有函数
-
inline TensorImpl *unsafeGetTensorImpl() const¶
返回指向底层 TensorImpl 的指针。
注意:客户端应谨慎直接操作 TensorImpl 而非 Tensor。这样做容易出错。
-
inline size_t nbytes() const¶
返回张量的字节大小。
注意:仅返回活动空间的大小,而非底层数据块的总容量。
-
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<DimOrderType> dim_order() const¶
返回维度在内存中的布局顺序。
-
inline const ArrayRef<StridesType> strides() const¶
返回 tensor 在每个维度的步长。
-
inline TensorShapeDynamism shape_dynamism() const¶
返回 tensor 形状的可变性。
-
inline const void *const_data_ptr() const¶
返回指向常量底层数据 blob 的指针。
-
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
已废弃:改变 tensor 别名的 data_ptr。不会释放之前指向的数据,也不假定新指针的所有权语义。这个 API 在 at::Tensor 中不存在,因此内核开发者应避免使用它。
-
using DimOrderType = TensorImpl::DimOrderType¶