ExecuTorch 入门¶

本节旨在介绍将 PyTorch 模型转换为 ExecuTorch 并运行所需的步骤。要使用该框架，您通常需要执行以下步骤：

安装 ExecuTorch python 包和运行时库。目标用户设备的要求取决于后端。有关更多信息，请参阅相应的后端文档。
导出 PyTorch 模型以适应目标硬件配置。
使用 ExecuTorch 运行时 API 在您的开发平台上运行模型。
使用 ExecuTorch 运行时将模型部署到目标平台。

系统要求¶

安装 ExecuTorch 主机库需要以下条件，这些库是导出模型和从 Python 运行模型所必需的。目标终端用户设备的要求取决于后端。有关更多信息，请参阅相应的后端文档。

Python 3.10 - 3.12
g++ 7 或更高版本，clang++ 5 或更高版本，或其他兼容 C++17 的工具链。
Linux (x86_64 或 ARM64) 或 macOS (ARM64)。
- 基于 Intel 的 macOS 系统需要从源代码构建 PyTorch（有关说明，请参阅从源代码构建）。
- Windows 通过 WSL 支持。

安装¶

要使用 ExecuTorch，您需要安装 Python 包和相应的特定平台运行时库。Pip 是安装 ExecuTorch Python 包的推荐方式。

此包包含导出 PyTorch 模型所需的依赖项，以及用于模型测试和评估的 Python 运行时绑定。请考虑在虚拟环境中安装 ExecuTorch，例如由 conda 或 venv 提供的虚拟环境。

pip install executorch

要从源代码构建框架，请参阅从源代码构建。后端委托可能需要额外的依赖项。有关更多信息，请参阅相应的后端文档。

准备模型¶

导出是将 PyTorch 模型转换为 ExecuTorch 运行时使用的 .pte 文件格式的过程。这是使用 Python API 完成的。像 Llama 3.2 这样的常用模型的 PTE 文件可以在 HuggingFace 的 ExecuTorch Community 下找到。这些模型已被导出并为 ExecuTorch 进行了优化，可以直接部署，无需经过优化过程。

一个完整的导出、优化和验证 MobileNet V2 的示例可在 Colab notebook 中找到。

要求¶

一个 PyTorch 模型。
示例模型输入，通常是 PyTorch 张量。您应该能够使用这些输入成功运行 PyTorch 模型。
一个或多个目标硬件后端。

选择后端¶

ExecuTorch 为各种硬件提供硬件加速。最常用的后端是 XNNPACK（用于 Arm 和 x86 CPU）、Core ML（用于 iOS）、Vulkan（用于 Android GPU）以及 Qualcomm（用于 Qualcomm 驱动的 Android 手机）。

对于移动用例，请首先考虑在 Android 上使用 XNNPACK，在 iOS 上使用 Core ML 或 XNNPACK。有关更多信息，请参阅硬件后端。

导出¶

导出是通过 Python API 完成的。ExecuTorch 在导出过程中提供了高度的定制性，但典型流程如下。此示例使用了 torchvision 中 MobileNet V2 图像分类模型的实现，但该过程支持任何符合导出要求的 PyTorch 模型。对于使用 Hugging Face 模型的用户，您可以在 huggingface/optimum-executorch 仓库中找到支持的模型列表。

import torch
import torchvision.models as models
from torchvision.models.mobilenetv2 import MobileNet_V2_Weights
from executorch.backends.xnnpack.partition.xnnpack_partitioner import XnnpackPartitioner
from executorch.exir import to_edge_transform_and_lower

model = models.mobilenetv2.mobilenet_v2(weights=MobileNet_V2_Weights.DEFAULT).eval()
sample_inputs = (torch.randn(1, 3, 224, 224), )

et_program = to_edge_transform_and_lower(
    torch.export.export(model, sample_inputs),
    partitioner=[XnnpackPartitioner()]
).to_executorch()

with open("model.pte", "wb") as f:
    f.write(et_program.buffer)

如果模型需要不同的输入大小，您需要在 export 调用中指定可变维度和边界。有关更多信息，请参阅模型导出和优化。

目标硬件后端由 to_edge_transform_and_lower 的 partitioner 参数控制。在此示例中，使用 XnnpackPartitioner 来定位移动 CPU。有关如何使用每个后端的信息，请参阅后端特定文档。

在此阶段还可以进行量化以减小模型大小和运行时。量化是后端特定的。有关支持的量化方案的完整描述，请参阅目标后端的文档。

测试模型¶

成功生成 .pte 文件后，通常使用 Python 运行时 API 在开发平台上验证模型。这可用于在设备上运行模型之前评估模型准确性。

对于此示例中使用的 torchvision 的 MobileNet V2 模型，图像输入应为标准化、float32 的张量，维度为 (batch, channels, height, width)。输出。有关此模型的输入和输出张量格式的更多信息，请参阅 torchvision.models.mobilenet_v2。

import torch
from executorch.runtime import Runtime
from typing import List

runtime = Runtime.get()

input_tensor: torch.Tensor = torch.randn(1, 3, 224, 224)
program = runtime.load_program("model.pte")
method = program.load_method("forward")
output: List[torch.Tensor] = method.execute([input_tensor])
print("Run succesfully via executorch")

from torchvision.models.mobilenetv2 import MobileNet_V2_Weights
import torchvision.models as models

eager_reference_model = models.mobilenetv2.mobilenet_v2(weights=MobileNet_V2_Weights.DEFAULT).eval()
eager_reference_output = eager_reference_model(input_tensor)

print("Comparing against original PyTorch module")
print(torch.allclose(output[0], eager_reference_output, rtol=1e-3, atol=1e-5))

有关导出和运行模型的完整示例，请参阅我们的示例 GitHub 仓库。

此外，如果您使用 Hugging Face 模型，huggingface/optimum-executorch 库可以简化使用熟悉的 Hugging Face API 与 ExecuTorch 端到端运行这些模型的过程。请访问该仓库以获取特定示例和支持的模型。

在设备上运行¶

ExecuTorch 提供 Java、Objective-C 和 C++ 的运行时 API。

快速链接

Android
iOS
C++

Android¶

安装¶

ExecuTorch 提供用于 Android 的 Java 绑定，可以从 Java 和 Kotlin 使用。要将库添加到您的应用中，请将以下依赖项添加到 gradle 构建规则中。

# app/build.gradle.kts
dependencies {
  implementation("org.pytorch:executorch-android:0.7.0")
}

# See latest available versions in https://mvnrepository.com/artifact/org.pytorch/executorch-android

运行时 API¶

可以使用 Module 类加载和运行模型。

import org.pytorch.executorch.EValue;
import org.pytorch.executorch.Module;
import org.pytorch.executorch.Tensor;

// …

Module model = Module.load("/path/to/model.pte");

Tensor input_tensor = Tensor.fromBlob(float_data, new long[] { 1, 3, height, width });
EValue input_evalue = EValue.from(input_tensor);
EValue[] output = model.forward(input_evalue);
float[] scores = output[0].toTensor().getDataAsFloatArray();

有关在 Android 上运行模型的完整示例，请参阅 DeepLabV3AndroidDemo。有关 Android 开发的更多信息，包括从源代码构建、Java API 的完整描述以及有关从 Android 原生代码使用 ExecuTorch 的信息，请参阅在 Android 上使用 ExecuTorch。

iOS¶

安装¶

ExecuTorch 通过 C++ 支持 iOS 和 macOS，以及 CoreML、MPS 和 CPU 的硬件后端。iOS 运行时库以 .xcframework 目标集合的形式提供，并可作为 Swift PM 包提供。

要开始使用 Xcode，请转到 File > Add Package Dependencies。将 ExecuTorch 仓库的 URL 粘贴到搜索栏中并选择它。请确保将分支名称更改为您想要的 ExecuTorch 版本，格式为“swiftpm-”，（例如，“swiftpm-0.6.0”）。也可以手动将 ExecuTorch 依赖项添加到包文件中。有关更多信息，请参阅在 iOS 上使用 ExecuTorch。

运行时 API¶

可以使用 C++ API 从 Objective-C 加载和运行模型。

有关 iOS 集成的更多信息，包括 API 参考、日志设置以及从源代码构建，请参阅在 iOS 上使用 ExecuTorch。

C++¶

ExecuTorch 提供 C++ API，可用于定位嵌入式或移动设备。C++ API 提供了比其他语言绑定更高的控制级别，支持高级内存管理、数据加载和平台集成。

安装¶

CMake 是 ExecuTorch C++ 运行时首选的构建系统。要与 CMake 一起使用，请将 ExecuTorch 仓库克隆到您的项目作为子目录，并使用 CMake 的 add_subdirectory("executorch") 来包含依赖项。将提供 executorch 目标以及内核和后端目标以供链接。运行时也可以独立构建以支持各种工具链。有关构建集成、目标和交叉编译的详细描述，请参阅使用 C++ 的 ExecuTorch。

git clone -b release/0.7 https://github.com/pytorch/executorch.git

# CMakeLists.txt
add_subdirectory("executorch")
...
target_link_libraries(
  my_target
  PRIVATE executorch
          extension_module_static
          extension_tensor
          optimized_native_cpu_ops_lib
          xnnpack_backend)

运行时 API¶

提供了高级和低级 C++ API。低级 API 是平台无关的，不动态分配内存，最适合资源受限的嵌入式系统。高级 API 作为低级 API 的便利包装器提供，并利用动态内存分配和标准库构造来减少冗长。

ExecuTorch 在原生构建中使用 CMake。集成通常通过克隆 ExecuTorch 仓库并使用 CMake add_subdirectory 来添加依赖项来完成。

可以使用高层 API 如下加载和运行模型

#include <executorch/extension/module/module.h>
#include <executorch/extension/tensor/tensor.h>

using namespace ::executorch::extension;

// Load the model.
Module module("/path/to/model.pte");

// Create an input tensor.
float input[1 * 3 * 224 * 224];
auto tensor = from_blob(input, {1, 3, 224, 224});

// Perform an inference.
const auto result = module.forward(tensor);

if (result.ok()) {
  // Retrieve the output data.
  const auto output = result->at(0).toTensor().const_data_ptr<float>();
}

有关 C++ API 的更多信息，请参阅在 C++ 中使用 Module 扩展运行 ExecuTorch 模型和在 C++ 中管理 Tensor 内存。

有关构建和运行 C++ 应用程序的完整示例，请参阅我们的示例 GitHub 仓库。

下一步¶

ExecuTorch 提供了高度的可定制性，以支持各种硬件目标。根据您的用例，请考虑探索以下一个或多个页面：

导出和优化，用于高级模型转换选项。
后端概述，有关可用的后端和配置选项。
在 Android 上使用 ExecuTorch 和在 iOS 上使用 ExecuTorch，用于移动运行时集成。
使用 C++ 的 ExecuTorch，用于嵌入式和移动原生开发。
性能剖析和调试，用于开发人员工具和调试。
API 参考，有关可用 API 的完整描述。
示例，有关演示应用程序和示例代码。

ExecuTorch 入门¶

系统要求¶

安装¶

准备模型¶

要求¶

选择后端¶

导出¶

测试模型¶

在设备上运行¶

Android¶

安装¶

运行时 API¶

iOS¶

安装¶

运行时 API¶

C++¶

安装¶

运行时 API¶

下一步¶

文档

教程

资源