Java ORT 入门
ONNX Runtime 提供 Java 绑定,用于在 JVM 上运行 ONNX 模型推理。
目录
支持的版本
Java 8 或更高版本
构建版本
发布工件发布到 Maven Central,可作为大多数 Java 构建工具的依赖项使用。这些工件支持一些流行平台。
工件 | 描述 | 支持的平台 |
---|---|---|
com.microsoft.onnxruntime:onnxruntime | CPU | Windows x64, Linux x64, macOS x64 |
com.microsoft.onnxruntime:onnxruntime_gpu | GPU (CUDA) | Windows x64, Linux x64 |
有关本地构建的更多详细信息,请参阅Java API 开发文档。
有关共享库加载机制的自定义,请参阅高级加载说明。
API 参考
Javadoc 可在此处获取:here。
示例
示例实现位于 src/test/java/sample/ScoreMNIST.java。
编译后,示例代码需要以下参数 ScoreMNIST [path-to-mnist-model] [path-to-mnist] [scikit-learn-flag]
。MNIST 预计为 libsvm 格式。如果提供了可选的 scikit-learn 标志,则模型应由 skl2onnx 生成(因此需要一个扁平的特征向量,并产生结构化输出);否则,模型应为 PyTorch 中的 CNN(需要 [1][1][28][28]
输入,并产生概率向量)。在 testdata 中提供了两个示例模型:cnn_mnist_pytorch.onnx
和 lr_mnist_scikit.onnx
。第一个是使用 PyTorch 训练的 LeNet5 风格的 CNN,第二个是使用 scikit-learn 训练的逻辑回归。
单元测试包含加载模型、检查输入/输出节点形状和类型以及构造用于评分的张量的几个示例。
入门
这是一个简单的入门教程,用于在给定输入数据的情况下,对现有 ONNX 模型运行推理。模型通常使用任何知名的训练框架进行训练并导出为 ONNX 格式。
请注意,下面提供的代码使用 Java 10 及更高版本可用的语法。Java 8 语法类似但更冗长。
要开始评分会话,首先创建 OrtEnvironment
,然后使用 OrtSession
类打开一个会话,将模型的文件路径作为参数传入。
var env = OrtEnvironment.getEnvironment();
var session = env.createSession("model.onnx",new OrtSession.SessionOptions());
一旦创建了会话,就可以使用 OrtSession
对象的 run
方法执行查询。目前我们支持 OnnxTensor
输入,模型可以生成 OnnxTensor
、OnnxSequence
或 OnnxMap
输出。后两种情况在对 scikit-learn 等框架生成的模型进行评分时更常见。
run 调用需要一个 Map<String,OnnxTensor>
,其中键与模型中存储的输入节点名称匹配。这些可以通过在实例化会话上调用 session.getInputNames()
或 session.getInputInfo()
来查看。run 调用会产生一个 Result
对象,其中包含一个表示输出的 Map<String,OnnxValue>
。 Result
对象是 AutoCloseable
的,可以在 try-with-resources 语句中使用,以防止引用泄漏。一旦 Result
对象关闭,其所有子 OnnxValue
也会关闭。
OnnxTensor t1,t2;
var inputs = Map.of("name1",t1,"name2",t2);
try (var results = session.run(inputs)) {
// manipulate the results
}
您可以通过多种方式将输入数据加载到 OnnxTensor 对象中。最有效的方法是使用 java.nio.Buffer
,但也可以使用多维数组。如果使用数组构造,数组不得是不规则的。
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);
这是一个完整的示例程序,它在一个预训练的 MNIST 模型上运行推理。
在 GPU 或使用其他提供程序上运行 (可选)
要启用 GPU 等其他执行提供程序,只需在创建 OrtSession 时在 SessionOptions 上打开相应的标志即可。
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);
执行提供程序按其启用顺序确定优先级。