尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

ONNX Runtime Java API 完全指南:JNI 绑定的构建、本地库加载与开发实践

ONNX Runtime Java API 完全指南:JNI 绑定的构建、本地库加载与开发实践 ONNX Runtime Java API 完全指南JNI 绑定的构建、本地库加载与开发实践【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntimeONNX Runtime 官方提供 Java 语言绑定位于仓库的java/目录通过 Java Native InterfaceJNI实现 Java 代码与 ONNX Runtime C/C 核心的无缝调用。本文以 java/README.md 为骨架结合仓库内java/build.gradle、cmake/onnxruntime_java.cmake、OnnxRuntime.java 等源码系统讲解 Java API 的构建流程、CMake 与 Gradle 的分工协作、共享库的高级加载机制、Android 遥测权限注意事项以及日常开发中的格式化与 JNI 头文件维护方法帮助读者在本地完整构建、测试并深度定制这一 Java 推理接口。一、Java API 概览基于 JNI 的语言绑定java/目录存放 ONNX Runtime 的 Java 语言绑定。绑定通过 JNI 实现Java 侧只需调用普通方法底层自动桥接到 ONNX Runtime 的 C API因此 Java 开发者无需直接接触任何 native 代码。从源码结构看绑定涉及三类共享库文件onnxruntimeONNX Runtime 核心共享库由 C/C 编译产出onnxruntime4j_jniJNI 胶水共享库源文件位于java/src/main/native/其中ai_onnxruntime_OrtSession.c、ai_onnxruntime_OrtEnvironment.c等按 Java 类一对一映射各类 Execution Provider 共享库CUDA、ROCm、DNNL、OpenVINO、TensorRT、QNN 等仅在启用对应 EP 时随包分发。Java 侧 API 集中在包ai.onnxruntime源码位于 java/src/main/java/ai/onnxruntime/核心类包括OrtEnvironment、OrtSession、OnnxTensor、OnnxValue、OrtException等Android 平台另有java/src/main/android/源集与java/src/main/android-telemetry/遥测模块。说明本文档聚焦于开发、构建、运行与测试该 API 本身若只需在业务项目中使用官方发布版 API请参阅官方 Java API 文档。二、构建 Java API2.1 环境要求构建要求Java 11 或更高版本运行要求编译出的 JAR 可在 Java 8 或更高版本上运行java/build.gradle中通过--release 8编译选项保证字节码向后兼容构建工具Java 项目使用 Gradle 管理依赖、编译、测试与打包。仓库通过 Gradle Wrapperjava/gradlew / java/gradlew.bat锁定 Gradle 版本无需在系统上预装指定版本的 Gradle。当前 wrapper 配置java/gradle/wrapper/gradle-wrapper.properties锁定的 Gradle 版本为 8.7。2.2 通过主项目 CMake 构建推荐Java API 的构建集成在主项目的 CMake 构建体系中构建脚本使用--build_java选项即可./build.sh --build_java --config ReleaseWindows 下对应build.bat --build_java --config Release。具体参数组合请以仓库根目录构建脚本与官方构建说明为准。2.3 构建产物构建输出位于$REPO_ROOT/build/$OS/$CONFIGURATION/java/build包含产物说明docs/javadoc/HTML 格式的 Javadoc 文档reports/详细测试结果与其他报告libs/onnxruntime-VERSION.jar打包了编译后的类、平台相关 JNI 共享库与平台相关 onnxruntime 共享库的 JAR例如 Release 配置下产物路径为build/Linux/Release/java/build/操作系统名因平台而异。三、构建系统协作机制CMake 委托 Gradle3.1 分工与调用链整个 Java 构建由主项目的 CMake 系统委托给 Gradle 完成CMake 首先确保所有 C/C 编译完成——即onnxruntime核心目标与 JNI 胶水目标onnxruntime4j_jni定义见 cmake/onnxruntime_java.cmakeCMake 将编译出的共享库注入到 Gradle 可读取的位置build/java/native-lib、native-jni、native-test等目录见 java/build.gradle随后执行专门的 Gradle 构建任务产出 JAR、Javadoc 与测试报告到上节所述输出目录。这一设计的核心原因是Java 绑定依赖 C/C 编译出的onnxruntime共享库与 JNI 胶水库。若脱离 CMake 单独运行 Gradlebuild、test、check等任务会因缺少 native 依赖而失败。3.2 独立运行 Gradle 的方式如需在 CMake 之外单独运行 Gradle例如仅想重跑测试通过系统属性指定 CMake 构建目录./gradlew build -DcmakeBuildDir/path/to/onnxruntime-build-dir前提是 native 库已完成至少一次构建。-DcmakeBuildDir同时驱动java/build.gradle中的多个行为注入 native 测试资源、注册allJar/cmakeBuild/cmakeCheck任务、设置测试工作目录等未设置时这些任务会被跳过build.gradle中打印 cmakeBuildDir is not set. Skipping cmake tasks.。3.3 Gradle 构建细节来自源码从 java/build.gradle 可以确认以下实现细节Maven 坐标groupId为com.microsoft.onnxruntimeartifactId默认onnxruntime启用训练 API-DENABLE_TRAINING_APIS1时为onnxruntime-training传入-DUSE_CUDA时追加_gpu后缀编译选项使用--release 8确保只使用 Java 8 的 API保证产物可运行于 Java 8并通过-h参数在build/headers/生成 JNI 头文件测试基于 JUnit 5junit-jupiter测试资源会合并csharp/testdata、onnxruntime/test/testdata、训练 API 测试数据与 java/testdata 等多处数据目录通过JAVA_FULL_TEST系统属性可让每个测试类在独立 JVM 中运行用于测试环境线程池相关逻辑test任务会透传USE_CUDA、USE_OPENVINO、USE_TENSORRT等大量USE_*属性供测试按可用 EP 跳过用例发布支持sources与javadoc两个附加 JAR并提供 Maven 发布与配置签名密钥时的PGP 签名。四、本地共享库的高级加载机制默认行为下onnxruntime与onnxruntime4j_jni两个共享库通过classpath 资源自动加载库被打进 JAR 的ai/onnxruntime/native/os-arch/路径下运行时解压到临时目录再通过System.load加载。若你的使用场景需要自定义加载路径请查阅 package-info.java 与 OnnxRuntime.java 的 Javadoc。从OnnxRuntime.java的load()实现OnnxRuntime.java可以归纳出完整的加载优先级开发者可按需选择优先级机制配置方式底层调用1跳过加载系统属性onnxruntime.native.LIB_NAME.skiptrue如onnxruntime.native.onnxruntime4j_jni.skiptrue由用户自行加载不执行加载2指定所有库所在目录系统属性onnxruntime.native.path目录System.load3指定单个库文件路径系统属性onnxruntime.native.LIB_NAME.path文件路径System.load4aclasspath 资源自动发现库位于 JAR 内ai/onnxruntime/native/os-arch/解压到临时目录后System.load4b系统库路径兜底库不在 classpath 资源中System.loadLibrary依赖java.library.path行为随 JVM/系统而异关键实现说明平台目录串形如linux-x64、osx-aarch64、win-x64等由OnnxRuntime.java根据os.name与os.arch推导Android 上直接使用System.loadLibrary若指定了onnxruntime.native.path加载前会校验文件存在性不存在则抛出IOException并提示缺失文件路径所有加载事件通过java.util.logging在FINE级别记录加载失败排查时可开启该级别的日志查看详细过程共享 EP 库的特殊性CUDA、ROCm、DNNL、OpenVINO、TensorRT、QNN 等属于共享库 Execution Provider由 ONNX Runtime 原生库自行加载Java API 无法控制其加载位置因此这些库必须放在 ONNX Runtime 核心共享库所在目录或作为 classpath 资源存在。OnnxRuntime.java中的extractProviderLibrary()会负责从资源中解压或校验指定目录中的这些库含onnxruntime_providers_shared及 WebGPU 的webgpu_dawn、dxil、dxcompiler等加载完成后绑定会通过initialiseAPIBase请求 ORT C API 结构当前使用 API 版本 23并枚举当前可用的 Execution Provider 列表。五、Android 支持与遥测权限Java 绑定同时支持 Androidjava/src/main/android/源集。当启用遥测时Android AAR 的 manifestjava/src/main/android-telemetry/AndroidManifest.xml会声明两个权限android.permission.INTERNETandroid.permission.ACCESS_NETWORK_STATEAndroid 的 manifest 合并机制会将这些权限合并进消费方应用。它们是为内置的 1DS 传输通道上报遥测事件、并根据网络状态调整传输行为所必需的同时该模块包含ai.onnxruntime.TelemetryInitializerproviderandroid:initOrder100用于应用启动时初始化遥测。若你的应用不允许申请这些权限请在构建时构建不含遥测的 AAR 版本构建 AAR 时不启用 telemetry 相关开关从而避免权限被打入最终应用。六、Java API 开发指南6.1 代码格式化SpotlessJava 源码使用 Spotless 插件保持格式统一java/build.gradle 中配置了googleJavaFormat与removeUnusedImportsGradle 文件使用 Tab 缩进./gradlew spotlessCheck # 检查格式展示不合规代码 ./gradlew spotlessApply # 自动修复格式格式不合规的代码会在测试运行的 check 阶段直接导致构建失败compileJava依赖spotlessJava任务测试同样先执行格式化检查。6.2 JNI 头文件维护当在 Java 文件中新增或修改native方法时需要同步维护 C 侧实现。标准流程为执行 Gradle 的compileJava任务编译 Java 并自动重新生成JNI 头文件到build/headers/ai_onnxruntime*.h检查生成的ai_onnxruntime*.h确认方法签名如Java_ai_onnxruntime_OrtSession_run更新对应的 C 实现文件即 java/src/main/native/ 下的ai_onnxruntime*.c如 ai_onnxruntime_OrtSession.c重新运行构建。6.3 依赖与测试零依赖设计Java API 本身没有任何运行时或编译期依赖仅测试依赖 JUnit 5 与 protobuf-javajava/build.gradle 的dependencies块测试通过./gradlew test运行测试输出位于构建产物reports/目录JAR 内的 JNI 头文件、native 目录结构等信息可通过./gradlew jar产物验证。6.4 快速上手从源码结构看典型调用路径虽然没有随仓库提供 Java 示例工程但从ai.onnxruntime包的公开类java/src/main/java/ai/onnxruntime/可以还原典型的推理调用链通过OrtEnvironment.getEnvironment()或OrtEnvironment.create()获取运行时环境使用OrtSession.SessionOptions配置会话可添加OrtProvider及其选项如OrtCUDAProviderOptions、OrtTensorRTProviderOptions通过OrtEnvironment.createSession(modelPath, options)加载模型得到OrtSession使用OnnxTensor.createTensor(...)构造输入张量调用session.run(...)执行推理返回OnnxValueOnnxTensor/OnnxSequence/OnnxMap并读取结果通过session.getInputInfo()/session.getOutputInfo()获取模型的输入输出元数据TensorInfo、NodeInfo等关闭资源释放内存。非 Java 原生可表示的类型如 fp16在通过该 API 访问时会被转换为最接近的 Java 原始类型参见 package-info.java。七、常见问题与排查建议场景建议独立跑 Gradle 报 native 库缺失先完成一次完整 CMake 构建再通过-DcmakeBuildDir指定构建目录UnsatisfiedLinkError或加载失败开启java.util.loggingFINE 级别日志查看加载路径与顺序确认平台目录串如linux-x64与 JAR 内资源路径一致共享 EPCUDA/TensorRT 等未生效确认对应 provider 库位于核心库同目录或 classpath 资源中且构建时通过USE_*选项启用了该 EPAndroid 应用出现意外网络权限构建不含遥测的 AAR 版本代码格式导致 check 失败运行spotlessApply自动修复后再提交修改 native 方法后行为异常用compileJava重新生成 JNI 头文件核对 C 实现签名与头文件一致总结ONNX Runtime 的 Java API 通过 JNI 在 Java 与 C/C 核心之间架起桥梁其构建体系采用CMake 编译 native Gradle 打包 Java的分层协作模式一次--build_java构建即可产出内含平台原生库的可执行 JAR。理解共享库的四级加载优先级与共享 EP 库的特殊放置要求是处理运行期加载问题的关键而掌握 Spotless 格式化与 JNI 头文件再生成流程则是参与该绑定开发的基础。本文所涉机制均可通过 java/README.md、java/build.gradle、OnnxRuntime.java 与 cmake/onnxruntime_java.cmake 等文件进一步验证与深入。【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表