Java中ONNX Runtime的正确导入与运行指南-java教程-PHP中文网

Java中ONNX Runtime的正确导入与运行指南

霞舞

发布： 2025-09-25 13:37:23

原创

984人浏览过

Java中ONNX Runtime的正确导入与运行指南

本文旨在解决Java项目中ONNX Runtime库导入失败的问题。即使已在Maven pom.xml 中正确添加了依赖，直接使用 javac 或 java 命令编译或运行时仍可能遭遇 package does not exist 错误。核心问题在于编译和运行阶段需要显式地将ONNX Runtime的JAR包路径添加到Java的Classpath中。本文将详细介绍如何配置Maven依赖，并提供正确的命令行编译与运行方法，以确保ONNX模型能在Java环境中成功加载和推理。

理解问题：依赖管理与编译/运行环境

在java开发中，尤其是在使用maven等构建工具时，开发者可能会遇到一个常见的困惑：即使在 pom.xml 中声明了某个库的依赖，但在尝试编译或运行代码时，仍然会收到 package does not exist 的错误。这通常发生在直接使用 javac 或 java 命令，而不是通过maven或其他ide的构建流程时。

其根本原因在于Maven主要负责管理项目的依赖关系，它会将所需的JAR包下载到本地Maven仓库（通常是 ~/.m2/repository ）。然而，当您直接调用 javac（Java编译器）或 java（Java虚拟机）命令时，它们并不会自动识别Maven仓库中的依赖。这些命令需要通过 classpath 参数明确告知在哪里可以找到所需的类文件。当 ai.onnxruntime 包找不到时，就意味着ONNX Runtime的JAR包没有被正确地包含在当前操作的Classpath中。

Maven依赖配置

首先，确保您的Maven pom.xml 文件中已正确添加了ONNX Runtime的依赖。这是一个标准的配置示例：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>test_first</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <!-- ONNX Runtime Java API -->
        <dependency>
            <groupId>com.microsoft.onnxruntime</groupId>
            <artifactId>onnxruntime</artifactId>
            <version>1.13.1</version>
        </dependency>
    </dependencies>
</project>

登录后复制

在添加此依赖后，运行 mvn clean install 或 mvn compile 命令，Maven会自动下载 onnxruntime-1.13.1.jar 到您的本地Maven仓库。这个步骤是确保依赖存在的基础。

核心解决方案：正确设置Classpath

Classpath是Java虚拟机（JVM）和Java编译器（Javac）查找类文件和资源文件的路径集合。当您直接使用 javac 或 java 命令时，必须通过 -cp 或 -classpath 参数明确指定所有必要的JAR包路径。

立即学习“Java免费学习笔记（深入）”；

1. 编译Java代码

如果您需要手动编译Java源文件，需要将ONNX Runtime的JAR包路径加入到 javac 命令的Classpath中。

# 假设您的ONNX Runtime JAR包位于Maven本地仓库的以下路径
# 示例路径 (请根据您的操作系统和Maven仓库实际路径进行调整)
ONNX_RUNTIME_JAR="/Users/XXXX/.m2/repository/com/microsoft/onnxruntime/onnxruntime/1.13.1/onnxruntime-1.13.1.jar"

# 编译Main.java
javac -cp "${ONNX_RUNTIME_JAR}" src/main/java/org/example/Main.java

登录后复制

请注意，XXXX 应替换为您的实际用户名，且Windows系统路径分隔符为 \，例如 C:\Users\XXXX\.m2\...。

2. 运行Java应用程序

对于Java 11及更高版本，可以通过JEP 330特性直接运行单个源文件，此时同样需要指定Classpath。

# 假设您的ONNX Runtime JAR包路径已定义
ONNX_RUNTIME_JAR="/Users/XXXX/.m2/repository/com/microsoft/onnxruntime/onnxruntime/1.13.1/onnxruntime-1.13.1.jar"

# 运行Main.java
java -cp "${ONNX_RUNTIME_JAR}" src/main/java/org/example/Main.java

登录后复制

如果您已经编译了 .class 文件，并且 Main.class 位于当前目录或某个输出目录（例如 target/classes），则运行命令如下：

MindShow

MindShow官网 | AI生成PPT，快速演示你的想法

1492

查看详情

# 假设ONNX_RUNTIME_JAR已定义，并且编译后的类文件在当前目录
java -cp ".:${ONNX_RUNTIME_JAR}" org.example.Main

# 或者，如果类文件在target/classes，且当前在项目根目录
java -cp "target/classes:${ONNX_RUNTIME_JAR}" org.example.Main

登录后复制

Classpath路径分隔符注意事项：

在Unix/Linux/macOS系统上，Classpath中的多个路径使用 : (冒号) 分隔。
在Windows系统上，Classpath中的多个路径使用 ; (分号) 分隔。

示例代码

以下是用于测试ONNX Runtime导入和初始化的简单Java代码：

package org.example;

import ai.onnxruntime.OrtEnvironment;
import ai.onnxruntime.OrtSession; // 导入OrtSession以备后续使用

public class Main {
    public static void main(String[] args) {
        System.out.println("尝试初始化ONNX Runtime环境...");
        try {
            // 获取ONNX Runtime环境实例
            OrtEnvironment env = OrtEnvironment.getEnvironment();
            System.out.println("ONNX Runtime环境初始化成功！版本: " + env.getVersion());

            // 示例：可以进一步加载模型并进行推理
            // String modelPath = "path/to/your/model.onnx";
            // OrtSession session = env.createSession(modelPath);
            // System.out.println("ONNX模型加载成功！");
            // session.close();

        } catch (Exception e) {
            System.err.println("ONNX Runtime环境初始化失败或发生其他错误: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

登录后复制

注意事项与最佳实践

Maven构建： 对于复杂的项目，强烈建议使用Maven的完整生命周期管理。通过 mvn compile 编译代码，通过 mvn package 打包项目。如果需要运行，可以使用Maven的 exec 插件，或者将项目打包成一个包含所有依赖的“胖JAR”（fat JAR），然后通过 java -jar your-app-with-dependencies.jar 运行。

Maven Exec Plugin 示例：

<build>
    <plugins>
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>exec-maven-plugin</artifactId>
            <version>3.0.0</version>
            <executions>
                <execution>
                    <goals>
                        <goal>java</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <mainClass>org.example.Main</mainClass>
            </configuration>
        </plugin>
    </plugins>
</build>

登录后复制

然后通过 mvn exec:java 运行。

IDE集成： 使用IntelliJ IDEA、Eclipse等集成开发环境（IDE）时，IDE通常会自动处理Classpath的设置，使得开发者无需手动管理。这是日常开发中最推荐的方式。
ONNX Runtime版本： 确保您使用的ONNX Runtime Java API版本与底层C++运行时库兼容。
动态库加载： ONNX Runtime Java API在内部会尝试加载本地库（.so、.dll、.dylib 文件）。在某些环境下，可能需要确保这些动态库位于系统PATH或Java的 java.library.path 中。Maven依赖通常会处理这些，但在特殊部署场景下需要注意。