執行時 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 – [輸入] 常量緩衝區中緩衝區的索引。

• 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 所需的最小位元組數。

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 – [輸入] 要複製到方法輸入中的 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 ()

實驗性：將執行狀態重置為 Method 的起始位置。用於搭配 step() API 使用。

返回值

• Error:Ok – 成功時

• Error::InvalidState – 如果在基於步進的執行到達 Method 末尾之前呼叫。這意味著無法恢復在執行中途失敗的 Method。

ET_DEPRECATED ET_NODISCARD Error experimental_reset_execution ()

已棄用：請使用 reset_execution() 代替。

MethodMeta method_meta() const

返回對應於呼叫方的 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] 要查詢的緩衝區索引。

返回值

成功時返回大小（以位元組為單位），失敗時返回錯誤。

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() 代替。

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

用於初始化可變張量的資料。

enumerator External

用於初始化外部張量的資料。

公有成員

Type segment_type

段的型別。

size_t segment_index

段在段列表中的索引。對程式段未定義。

const char *descriptor

一個可選的、以 null 結尾的字串，描述該段。對於 Backend 段，這是後端 ID。對於其他段型別，為 Null。

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 的冪。

返回值

成功時返回指向已分配記憶體的對齊指標。

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] 在核心或 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

返回執行時在載入 Method 並分配其內部結構時將使用的分配器。在其關聯的 Method 載入後不得使用。

inline HierarchicalAllocator *planned_memory() const

返回用於可變張量資料的記憶體規劃緩衝器。

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

返回張量的位元組大小。

注意：僅返回活動空間的大小，而非底層資料塊的總容量。

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

返回 tensor 在每個維度的步長。

inline TensorShapeDynamism shape_dynamism() const

返回 tensor 形狀的可變性。

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

已廢棄：改變 tensor 別名的 data_ptr。不會釋放之前指向的資料，也不假定新指標的所有權語義。這個 API 在 at::Tensor 中不存在，因此核心開發者應避免使用它。