onnxruntime-java

by @yuzawa-san

This is an performant and modern Java binding to Microsoft's ONNX Runtime which uses Java's new Foreign Function & Memory API (a.k.a. Project Panama).

This project's goals are to provide a type-safe, lightweight, and performant binding which abstracts a lot of the native and C API intricacies away behind a Java-friendly interface. This is loosely coupled to the upstream project and built off of the public (and stable) C API.

The minimum supported Java version is 23, since the FFI API was first stabilized in that version. There are other fine bindings which use JNI and are capable of supporting earlier Java versions.

Usage

This project is released to Maven Central and can be used in your project.

Artifacts

The library is currently built for Linux, Windows, MacOS and for arm64 and x86_64. These were chosen since the upstream projects publishes artifacts for these enviroments. Here are the artifacts published listed below. Snapshot releases are periodically released for testing and experimentation.

onnxruntime

[!WARNING] Prior versions used the com.jyuzawa:onnxruntime Maven coordinates with a bastardized version of semver. Please upgrade to the com.jyuzawa:onnxruntime-api. See "Versioning" below for details.

The binding with no native libraries. For use as a implementation dependency.

The native library (from Microsoft) will need to be provided at runtime using one of the next two artifacts. Alternatively, the Java library path (java.library.path) will be used if neither of those artifacts is provided. This allows users to "bring their own" shared library.

Versioning

This library's version string will be ${ORT_UPSTREAM_VERSION}-${THIS_REPO_VERSION}. The first part indicates the minimum upstream native library this Java API supports, so please use the corresponding (or older) version. The second part of the version (THIS_REPO_VERSION) may get incremented if we add additional changes to the API but still target the same minimum upstream version. This API has a validation to make sure the shared library is minor version compatible with this library.

onnxruntime-cpu

A collection of native libraries with CPU support for a several common OS/architecture combinations. For use as an optional runtime dependency. Include one of the OS/Architecture classifiers like linux-x86_64 to provide specific support.

onnxruntime-gpu

A collection of native libraries with GPU (CUDA) support for a several common OS/architecture combinations. For use as an optional runtime dependency. Include one of the OS/Architecture classifiers like linux-x86_64 to provide specific support.

In your library

There is an example library in the onnxruntime-sample-library directory. The library should use the onnxruntime as a implementation dependency. This puts the burden of providing a native library on your end user.

In your application

There is an example application in the onnxruntime-sample-application directory. The library should use the onnxruntime as a implementation dependency. The application needs to have acccess to the native library. You have the option providing it via a runtime dependency using either a classifier variant from onnxruntime-cpu or onnxruntime-gpu. Otherwise, the Java library path will be used to load the native library.

The example application can be ran:

./gradlew onnxruntime-sample-application:run

JVM Arguments

Since this uses a native library, this will require the runtime to have the --enable-native-access JVM option, likely --enable-native-access=ALL-UNNAMED.

Execution Providers

Only those which are exposed in the C API are supported. If you wish to use another execution provider which is present in the C API, but not in any of the artifacts from the upstream project, you can choose to bring your own onnxruntime shared library to link against.