在 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 代码初始化时加载。
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 模型的演示视频。
直接使用 AAR 文件¶
您也可以直接在应用中指定 AAR 文件。我们在每次发布时或作为快照将预构建的 AAR 上传到 S3。
已发布版本(推荐)¶
版本 |
AAR |
SHASUMS |
---|---|---|
main 分支的快照¶
日期 |
AAR |
SHASUMS |
---|---|---|
2025-02-27 |
使用 AAR 文件¶
将 AAR 文件添加到您的应用中
下载 AAR。
将其作为文件路径添加到您的 gradle 构建规则中。
AAR 文件本身不包含依赖信息,不像 Maven 仓库中的文件捆绑了 pom.xml。Java 包需要 fbjni
和 soloader
,目前要求用户显式声明依赖项。因此,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 文件。
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-v8a
或 x86_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
设置为 Release
或 Debug
。
使用 MediaTek 后端¶
要使用MediaTek 后端,在安装并设置好 SDK 后,请将 NEURON_BUFFER_ALLOCATOR_LIB
和 NEURON_USDK_ADAPTER_LIB
设置为对应的路径。
使用 Qualcomm AI Engine 后端¶
要使用Qualcomm AI Engine 后端,在安装并设置好 SDK 后,请将 QNN_SDK_ROOT
设置为对应的路径。
运行时集成¶
这里是一个 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 模块,准备输入数据,运行推理,并处理输出数据。
请参考 DeepLabV3AndroidDemo 和 LlamaDemo 获取使用 ExecuTorch AAR 软件包的代码示例。
Java API 参考¶
请参阅Java API 参考。