解决Java中ONNX Runtime导入失败问题：理解与配置类路径-java教程-PHP中文网

解决Java中ONNX Runtime导入失败问题：理解与配置类路径

花韻仙語

发布： 2025-09-25 13:34:20

原创

938人浏览过

解决Java中ONNX Runtime导入失败问题：理解与配置类路径

本教程旨在解决Java开发中导入ONNX Runtime时遇到的“包不存在”错误，即使已通过Maven添加依赖。文章将深入探讨Java类路径（Classpath）的核心概念，并提供在编译和运行时正确配置类路径的详细指导，确保ONNX模型能够在Java环境中顺利进行推理。

1. 问题描述：ONNX Runtime导入失败

在java项目中集成onnx runtime以进行模型推理时，开发者常会遇到一个普遍的问题：尽管已在pom.xml中正确添加了onnx runtime的maven依赖，但在尝试编译或运行java代码时，仍然收到“包不存在”（package does not exist）的错误。

例如，以下是一个典型的Maven依赖配置：

<?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>
        <dependency>
            <groupId>com.microsoft.onnxruntime</groupId>
            <artifactId>onnxruntime</artifactId>
            <version>1.13.1</version>
        </dependency>
    </dependencies>
</project>

登录后复制

尽管Maven已将onnxruntime-1.13.1.jar下载到本地仓库，并在IDE中显示为外部库，但当直接使用javac命令编译包含ONNX Runtime导入语句的Java文件时，例如：

package org.example;

import ai.onnxruntime.OrtEnvironment; // 错误可能出现在这里
// import ai.onnxruntime.OrtSession.Result.*; // 或者这里

public class Main {
    public static void main(String[] args) {
        // ...
    }
}

登录后复制

编译命令：

javac src/main/java/org/example/Main.java

登录后复制

可能导致如下错误：

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

src/main/java/org/example/Main.java:3: error: package ai.onnxruntime.OrtSession.Result does not exist
import ai.onnxruntime.OrtSession.Result.*;
^
1 error

登录后复制

这个错误表明Java编译器无法找到ai.onnxruntime包下的类，即使Maven已经处理了依赖。

2. 核心概念：Java类路径（Classpath）

要理解上述问题，关键在于掌握Java的类路径（Classpath）概念。

类路径的作用： Java虚拟机（JVM）和Java编译器（javac）在查找类和包时，需要知道去哪里寻找对应的.class文件或JAR文件。这个搜索路径集合就是类路径。
Maven与类路径： Maven是一个项目管理工具，它负责下载项目依赖的JAR包，并将它们放置在本地Maven仓库（通常是~/.m2/repository）中。当使用Maven的构建命令（如mvn compile或mvn package）时，Maven会自动配置好类路径，以便编译器和打包工具能够找到所有依赖。
直接使用javac和java： 然而，当您脱离Maven的上下文，直接使用javac命令编译源代码，或者使用java命令运行编译后的.class文件时，Java编译器和JVM并不知道Maven所管理的依赖位置。此时，您需要手动告诉它们去哪里寻找所需的JAR包，这就是通过java或javac命令的-cp（或-classpath）参数来完成的。

3. 解决方案：正确配置类路径

解决“包不存在”错误的核心在于确保在编译和运行时，Java能够访问到ONNX Runtime的JAR包。

3.1 方法一：直接通过java -cp命令指定类路径（适用于单文件执行）

对于简单的Java文件，尤其是在Java 11及更高版本中，您可以使用JEP 330（单文件源代码程序启动）特性，结合-cp参数直接运行Java源代码，而无需先手动编译。

BlessAI

Bless AI 提供五个独特的功能：每日问候、庆祝问候、祝福、祷告和名言的文本生成和图片生成。

查看详情

步骤：

确定ONNX Runtime JAR包的完整路径： 这个JAR包通常位于您的本地Maven仓库中。例如，对于ONNX Runtime 1.13.1版本，路径可能类似于：
- Windows: C:\Users\YourUsername\.m2\repository\com\microsoft\onnxruntime\onnxruntime\1.13.1\onnxruntime-1.13.1.jar
- macOS/Linux: /Users/YourUsername/.m2/repository/com/microsoft/onnxruntime/onnxruntime/1.13.1/onnxruntime-1.13.1.jar 请将YourUsername替换为您的实际用户名。

使用java -cp命令运行： 假设您的Java代码文件是src/main/java/org/example/Main.java，并且其中包含以下内容：

package org.example;

import ai.onnxruntime.OrtEnvironment;
import ai.onnxruntime.OrtSession;
import ai.onnxruntime.OrtException;

public class Main {
    public static void main(String[] args) {
        try {
            // 验证ONNX Runtime是否成功导入和初始化
            OrtEnvironment env = OrtEnvironment.getEnvironment();
            System.out.println("ONNX Runtime环境初始化成功！版本: " + env.getAPIVersion());
            // 可以在这里加载并运行ONNX模型
            // OrtSession session = env.createSession("path/to/your/model.onnx");
            // ...
        } catch (OrtException e) {
            System.err.println("ONNX Runtime初始化失败: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

登录后复制

您可以使用以下命令直接运行它（请替换为您的实际JAR包路径）：

Windows示例：

java -cp "C:\Users\XXXX\.m2\repository\com\microsoft\onnxruntime\onnxruntime\1.13.1\onnxruntime-1.13.1.jar" src\main\java\org\example\Main.java

登录后复制

macOS/Linux示例：

java -cp "/Users/XXXX/.m2/repository/com/microsoft/onnxruntime/onnxruntime/1.13.1/onnxruntime-1.13.1.jar" src/main/java/org/example/Main.java

登录后复制

注意： 如果您的Java版本低于11，或者您希望先编译再运行，您需要分别在javac和java命令中使用-cp参数。编译：

javac -cp "/Users/XXXX/.m2/repository/com/microsoft/onnxruntime/onnxruntime/1.13.1/onnxruntime-1.13.1.jar" src/main/java/org/example/Main.java

登录后复制

运行（假设编译后的Main.class在当前目录或其子目录中，且org.example包结构正确）：

java -cp "/Users/XXXX/.m2/repository/com/microsoft/onnxruntime/onnxruntime/1.13.1/onnxruntime-1.13.1.jar;." org.example.Main
# 或者对于Linux/macOS
java -cp "/Users/XXXX/.m2/repository/com/microsoft/onnxruntime/onnxruntime/1.13.1/onnxruntime-1.13.1.jar:." org.example.Main

登录后复制

这里的:或;是路径分隔符，.表示当前目录，用于查找Main.class文件。

3.2 方法二：利用Maven管理项目（推荐）

对于任何非简单的、结构化的Java项目，强烈推荐使用Maven来管理构建、依赖和运行。Maven会自动处理类路径问题，避免手动指定复杂的JAR包路径。

编译： 使用mvn compile命令。Maven会自动查找pom.xml中声明的所有依赖，并在编译时将其添加到类路径。
打包： 使用mvn package命令。这将生成一个JAR包，通常会包含您的代码和Maven管理的依赖（如果是“fat jar”或“uber jar”），或者生成一个包含依赖的lib目录。
运行：
- 如果打包生成的是一个包含所有依赖的“可执行JAR包”（例如，通过Maven Shade Plugin或Spring Boot Maven Plugin），可以直接使用java -jar your-project.jar运行。
- 如果打包生成的是一个普通的JAR包和独立的lib目录，您可以使用java -cp "lib/*:your-project.jar" YourMainClass（Linux/macOS）或java -cp "lib/*;your-project.jar" YourMainClass（Windows）来运行。
- 您也可以使用Maven的exec:java插件直接运行主类：
```
<build>
    <plugins>
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>exec-maven-plugin</artifactId>
            <version>3.0.0</version>
            <configuration>
                <mainClass>org.example.Main</mainClass>
            </configuration>
        </plugin>
    </plugins>
</build>
```
  登录后复制
  然后运行：mvn exec:java

4. 注意事项

路径分隔符： 在Windows系统上，类路径中的多个路径使用分号（;）分隔；在Linux/macOS系统上，使用冒号（:）分隔。
JAR包完整路径： 确保您提供的JAR包路径是完整的，指向.jar文件本身，而不是其所在的目录。
Java版本： Java 11引入的JEP 330使得可以直接运行单文件源代码，这在测试简单代码时非常方便。如果使用旧版本Java，则必须先编译（javac -cp ...），再运行（java -cp ...）。
通配符： 在Java 6及更高版本中，可以在类路径中使用通配符*来包含指定目录下所有的JAR文件。例如，java -cp "path/to/jars/*" YourMainClass。这对于包含多个依赖JAR的lib目录非常有用。

5. 总结

在Java项目中导入ONNX Runtime并遇到“包不存在”错误，通常不是因为Maven依赖配置有误，而是因为在脱离Maven构建工具直接使用javac或java命令时，没有正确地将ONNX Runtime的JAR包添加到Java的类路径中。通过理解类路径的工作原理，并利用-cp参数手动指定JAR包路径，或者更推荐地，通过Maven的构建和运行机制，可以有效地解决这类问题，确保ONNX模型在Java环境中的顺利集成和推理。

以上就是解决Java中ONNX Runtime导入失败问题：理解与配置类路径的详细内容，更多请关注php中文网其它相关文章！