From aca34352a54794754bfa7532a9d577b67935cf9e Mon Sep 17 00:00:00 2001 From: James Yuzawa Date: Thu, 13 Aug 2020 15:06:42 -0400 Subject: [PATCH] Java API: Documentation cleanup (#4395) * update java API docs * fix link * rearrange * update platforms, use table * use javadoc.io * craigacp tested it in java 14 * update link * fix broken link * fix testdata link --- README.md | 2 +- docs/Java_API.md | 33 ++++++++++++++++++++++++++++----- java/README.md | 30 +++--------------------------- 3 files changed, 32 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index bf844b88da..7226f0005e 100644 --- a/README.md +++ b/README.md @@ -132,7 +132,7 @@ For production scenarios, it's strongly recommended to build only from an [offic |[C++](./include/onnxruntime/core/session/onnxruntime_cxx_api.h)| |[Samples](./samples#CC)| |[C](docs/C_API.md)| | [Samples](./samples#CC)| |[WinRT](docs/WinRT_API.md) | [Windows.AI.MachineLearning](https://docs.microsoft.com/en-us/windows/ai/windows-ml/api-reference)| [Samples](https://github.com/microsoft/windows-Machine-Learning)| -|[Java](docs/Java_API.md)|8-13|[Samples](./samples#Java)| +|[Java](docs/Java_API.md)|8+|[Samples](./samples#Java)| [Ruby](https://github.com/ankane/onnxruntime) (external project)| 2.4-2.7| [Samples](https://ankane.org/tensorflow-ruby)| |[Javascript (node.js)](./nodejs) |12.x | [Samples](./nodejs/examples/README.md) | diff --git a/docs/Java_API.md b/docs/Java_API.md index 361089332f..72978e0770 100644 --- a/docs/Java_API.md +++ b/docs/Java_API.md @@ -1,10 +1,37 @@ # ONNX Runtime Java API The ONNX runtime provides a Java binding for running inference on ONNX models on a JVM, using Java 8 or newer. -Two jar files are created during the build process, one contains the onnxruntime shared library, the JNI binding and the Java class files, and the other only contains the class files. By default the shared libraries are loaded from the classpath in a folder called `/lib`, if you wish to have them load from `java.library.path` then supply `-DORT_LOAD_FROM_LIBRARY_PATH` to the JVM at runtime. +Release artifacts are published to Maven Central for use as a dependency in most Java build tools. The artifacts are built with support for some popular plaforms. + +![Version Shield](https://img.shields.io/maven-central/v/com.microsoft.onnxruntime/onnxruntime) + +| Artifact | Description | Supported Platforms | +|-----------|-------------|---------------------| +| [com.microsoft.onnxruntime:onnxruntime](https://search.maven.org/artifact/com.microsoft.onnxruntime/onnxruntime) | CPU | Windows x64, Linux x64, macOS x64 | +| [com.microsoft.onnxruntime:onnxruntime_gpu](https://search.maven.org/artifact/com.microsoft.onnxruntime/onnxruntime_gpu) | GPU (CUDA) | Windows x64, Linux x64 | + +For building locally, please see the [Java API development documentation](../java/README.md) for more details. + +For customization of the loading mechanism of the shared library, please see [advanced loading instructions](../java/README.md#advanced-loading). + +## API Reference + +The Javadoc is available [here](https://javadoc.io/doc/com.microsoft.onnxruntime/onnxruntime). ## Sample Code +An example implementation is located in +[src/test/java/sample/ScoreMNIST.java](../java/src/test/java/sample/ScoreMNIST.java). +Once compiled the sample code expects the following arguments `ScoreMNIST + `. MNIST is expected +to be in libsvm format. If the optional scikit-learn flag is supplied the model +is expected to be produced by skl2onnx (so expects a flat feature vector, and +produces a structured output), otherwise the model is expected to be a CNN from +pytorch (expecting a `[1][1][28][28]` input, producing a vector of +probabilities). Two example models are provided in [testdata](../java/testdata), +`cnn_mnist_pytorch.onnx` and `lr_mnist_scikit.onnx`. The first is a LeNet5 style +CNN trained using PyTorch, the second is a logistic regression trained using scikit-learn. + The unit tests contain several examples of loading models, inspecting input/output node shapes and types, as well as constructing tensors for scoring. * [../java/src/test/java/ai/onnxruntime/InferenceTest.java#L66](../java/src/test/java/ai/onnxruntime/InferenceTest.java#L66) @@ -50,7 +77,3 @@ To enable other execution providers like GPUs simply turn on the appropriate fla The execution providers are preferred in the order they were enabled. -## API Reference - -The Javadoc is available [here](https://microsoft.github.io/onnxruntime/java/index.html). - diff --git a/java/README.md b/java/README.md index 9c4d82369c..cb1a449b85 100644 --- a/java/README.md +++ b/java/README.md @@ -5,23 +5,8 @@ Java Native Interface (JNI) is used to allow for seamless calls to ONNX runtime ## Usage -TBD: maven distribution - -The minimum supported Java Runtime is version 8. - -An example implementation is located in -[src/test/java/sample/ScoreMNIST.java](./src/test/java/sample/ScoreMNIST.java). -Once compiled the sample code expects the following arguments `ScoreMNIST - `. MNIST is expected -to be in libsvm format. If the optional scikit-learn flag is supplied the model -is expected to be produced by skl2onnx (so expects a flat feature vector, and -produces a structured output), otherwise the model is expected to be a CNN from -pytorch (expecting a `[1][1][28][28]` input, producing a vector of -probabilities). Two example models are provided in [testdata](testdata), -`cnn_mnist_pytorch.onnx` and `lr_mnist_scikit.onnx`. The first is a LeNet5 style -CNN trained using PyTorch, the second is a logistic regression trained using scikit-learn. - -This project can be built manually using the instructions below. +This document pertains to developing, building, running, and testing the API itself in your local environment. +For general purpose usage of the publicly distributed API, please see the [general Java API documentation](../docs/Java_API.md). ### Building @@ -43,16 +28,7 @@ The build will generate output in `$REPO_ROOT/build/$OS/$CONFIGURATION/java/buil * `docs/javadoc/` - HTML javadoc * `reports/` - detailed test results and other reports -* `libs/onnxruntime-.jar` - JAR with classes, depends on `onnxruntime--jni.jar` and `onnxruntime--lib.jar ` -* `libs/onnxruntime--jni.jar`- JAR with JNI shared library -* `libs/onnxruntime--lib.jar` - JAR with onnxruntime shared library -* `libs/onnxruntime--all.jar` - the 3 preceding jars all combined: JAR with classes, JNI shared library, and onnxruntime shared library - -The reason the shared libraries are split out like that is that users can mix and match to suit their use case: - -* To support a single OS/Architecture without any dependencies, use `libs/onnxruntime--all.jar`. -* To support cross-platform: bundle a single `libs/onnxruntime-.jar` and with all of the respective `libs/onnxruntime--jni.jar` and `libs/onnxruntime--lib.jar` for all of the desired OS/Architectures. -* To support use case where an onnxruntime shared library will reside in the system's library search path: bundle a single `libs/onnxruntime-.jar` and with all of the `libs/onnxruntime--jni.jar`. The onnxruntime shared library should be loaded using one of the other methods described in the "Advanced Loading" section below. +* `libs/onnxruntime-VERSION.jar` - JAR with compiled classes, platform-specific JNI shared library, and platform-specific onnxruntime shared library. #### Build System Overview