本文详解在 Android 项目中通过 onnxruntime-android 依赖加载和运行 ONNX 模型的完整流程，涵盖 Gradle 配置、代码初始化、常见编译错误排查（如 ai.onnxruntime 包无法识别）及版本兼容性建议。
本文详解在 android 项目中通过 onnxruntime-android 依赖加载和运行 onnx 模型的完整流程，涵盖 gradle 配置、代码初始化、常见编译错误排查（如 `ai.onnxruntime` 包无法识别）及版本兼容性建议。
要在 Android 应用中成功部署由 MATLAB 训练并导出为 ONNX 格式的神经网络，核心在于正确引入官方 ONNX Runtime for Android SDK，并确保构建系统能正常解析其 AAR（Android Archive）包中的 Java/Kotlin 接口。你遇到的 package ai.onnxruntime does not exist 错误，本质上是 Gradle 未能将 onnxruntime-android 的 AAR 依赖正确解压并注入编译类路径所致。
✅ 正确的 Gradle 配置方式
请移除 @aar 后缀——这是关键误区。implementation 'com.microsoft.onnxruntime:onnxruntime-android:1.15.1@aar' 中的 @aar 是手动强制指定模块类型的方式，但现代 Gradle（尤其是 Android Gradle Plugin 7.0+）已默认支持自动解析 AAR，显式添加 @aar 反而可能干扰依赖解析器，导致元数据读取失败、R8/ProGuard 规则缺失或 Java 接口未暴露。
✅ 推荐写法（无需 @aar）：
// app/build.gradle
android {
compileSdk 34
defaultConfig {
minSdk 21 // onnxruntime-android 最低支持 API 21
targetSdk 34
}
}
dependencies {
implementation 'com.microsoft.onnxruntime:onnxruntime-android:1.16.0-rc1'
// 或使用稳定版（推荐生产环境）：
// implementation 'com.microsoft.onnxruntime:onnxruntime-android:1.17.1'
}
? 验证依赖是否生效：同步项目后，在 Android Studio 的 Project → External Libraries 下应能看到
onnxruntime-android-1.x.x.aar，且展开后可浏览ai.onnxruntime.*包结构（含OrtEnvironment,OrtSession,OrtTensor等类）。
✅ 基础 Java/Kotlin 初始化示例
配置成功后，即可在 Activity 或 ViewModel 中安全导入并使用：
// Java 示例
import ai.onnxruntime.*;
public class OnnxInferenceHelper {
private OrtEnvironment environment;
private OrtSession session;
public void init(Context context, String modelPath) throws Exception {
environment = OrtEnvironment.getEnvironment();
// 从 assets 加载模型（推荐）
AssetManager assetManager = context.getAssets();
InputStream is = assetManager.open(modelPath); // e.g., "model.onnx"
session = environment.createSession(is);
}
public void runInference(float[] input) throws OrtException {
// 构造输入 Tensor（以 float32 为例）
OrtTensor inputTensor = OrtTensor.createTensor(
environment,
FloatBuffer.wrap(input),
new long[]{1, input.length},
OnnxJavaType.FLOAT
);
// 执行推理
Map<string orttensor> inputs = Map.of("input", inputTensor);
Map<string orttensor> outputs = session.run(inputs);
// 解析输出...
}
}</string></string>
⚠️ 注意事项与最佳实践
-
API Level 兼容性：
onnxruntime-android要求minSdk >= 21；若需支持更低版本，请确认所用版本是否提供arm64-v8a/armeabi-v7a/x86_64等 ABI 的原生库（1.16+ 默认包含主流 ABI）。 -
模型部署路径：建议将
.onnx文件放入src/main/assets/目录，避免打包进res/raw（ONNX Runtime 不支持TypedArray流）。 -
线程安全：
OrtEnvironment是线程安全的单例，但OrtSession实例不保证线程安全，高并发场景下建议复用 session 或加锁。 -
版本选择建议：优先使用最新稳定版（如
1.17.1），而非 RC 版本；若遇兼容性问题，可回退至1.15.1（但务必去掉@aar）。 -
混淆与 R8：默认无需额外 ProGuard 规则，SDK 已内置
consumer-rules.pro；若启用全量混淆，可保留ai.onnxruntime.** { *; }。
完成上述配置后，import ai.onnxruntime.* 将不再报错，OrtEnvironment 和 OrtSession 等核心类可正常使用。整个流程无需手动下载 AAR 或配置本地仓库——Maven Central 的托管依赖足以支撑端到端部署。
