Skip to content

A type-safe, lightweight, modern, and performant binding Java binding of Microsoft's ONNX Runtime

License

Notifications You must be signed in to change notification settings

yuzawa-san/onnxruntime-java

Repository files navigation

onnxruntime-java

by @yuzawa-san

build codecov

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.

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

maven javadoc maven-snapshot

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.

onnxruntime-cpu

maven maven-snapshot

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.

onnxruntime-gpu

maven

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.

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. 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.

Versioning

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.

About

A type-safe, lightweight, modern, and performant binding Java binding of Microsoft's ONNX Runtime

Topics

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Sponsor this project

Packages

No packages published

Languages