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

移動建構子 (Move ctor)。取得先前由 rhs 擁有的資源的所有權，並將 rhs 保留在未初始化的狀態。

ET_NODISCARD Error set_input (const EValue &input_evalue, size_t input_idx)

設定內部輸入值等同於提供的數值。

參數

• input_evalue – [in] 要複製到方法輸入中的 evalue。如果 evalue 是一個張量，則在大多數情況下會複製資料，因此此處傳入的張量不一定總是需要在此呼叫之後仍然有效。 但是，在某些情況下，Method 將保留指向張量資料的指標。基於該方法的記憶體計畫，輸入可能沒有預先分配的緩衝區空間。 在這種情況下，執行器將別名化 (alias) 作為輸入提供的張量的記憶體，而不是將輸入深度複製到記憶體計畫的區域中。

• 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)

將指定方法輸出的資料緩衝區設定為提供的值。

注意：基於該方法的記憶體計畫，輸出張量可能沒有預先分配的緩衝區空間，在這種情況下，執行器將把那些張量指向此處提供的緩衝區，因此使用者應注意此記憶體的壽命超過執行器的前向傳遞 (forward)。

參數

• buffer – [in] 將指定張量指向的記憶體塊。

• size – [in] 緩衝區的長度（以位元組為單位），必須 >= 指定張量的 nbytes。

• output_idx – [in] 設定 data_ptr 的輸出的索引。必須對應於一個張量，並且該張量必須沒有被記憶體計畫分配緩衝區。

回傳

成功時返回 Error::Ok，失敗時返回非 Ok。

ET_NODISCARD Error get_outputs (EValue *output_evalues, size_t length)

將方法輸出複製到提供的陣列中。

警告：輸出包含內部張量輸出的淺層副本 (shallow copies)。 請勿更改傳回的 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)

將方法輸入複製到提供的陣列中。

警告：輸入包含內部張量輸入的淺層副本 (shallow copies)。 請勿更改傳回的 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 成功

• 非 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

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

Public Members

Type segment_type

片段的類型。

size_t segment_index

片段在片段列表中的索引。 對於程式片段，此值未定義。

const char *descriptor

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

class 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::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)

已棄用：請改用 spans。

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

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)：一旦所有使用者都遷移到新的建構函式，就移除它。

inline MemoryAllocator *method_allocator() const

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

inline HierarchicalAllocator *planned_memory() const

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

inline MemoryAllocator *temp_allocator() const

傳回用於在核心或委派執行期間配置暫存資料的分配器。

此分配器將在每次執行期間的核心或委派呼叫後重置。

Values

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

傳回 tensor 的大小 (以位元組為單位)。

注意：僅傳回有效的空間，而不是底層資料 blob 的總容量。

inline ssize_t size(ssize_t dim) const

傳回給定維度上 tensor 的大小。

注意：即使 size() 傳回 SizeType 陣列的元素，它也有意不傳回 SizeType。 這是為了讓這個方法的呼叫更相容於 at::Tensor，並與此類別和 ETensor 中的其他方法更一致。

inline ssize_t dim() const

傳回 tensor 的維度數量。

inline ssize_t numel() const

傳回 tensor 中的元素數量。

inline ScalarType scalar_type() const

傳回 tensor 中元素的類型 (int32、float、bool 等)。

inline ssize_t element_size() const

傳回 tensor 中一個元素的大小 (以位元組為單位)。

inline const ArrayRef<SizesType> sizes() const

傳回 tensor 在每個維度上的大小。

inline const ArrayRef<DimOrderType> dim_order() const

傳回維度在記憶體中排列的順序。

inline const ArrayRef<StridesType> strides() const

傳回張量在每個維度上的 strides (步幅)。

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 中不存在，因此核心開發人員應避免使用它。