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 22, since the FFI API was introduced (and taken out of preview) in that version. There are other fine bindings which use JNI and are capable of supporting earlier Java versions.
This project is released to Maven Central and can be used in your project.
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.
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.
The API has a validation to make sure the shared library is minor version compatible with this library.
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 osx-x86_64 to provide specific support.
A collection of native libraries with GPU support for a several common OS/architecture combinations. For use as an optional runtime dependency. Include one of the OS/Architecture classifiers like osx-x86_64 to provide specific support.
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.
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:runSince this uses a native library, this will require the runtime to have the --enable-native-access JVM option, likely --enable-native-access=ALL-UNNAMED.
Only those which are exposed in the C API are supported.
The onnxruntime-gpu artifact supports CUDA and TensorRT, since those are built off of the GPU artifacts from the upstream project.
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.
The version of the upstream project used will be reflected in the release notes. Semantic versioning is used. Major version will be bumped when this API or the underlying C API has backward incompatible changes. Upstream major version changes will typically be major version changes here. Minor version will be bumped for smaller, but compatible changes. Upstream minor version changes will typically be minor version changes here.
The onnxruntime-cpu and onnxruntime-gpu artifacts are versioned to match the upstream versions and depend on a minimum compatible onnxruntime version.