• 文档 >
  • 在 Android 上使用 ExecuTorch
快捷方式

在 Android 上使用 ExecuTorch

为了在 Android 上使用,ExecuTorch 提供了 Java/Kotlin API 绑定和 Android 平台集成,并以 AAR 文件形式提供。

注意:本页介绍通过 AAR 库进行 Android 应用集成。ExecuTorch 的 C++ API 也可以用于 Android native 开发,相关文档可在有关交叉编译的本页面上找到。

安装

所有 ExecuTorch Android 库都打包到一个 Android 库 (AAR) 中,即 executorch.aar,用于通用(图像/音频处理)和 LLM (LLaMA) 用例。在每个版本发布时,预构建的 AAR 文件会被上传到 Maven 和 S3。用户也可以从源代码构建 AAR。

库内容

AAR 文件包含供用户集成到其 Java/Kotlin 应用代码中的 Java 库,以及相应的 JNI 库(.so 文件),该文件在 Java 代码初始化时加载。

  • Java 库

  • JNI 包含相应 Java 代码的 JNI 绑定以及 ExecuTorch native 库,包括

    • 核心 ExecuTorch 运行时库

    • XNNPACK 后端

    • 可移植 kernels

    • 优化 kernels

    • 量化 kernels

    • LLaMa 特定的自定义 ops 库。

  • 提供两种 ABI 变体:arm64-v8a 和 x86_64。

该 AAR 库可用于具有 arm64-v8a 或 x86_64 架构的通用 Android 设备。它适用于各种外形因素,包括手机、平板电脑、电视盒等,因为它不包含任何 UI 组件。

从 Maven Central 使用 AAR

ExecuTorch 可在 Maven Central 上获得。

只需将目标 org.pytorch:executorch-android:0.6.0-rc1 添加到您的 Android 应用依赖项 (build.gradle) 中,然后构建您的应用。

例如

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

注意:如果您想使用 v0.5.0 版本,请使用依赖项 org.pytorch:executorch-android:0.5.1

单击下面的截图观看关于如何在 Android Studio 中添加软件包并运行简单 ExecuTorch 模型的演示视频在 Android 上集成并运行 ExecuTorch

直接使用 AAR 文件

您也可以直接在应用中指定 AAR 文件。我们在每次发布时或作为快照将预构建的 AAR 上传到 S3。

main 分支的快照

日期

AAR

SHASUMS

2025-02-27

executorch.aar

executorch.aar.sha256sums

使用 AAR 文件

将 AAR 文件添加到您的应用中

  1. 下载 AAR。

  2. 将其作为文件路径添加到您的 gradle 构建规则中。

AAR 文件本身不包含依赖信息,不像 Maven 仓库中的文件捆绑了 pom.xml。Java 包需要 fbjnisoloader,目前要求用户显式声明依赖项。因此,gradle 规则中还需要另外两个 dependencies

implementation("com.facebook.soloader:soloader:0.10.5")
implementation("com.facebook.fbjni:fbjni:0.5.1")

示例用法

在您的应用工作目录中,例如 executorch/examples/demo-apps/android/LlamaDemo,

mkdir -p app/libs
curl https://ossci-android.s3.amazonaws.com/executorch/release/v0.6.0-rc1/executorch.aar -o app/libs/executorch.aar

并在 gradle 中包含它

# app/build.gradle.kts
dependencies {
    implementation(files("libs/executorch.aar"))
    implementation("com.facebook.soloader:soloader:0.10.5")
    implementation("com.facebook.fbjni:fbjni:0.5.1")
}

现在您可以使用 ExecuTorch Android 库编译您的应用了。

从源代码构建

scripts/build_android_library.sh 是一个帮助脚本,用于构建 Java 库(生成 .jar)、native 库(生成 .so)和打包好的 AAR 文件。

您需要 Android SDKNDK 才能使用它。

ExecuTorch CI 中当前使用的 NDK 版本:r27b。

您需要将 ANDROID_HOME 设置为 Android SDK 目录,将 ANDROID_NDK 设置为正确的 NDK 根目录(包含 NOTICE 文件)。

export ANDROID_HOME=/path/to/sdk
export ANDROID_NDK=/path/to/ndk
sh scripts/build_android_library.sh

目前,该脚本总是构建 XNNPACK 后端。

可选环境变量

可选地,在运行 build_android_library.sh 之前设置这些环境变量。

ANDROID_ABIS

如果您只需要为一个 ABI 构建 native 库,请将环境变量 ANDROID_ABIS 设置为 arm64-v8ax86_64

export ANDROID_ABIS=arm64-v8a
# or
# export ANDROID_ABIS=x86_64
sh scripts/build_android_library.sh

EXECUTORCH_CMAKE_BUILD_TYPE

根据您的需求,将环境变量 EXECUTORCH_CMAKE_BUILD_TYPE 设置为 ReleaseDebug

使用 MediaTek 后端

要使用MediaTek 后端,在安装并设置好 SDK 后,请将 NEURON_BUFFER_ALLOCATOR_LIBNEURON_USDK_ADAPTER_LIB 设置为对应的路径。

使用 Qualcomm AI Engine 后端

要使用Qualcomm AI Engine 后端,在安装并设置好 SDK 后,请将 QNN_SDK_ROOT 设置为对应的路径。

使用 Vulkan 后端

要使用Vulkan 后端,请将 EXECUTORCH_BUILD_VULKAN 设置为 ON

Android 后端

可用于 Android 的后端如下

后端

类型

文档

XNNPACK

CPU

文档

MediaTek NeuroPilot

NPU

文档

Qualcomm AI Engine

NPU

文档

Vulkan

GPU

文档

运行时集成

这里是一个 Java 代码示例,演示了如何将 ExecuTorch 集成到 Android 应用中

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

public class MainActivity extends Activity {
    private Module module;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // Load the ExecuTorch module
        Module module = Module.load("/data/local/tmp/add.pte");
        Tensor tensor1 = Tensor.fromBlob(new float[] {1.0f}, new long[] {1});
        Tensor tensor2 = Tensor.fromBlob(new float[] {20.0f}, new long[] {1});

        EValue eValue1 = EValue.from(tensor1);
        EValue eValue2 = EValue.from(tensor2);
        float result = module.forward(eValue1, eValue2)[0].toTensor().getDataAsFloatArray()[0];
    }
}

将对应的 .pte 文件推送到手机

adb push extension/module/test/resources/add.pte /data/local/tmp/

此示例加载一个 ExecuTorch 模块,准备输入数据,运行推理,并处理输出数据。

请参考 DeepLabV3AndroidDemoLlamaDemo 获取使用 ExecuTorch AAR 软件包的代码示例。

Java API 参考

请参阅Java API 参考

文档

访问 PyTorch 全面开发者文档

查看文档

教程

获取面向初学者和高级开发者的深度教程

查看教程

资源

查找开发资源并获得问题解答

查看资源