ONNX Runtime for Java 跨平台 AI 推理实战指南

方式 2：Gradle 集成

在 build.gradle 中添加：

dependencies {
    implementation 'com.microsoft.onnxruntime:onnxruntime:1.17.3'
    // GPU 版本
    // implementation 'com.microsoft.onnxruntime:onnxruntime-gpu:1.17.3'
}

方式 3：手动下载

若无法访问 Maven 仓库，可从 ONNX Runtime 官网 下载对应平台的 onnxruntime-java 包，将 onnxruntime.jar 加入项目类路径，并将 JNI 库（如 onnxruntime.dll/libonnxruntime.so/libonnxruntime.dylib）放入系统库路径或项目资源目录。

三、核心 API 解析

ONNX Runtime for Java 的核心 API 集中在 ai.onnxruntime 包下，关键类如下：

核心流程

1. 创建 OrtEnvironment 实例；
2. 配置 SessionOptions（设备、优化等）；
3. 加载 ONNX 模型，创建 OrtSession；
4. 构造输入 OrtTensor；
5. 执行推理，获取输出 OrtTensor；
6. 解析输出数据，释放资源。

四、实战案例：图像分类推理

以 ResNet-50 模型（ONNX 格式）为例，实现 Java 端图像分类推理，步骤如下：

4.1 准备工作

1. 下载 ResNet-50 ONNX 模型：ResNet50.onnx；
2. 准备测试图片（如 cat.jpg）；
3. 下载 ImageNet 标签文件（synset.txt），用于映射分类结果。

4.2 代码实现

步骤 1：工具类（图像预处理）

ResNet-50 要求输入为 (1, 3, 224, 224) 的张量，且需归一化（均值：[0.485, 0.456, 0.406]，标准差：[0.229, 0.224, 0.225]）。

import ai.onnxruntime.*;
import org.opencv.core.*;
import org.opencv.imgcodecs.Imgcodecs;
import org.opencv.imgproc.Imgproc;
import java.nio.FloatBuffer;
import java.util.Collections;
import java.util.Map;

public class ResNetInference {
    // ImageNet 均值和标准差
    private static final float[] MEAN = {0.485f, 0.456f, 0.406f};
    private static final float[] STD = {0.229f, 0.224f, 0.225f};
    private static final int INPUT_SIZE = 224;

    // 图像预处理：缩放、归一化、转置为 CHW 格式
    private static float[] preprocessImage(String imagePath) {
        // 加载 OpenCV（需添加 OpenCV 依赖）
        System.loadLibrary(Core.NATIVE_LIBRARY_NAME);
        // 读取图片
        Mat image = Imgcodecs.imread(imagePath);
        if (image.empty()) {
            throw new RuntimeException("读取图片失败：" + imagePath);
        }
        // 缩放为 224x224
        Mat resizedImage = new Mat();
        Imgproc.resize(image, resizedImage, new Size(INPUT_SIZE, INPUT_SIZE));
        // BGR 转 RGB
        Mat rgbImage = new Mat();
        Imgproc.cvtColor(resizedImage, rgbImage, Imgproc.COLOR_BGR2RGB);
        // 归一化并转换为 CHW 格式（通道在前）
        float[] inputData = new float[3 * INPUT_SIZE * INPUT_SIZE];
        int idx = 0;
        for (int c = 0; c < 3; c++) {
            for (int h = 0; h < INPUT_SIZE; h++) {
                for (int w = 0; w < INPUT_SIZE; w++) {
                    double pixel = rgbImage.get(h, w)[c];
                    // 归一化：(pixel/255 - mean) / std
                    float normalized = (float) ((pixel / 255.0 - MEAN[c]) / STD[c]);
                    inputData[idx++] = normalized;
                }
            }
        }
        return inputData;
    }

    // 执行推理
    public static String infer(String modelPath, String imagePath) throws OrtException {
        // 1. 创建 ONNX 环境
        try (OrtEnvironment env = OrtEnvironment.getEnvironment()) {
            // 2. 配置会话选项
            OrtSession.SessionOptions sessionOptions = new OrtSession.SessionOptions();
            // 设置 CPU 推理（如需 GPU，取消注释并配置 CUDA）
            // sessionOptions.addCUDA(0); // 使用第 0 块 GPU
            // 启用优化（LEVEL_1 为基础优化，LEVEL_2 包含更多算子融合）
            sessionOptions.setOptimizationLevel(OrtSession.SessionOptions.OptLevel.ALL_OPT);
            // 设置执行模式：SEQUENTIAL（单线程）/PARALLEL（多线程）
            sessionOptions.setExecutionMode(OrtSession.SessionOptions.ExecutionMode.SEQUENTIAL);

            // 3. 加载模型创建会话
            try (OrtSession session = env.createSession(modelPath, sessionOptions)) {
                // 4. 预处理图像，构造输入张量
                float[] inputData = preprocessImage(imagePath);
                // 定义输入形状：(1, 3, 224, 224)
                long[] inputShape = {1, 3, INPUT_SIZE, INPUT_SIZE};
                // 创建 FloatBuffer（ONNX Runtime 要求使用 DirectBuffer）
                FloatBuffer inputBuffer = FloatBuffer.allocateDirect(inputData.length);
                inputBuffer.put(inputData).rewind();
                // 封装输入张量
                try (OrtTensor inputTensor = OrtTensor.createTensor(env, inputBuffer, inputShape)) {
                    // 构造输入映射（key 为模型输入节点名称，可通过 Netron 查看）
                    Map<String, OrtTensor> inputs = Collections.singletonMap("data", inputTensor);

                    // 5. 执行推理
                    long startTime = System.currentTimeMillis();
                    try (OrtSession.Result result = session.run(inputs)) {
                        long inferTime = System.currentTimeMillis() - startTime;
                        System.out.println("推理耗时：" + inferTime + "ms");

                        // 6. 解析输出
                        // ResNet50 输出为 (1, 1000) 的张量，对应 1000 个类别概率
                        try (OrtTensor outputTensor = result.get(0).getTensor()) {
                            float[] outputData = (float[]) outputTensor.getValue();
                            // 找到概率最大的类别索引
                            int maxIndex = 0;
                            float maxProb = 0.0f;
                            for (int i = 0; i < outputData.length; i++) {
                                if (outputData[i] > maxProb) {
                                    maxProb = outputData[i];
                                    maxIndex = i;
                                }
                            }
                            // 映射标签（此处省略读取 synset.txt 的逻辑，可自行实现）
                            return "分类结果：索引=" + maxIndex + "，概率=" + maxProb;
                        }
                    }
                }
            }
        }
    }

    public static void main(String[] args) {
        try {
            String modelPath = "resnet50-v1-12.onnx";
            String imagePath = "cat.jpg";
            String result = infer(modelPath, imagePath);
            System.out.println(result);
        } catch (OrtException e) {
            e.printStackTrace();
        }
    }
}

步骤 2：添加 OpenCV 依赖（图像预处理）

在 pom.xml 中添加 OpenCV 依赖（用于图像操作）：

<dependency>
    <groupId>org.openpnp</groupId>
    <artifactId>opencv</artifactId>
    <version>4.7.0-0</version>
</dependency>

4.3 运行说明

1. 确保模型文件、测试图片路径正确；
2. 若使用 GPU 推理，需确保 CUDA/cuDNN 版本与 ONNX Runtime GPU 版本匹配；
3. 运行时需加载 OpenCV 原生库（Windows 为 opencv_java470.dll，Linux 为 libopencv_java470.so）。

五、性能优化策略

5.1 会话配置优化

1. 优化级别：设置 sessionOptions.setOptimizationLevel(OptLevel.ALL_OPT)，启用所有优化（算子融合、常量折叠等）；
2. 执行模式：批量推理时使用 ExecutionMode.PARALLEL，开启多线程执行；
3. 内存优化：启用 sessionOptions.enableMemoryPatternOptimization(true)，优化内存访问模式；

精度调整：对非高精度要求的场景，可使用 FP16 精度（需模型支持）：

sessionOptions.setGraphOptimizationLevel(OrtSession.SessionOptions.GraphOptimizationLevel.ORT_ENABLE_ALL);
sessionOptions.setPreferredOutputTensorFormat(OrtSession.SessionOptions.TensorFormat.ORT_TENSOR_FORMAT_FLOAT16);

5.2 数据处理优化

1. 复用缓冲区：避免频繁创建 FloatBuffer，可复用预分配的缓冲区；
2. 批量推理：将多张图片打包为 (batchSize, 3, 224, 224) 的张量，提升吞吐量；

异步推理：使用 session.runAsync() 实现异步推理，避免阻塞主线程：

CompletableFuture<OrtSession.Result> future = session.runAsync(inputs);
future.thenAccept(result -> {
    // 处理推理结果
    result.close();
});

5.3 硬件加速

1. GPU 加速：确保安装 CUDA/cuDNN，通过 sessionOptions.addCUDA(0) 启用 GPU；

CPU 优化：启用 OpenMP 多线程（需系统安装 OpenMP）：

sessionOptions.setIntraOpNumThreads(Runtime.getRuntime().availableProcessors());

TensorRT 加速：对 NVIDIA GPU，可集成 TensorRT 后端，进一步提升性能：

sessionOptions.addConfigEntry("session.enable_tensorrt_engine", "1");
sessionOptions.addConfigEntry("tensorrt_fp16_enable", "1"); // 启用 FP16

六、常见问题与解决方案

6.1 模型加载失败

• 原因：模型格式不兼容、路径错误、依赖库缺失；
• 解决：
  1. 使用 Netron 检查模型是否为合法 ONNX 格式；
  2. 确认模型路径为绝对路径或相对路径正确；
  3. 检查系统是否缺失 libonnxruntime.so/onnxruntime.dll 等 JNI 库。

6.2 张量形状不匹配

• 原因：输入张量形状与模型要求不一致；
• 解决：
  1. 通过 Netron 查看模型输入节点的形状；
  2. 确保预处理后的数据形状与模型要求完全一致（如 (1,3,224,224)）。

6.3 GPU 推理报错

• 原因：CUDA 版本不匹配、GPU 显存不足、未安装 cuDNN；
• 解决：
  1. 确认 ONNX Runtime GPU 版本与 CUDA/cuDNN 版本匹配（参考 官方文档）；
  2. 减小批量大小，避免显存溢出；
  3. 验证 CUDA 环境变量（如 CUDA_PATH、LD_LIBRARY_PATH）配置正确。

6.4 性能低下

• 原因：未启用优化、单线程执行、数据处理耗时；
• 解决：
  1. 启用所有优化级别；
  2. 增加 intraOpNumThreads 线程数；
  3. 优化图像预处理逻辑（如使用 JNI/OpenCV 原生方法）。

七、总结

ONNX Runtime for Java 为 Java 开发者提供了高效、易用的 AI 模型推理能力，无需深入底层深度学习框架，即可快速部署 ONNX 模型。本文从环境搭建、核心 API、实战案例到性能优化，全面讲解了 Java 端 ONNX Runtime 的使用方法，覆盖了图像分类等典型场景。

在实际项目中，可根据业务需求选择 CPU/GPU 加速、调整优化策略，结合批量推理、异步执行等方式提升性能。同时，ONNX Runtime 还支持 NLP、语音等领域的模型推理，只需调整输入预处理和输出解析逻辑，即可快速适配不同场景。

参考资料

1. ONNX Runtime 官方文档；
2. ONNX Runtime Java API 文档；
3. ONNX Models 仓库；
4. OpenCV Java 文档。