Erste Schritte mit ORT für Java

Die ONNX Runtime bietet eine Java-Bindung für die Inferenz auf ONNX-Modellen auf einer JVM.

Inhalt

Unterstützte Versionen

Java 8 oder neuer

Builds

Release-Artefakte werden auf Maven Central veröffentlicht und können als Abhängigkeit in den meisten Java-Build-Tools verwendet werden. Die Artefakte werden mit Unterstützung für einige gängige Plattformen erstellt.

Version Shield

Artefakt Beschreibung Unterstützte Plattformen
com.microsoft.onnxruntime:onnxruntime CPU Windows x64, Linux x64, macOS x64
com.microsoft.onnxruntime:onnxruntime_gpu GPU (CUDA) Windows x64, Linux x64

Informationen zum lokalen Build finden Sie in der Java API-Entwicklungsdokumentation.

Zur Anpassung des Lademechanismus der Shared Library lesen Sie bitte die Anweisungen für das erweiterte Laden.

API-Referenz

Die Javadoc ist hier verfügbar.

Beispiel

Eine Beispielimplementierung befindet sich in src/test/java/sample/ScoreMNIST.java.

Nach der Kompilierung erwartet der Beispielcode die folgenden Argumente: ScoreMNIST [pfad-zum-mnist-modell] [pfad-zum-mnist] [scikit-learn-flag]. MNIST wird im libsvm-Format erwartet. Wenn das optionale scikit-learn-Flag angegeben ist, wird erwartet, dass das Modell von skl2onnx erzeugt wurde (erwartet einen flachen Feature-Vektor und erzeugt eine strukturierte Ausgabe), andernfalls wird erwartet, dass das Modell eine CNN von pytorch ist (erwartet eine Eingabe [1][1][28][28], erzeugt einen Wahrscheinlichkeitsvektor). Zwei Beispielmodelle sind in testdata verfügbar: cnn_mnist_pytorch.onnx und lr_mnist_scikit.onnx. Das erste ist eine CNN im LeNet5-Stil, trainiert mit PyTorch, das zweite ist eine logistische Regression, trainiert mit scikit-learn.

Die Unit-Tests enthalten mehrere Beispiele zum Laden von Modellen, zur Inspektion von Eingabe-/Ausgabeknotenformen und -typen sowie zur Erstellung von Tensoren für die Auswertung.

Erste Schritte

Hier ist ein einfaches Tutorial, um mit der Inferenz auf einem vorhandenen ONNX-Modell für gegebene Eingabedaten zu beginnen. Das Modell wird typischerweise mit einem der bekannten Trainings-Frameworks trainiert und in das ONNX-Format exportiert.

Beachten Sie, dass der unten dargestellte Code Syntax verwendet, die ab Java 10 verfügbar ist. Die Java 8-Syntax ist ähnlich, aber umständlicher.

Um eine Scoring-Sitzung zu starten, erstellen Sie zunächst die OrtEnvironment und öffnen Sie dann eine Sitzung mit der Klasse OrtSession, wobei Sie den Dateipfad zum Modell als Parameter übergeben.

    var env = OrtEnvironment.getEnvironment();
    var session = env.createSession("model.onnx",new OrtSession.SessionOptions());

Sobald eine Sitzung erstellt ist, können Sie Abfragen mit der Methode run des OrtSession-Objekts ausführen. Derzeit unterstützen wir OnnxTensor-Eingaben, und Modelle können OnnxTensor, OnnxSequence oder OnnxMap-Ausgaben erzeugen. Letztere beiden sind wahrscheinlicher, wenn Modelle von Frameworks wie scikit-learn gescort werden.

Der run-Aufruf erwartet eine Map<String,OnnxTensor>, bei der die Schlüssel den Eingabeknotennamen im Modell entsprechen. Diese können durch Aufruf von session.getInputNames() oder session.getInputInfo() auf einer instanziierten Sitzung eingesehen werden. Der run-Aufruf erzeugt ein Result-Objekt, das eine Map<String,OnnxValue> mit der Ausgabe enthält. Das Result-Objekt ist AutoCloseable und kann in einer try-with-resources-Anweisung verwendet werden, um zu verhindern, dass Referenzen verloren gehen. Sobald das Result-Objekt geschlossen ist, werden auch alle seine untergeordneten OnnxValues geschlossen.

    OnnxTensor t1,t2;
    var inputs = Map.of("name1",t1,"name2",t2);
    try (var results = session.run(inputs)) {
        // manipulate the results
    }

Sie können Ihre Eingabedaten auf verschiedene Arten in OnnxTensor-Objekte laden. Der effizienteste Weg ist die Verwendung eines java.nio.Buffer, aber es ist auch möglich, mehrdimensionale Arrays zu verwenden. Wenn sie mit Arrays konstruiert werden, dürfen die Arrays nicht "gezackt" sein.

    FloatBuffer sourceData;  // assume your data is loaded into a FloatBuffer
    long[] dimensions;       // and the dimensions of the input are stored here
    var tensorFromBuffer = OnnxTensor.createTensor(env,sourceData,dimensions);

    float[][] sourceArray = new float[28][28];  // assume your data is loaded into a float array 
    var tensorFromArray = OnnxTensor.createTensor(env,sourceArray);

Hier ist ein vollständiges Beispielprogramm, das die Inferenz auf einem vortrainierten MNIST-Modell ausführt.

Ausführung auf einer GPU oder mit einem anderen Anbieter (optional)

Um andere Ausführungsanbieter wie GPUs zu aktivieren, schalten Sie einfach das entsprechende Flag in SessionOptions ein, wenn Sie eine OrtSession erstellen.

    int gpuDeviceId = 0; // The GPU device ID to execute on
    var sessionOptions = new OrtSession.SessionOptions();
    sessionOptions.addCUDA(gpuDeviceId);
    var session = environment.createSession("model.onnx", sessionOptions);

Die Ausführungsanbieter werden in der Reihenfolge ihrer Aktivierung priorisiert.