📚 课程目录第2章环境搭建

环境搭建：安装Java JDK、Maven、ONNX Runtime Java库

在开始使用ONNX Runtime进行Java部署之前，必须先完成基础环境的搭建。本章节将引导你完成三个核心组件的安装与配置：Java JDK（提供编译与运行环境）、Maven（负责依赖管理与构建）、以及ONNX Runtime Java库（通过Maven坐标引入项目）。这三者构成了后续所有模型推理实验的基石。

核心原理：三者的协作关系

理解三者如何协作，有助于在后续排障时快速定位问题。Java程序通过JDK提供的编译器（javac）和运行时（JVM）执行；Maven作为构建工具，从中央仓库下载并管理项目依赖；ONNX Runtime Java库则是一个JAR包，它通过JNI（Java Native Interface）调用底层C++推理引擎，从而在JVM中高效执行ONNX模型。

关键点：ONNX Runtime的Java API只是薄薄的一层封装，真正的计算发生在原生代码中。因此，安装JDK时务必注意位数匹配（64位JDK对应64位原生库），否则会抛出UnsatisfiedLinkError。

方法流程：分步安装与验证

1. 安装Java JDK（推荐版本17 LTS）

ONNX Runtime Java库要求JDK 8及以上版本，但为了获得更好的性能和长期支持，强烈建议使用JDK 17。安装步骤如下：

访问 Adoptium 或 Oracle官网下载对应操作系统的JDK 17安装包。
安装完成后，配置系统环境变量 JAVA_HOME 指向JDK安装目录。
将 %JAVA_HOME%\bin（Windows）或 $JAVA_HOME/bin（Linux/macOS）添加到 PATH 变量。

验证安装是否成功，打开终端执行：

java -version
# 预期输出示例：
# openjdk version "17.0.10" 2024-01-16 LTS
# OpenJDK Runtime Environment (build 17.0.10+7)
# OpenJDK 64-Bit Server VM (build 17.0.10+7, mixed mode, sharing)

提示：在Linux/macOS上，可以使用包管理器快速安装：sudo apt install openjdk-17-jdk（Ubuntu）或 brew install openjdk@17（macOS）。

2. 安装Maven构建工具

Maven是Java生态中最流行的构建工具之一。安装方式有两种：

方式一（推荐）：从 Apache Maven官网下载二进制压缩包，解压后配置 MAVEN_HOME 环境变量。
方式二：使用包管理器安装（如 brew install maven 或 sudo apt install maven）。

验证Maven安装：

mvn -version
# 预期输出示例：
# Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc2d9cac1a)
# Maven home: /opt/homebrew/Cellar/maven/3.9.6/libexec
# Java version: 17.0.10, vendor: Eclipse Adoptium, runtime: /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home

注意：Maven版本需3.6.3以上，否则可能无法正确解析ONNX Runtime的依赖元数据。如果使用旧版Maven，请先升级。

3. 在项目中引入ONNX Runtime Java库

ONNX Runtime的Java库已发布到Maven中央仓库，无需手动下载JAR文件。在项目的 pom.xml 中添加以下依赖：

<dependency>
    <groupId>com.microsoft.onnxruntime</groupId>
    <artifactId>onnxruntime</artifactId>
    <version>1.17.1</version>
</dependency>

如果你需要GPU加速（CUDA），则使用带GPU支持的构件：

<dependency>
    <groupId>com.microsoft.onnxruntime</groupId>
    <artifactId>onnxruntime_gpu</artifactId>
    <version>1.17.1</version>
</dependency>

添加依赖后，执行 mvn clean compile 让Maven下载依赖并编译项目。首次下载可能需要几分钟，请耐心等待。

案例场景：创建最小推理项目验证环境

为了确认环境配置无误，我们创建一个最简单的Java类来加载ONNX Runtime并检查版本信息。在 src/main/java 下创建 EnvCheck.java：

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

public class EnvCheck {
    public static void main(String[] args) throws Exception {
        OrtEnvironment env = OrtEnvironment.getEnvironment();
        System.out.println("ONNX Runtime 版本: " + OrtEnvironment.getVersion());
        System.out.println("可用 providers: " + env.getAvailableProviders());
        env.close();
    }
}

运行该程序：

mvn exec:java -Dexec.mainClass="EnvCheck"
# 预期输出（部分）：
# ONNX Runtime 版本: 1.17.1
# 可用 providers: [CPUExecutionProvider]

如果看到类似输出，说明JDK、Maven和ONNX Runtime Java库均已正确配置，可以开始后续的模型部署开发。

误区与复盘：常见安装问题排查

症状	可能原因	解决方案
`java.lang.UnsatisfiedLinkError`	JDK位数与原生库不匹配（如32位JDK运行64位库）	卸载32位JDK，安装64位JDK 17
`Could not resolve dependencies`	Maven无法访问中央仓库，或版本号错误	检查网络代理设置；确认 `pom.xml` 中版本号存在
`NoClassDefFoundError`	运行时未正确加载ONNX Runtime JAR	执行 `mvn clean package` 后使用 `java -cp target/classes:依赖路径` 运行
Maven编译时提示 `无效的目标发行版`	Maven使用的JDK版本与项目配置不一致	检查 `JAVA_HOME` 是否指向JDK 17；在 `pom.xml` 中设置 `<maven.compiler.source>17</maven.compiler.source>`

重要提醒：不要将ONNX Runtime的JAR包手动复制到 lib 目录，这会导致版本冲突和依赖管理混乱。始终通过Maven声明依赖。

复盘清单：环境搭建完成度自检

✅ java -version 显示JDK 17（或更高）
✅ mvn -version 显示Maven 3.6.3+，且Java版本与JDK一致
✅ pom.xml 中已添加 onnxruntime 依赖
✅ 执行 mvn clean compile 无报错
✅ 运行 EnvCheck 能打印ONNX Runtime版本号