Java集成ONNX Runtime：解决“包不存在”错误与类路径配置

引言：Java中ONNX Runtime导入困境

在java应用程序中集成onnx runtime以进行机器学习模型推理，是许多开发者面临的常见需求。然而，即使在项目中正确配置了maven依赖，部分用户在尝试编译或运行时，仍可能遭遇“包不存在”（package does not exist）的错误。这通常发生在直接使用javac或java命令行工具，而非通过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>
        <dependency>
            <groupId>com.microsoft.onnxruntime</groupId>
            <artifactId>onnxruntime</artifactId>
            <version>1.13.1</version>
        </dependency>
    </dependencies>
</project>

并且Java代码尝试导入相关类：

package org.example;

import ai.onnxruntime.OrtEnvironment;
// import ai.onnxruntime.OrtSession.Result.*; // 尝试导入此包时可能报错

public class Main {
    public static void main(String[] args) {
        var env = OrtEnvironment.getEnvironment();
        System.out.println("ONNX Runtime环境已初始化。");
    }
}

直接通过javac编译时，可能会遇到如下错误：

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已经下载了对应的JAR包到本地仓库。问题的核心在于Java的类路径（Classpath）机制。

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

理解Java类路径与依赖管理

Maven的作用： Maven是一个项目管理和理解工具，它通过pom.xml文件定义项目的依赖、构建过程和项目结构。当执行mvn install或mvn compile等命令时，Maven会自动从远程仓库下载所需的JAR包（例如onnxruntime-1.13.1.jar）到本地Maven仓库（通常位于用户主目录下的.m2/repository）。它也负责在构建过程中将这些依赖添加到编译和运行时的类路径中。

javac和java命令行的局限性：

• javac (Java编译器): 负责将.java源文件编译成.class字节码文件。在编译时，javac需要知道所有被引用类的位置。
• java (Java虚拟机/解释器): 负责加载并执行.class文件。在运行时，java虚拟机需要知道所有运行时所需类的位置。

当直接在命令行中使用javac或java时，它们并不会自动读取pom.xml文件来获取依赖信息。因此，即使Maven已经将ONNX Runtime的JAR包下载到本地，javac和java也无法默认找到这些类，除非通过类路径参数明确告知它们。

解决方案一：利用Maven构建生命周期（推荐）

对于Maven项目，最推荐且最健壮的方法是始终通过Maven自身的命令来管理编译、打包和运行。Maven会自动处理所有依赖的类路径配置。

1. 编译项目：

   mvn clean compile

   登录后复制

   这条命令会清理旧的编译产物，然后根据pom.xml下载所有依赖，并将项目的.java文件编译成.class文件。此时，Maven会自动将ONNX Runtime的JAR包包含在编译器的类路径中。

   

   AISEO

   AI创作对SEO友好的文案和文章

   56

   查看详情

2. 打包项目：

   mvn package

   登录后复制

   这条命令会编译项目，并将其打包成JAR或WAR文件。如果需要一个包含所有依赖的“胖JAR”（fat JAR），可以使用maven-assembly-plugin或maven-shade-plugin。

3. 运行项目（使用Maven插件）： 要直接运行主类，可以使用exec-maven-plugin。首先，在pom.xml中配置该插件：

   <build>
       <plugins>
           <plugin>
               <groupId>org.codehaus.mojo</groupId>
               <artifactId>exec-maven-plugin</artifactId>
               <version>3.1.0</version> <!-- 使用最新版本 -->
               <executions>
                   <execution>
                       <goals>
                           <goal>java</goal>
                       </goals>
                   </execution>
               </executions>
               <configuration>
                   <mainClass>org.example.Main</mainClass> <!-- 你的主类 -->
               </configuration>
           </plugin>
       </plugins>
   </build>

   登录后复制

   然后，通过以下命令运行：

   mvn exec:java

   登录后复制

   Maven会自动构建类路径并执行指定的mainClass。

解决方案二：手动指定类路径进行编译与执行

如果出于特定原因，必须直接使用javac或java命令行工具，那么就需要手动通过-cp（或-classpath）参数来指定ONNX Runtime的JAR包路径。

1. 定位ONNX Runtime的JAR包： ONNX Runtime的JAR包通常位于你的本地Maven仓库中。其路径结构为： ~/.m2/repository/com/microsoft/onnxruntime/onnxruntime/<version>/onnxruntime-<version>.jar

例如，对于版本1.13.1，在macOS/Linux上可能是： /Users/你的用户名/.m2/repository/com/microsoft/onnxruntime/onnxruntime/1.13.1/onnxruntime-1.13.1.jar

在Windows上可能是： C:\Users\你的用户名\.m2\repository\com\microsoft\onnxruntime\onnxruntime\1.13.1\onnxruntime-1.13.1.jar

2. 手动编译 (javac)： 在编译时，你需要将ONNX Runtime的JAR包添加到javac的类路径中。

• Linux/macOS示例：

  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

  登录后复制
• Windows示例：

  javac -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

  登录后复制

  请注意，Windows路径使用反斜杠\作为分隔符，而类路径中的多个条目则使用分号;分隔。

3. 手动执行 (java)： 执行Java应用程序时，同样需要指定类路径。

• 对于Java 11+的单文件执行 (JEP 330)： Java 11引入了JEP 330，允许直接运行单个源文件，无需显式编译。但仍需指定类路径。

  • Linux/macOS示例：

    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

    登录后复制
  • 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

    登录后复制

• 对于已编译的.class文件执行： 如果已经通过javac编译生成了.class文件（例如在target/classes目录下），则执行时需要将ONNX Runtime的JAR包路径和你的程序类路径（通常是当前目录.或编译输出目录）都包含在-cp参数中。

  • Linux/macOS示例：

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

    登录后复制

    （注意使用冒号:分隔类路径条目）

  • Windows示例：

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

    登录后复制

    （注意使用分号;分隔类路径条目）

注意事项与最佳实践

1. 优先使用Maven/Gradle： 对于任何非最简单的Java项目，强烈建议使用Maven或Gradle等构建工具。它们能够自动化依赖管理和类路径配置，显著提高开发效率并减少错误。
2. 版本一致性： 确保pom.xml中声明的ONNX Runtime版本与手动指定JAR包的路径版本一致。
3. 传递性依赖： ONNX Runtime本身可能依赖其他库。当手动指定类路径时，理论上你需要将所有这些传递性依赖的JAR包也一并加入类路径。这是手动管理类路径的复杂之处，也是构建工具的巨大优势。
4. IDE集成： 现代集成开发环境（IDE），如IntelliJ IDEA、Eclipse或VS Code，在导入Maven项目后，会自动解析pom.xml并配置好编译和运行时的类路径，因此在IDE内部通常不会遇到此类问题。
5. 跨平台兼容性： 命令行中的路径分隔符（Windows的;和\，Linux/macOS的:和/）是常见的混淆点，务必根据操作系统正确使用。

总结

“包不存在”错误在Java项目中，尤其是在涉及外部库时，是一个典型的类路径问题。理解Java的类路径机制是解决这类问题的关键。对于Maven项目，最佳实践是利用Maven自身的构建和运行命令来自动化类路径管理。如果必须手动操作，则需要通过javac和java命令的-cp参数，明确指定所有必需的依赖JAR包路径。掌握这些知识，将有助于开发者更有效地在Java应用程序中集成和使用ONNX Runtime，顺利进行模型推理任务。

以上就是Java集成ONNX Runtime：解决“包不存在”错误与类路径配置的详细内容，更多请关注php中文网其它相关文章！