Java 环境搭建

Spring AI 是 Java 生态中接入大模型的官方方案。本笔记涵盖 JDK、Maven/Gradle、SDKMAN、Spring Initializr。

版本选择

组件推荐版本说明
JDK21（LTS）Spring Boot 3.4+ / Spring AI 1.0 要求
构建工具Maven 3.9+ 或 Gradle 8.5+推荐 Maven，社区更广
Spring Boot3.4.x2025 年主流
Spring AI1.0+GA 版本，API 已稳定

SDKMAN：Java 版本管理器（推荐）

安装 SDKMAN

1
2
3
4
5
6
# Linux/macOS
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

# 验证
sdk version

使用 SDKMAN 管理 JDK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 列出可用 JDK
sdk list java

# 安装 Eclipse Temurin（OpenJDK）LTS 版
sdk install java 21.0.5-tem

# 安装特定版本
sdk install java 17.0.13-tem

# 切换版本
sdk default java 21.0.5-tem

# 当前使用版本
sdk current java

Temurin（原 AdoptOpenJDK）是 OpenJDK 的免费发行版，由 Eclipse 基金会维护，生产可用。

Maven 安装与使用

安装 Maven

1
2
3
4
5
6
7
# SDKMAN 安装（推荐）
sdk install maven 3.9.9

# 或手动下载
wget https://dlcdn.apache.org/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz
tar -xzf apache-maven-3.9.9-bin.tar.gz -C /opt/
export PATH="/opt/apache-maven-3.9.9/bin:$PATH"

Maven 常用命令

1
2
3
4
5
6
7
mvn --version              # 查看版本
mvn clean compile          # 编译
mvn test                   # 运行测试
mvn package -DskipTests    # 打包（跳过测试）
mvn spring-boot:run        # 运行 Spring Boot
mvn dependency:tree        # 查看依赖树
mvn dependency:resolve     # 下载依赖

Gradle 安装与使用

1
2
3
4
# SDKMAN 安装
sdk install gradle 8.11.1

# 或使用 Spring Initializr 自带的 Gradle Wrapper（推荐）

建议：除非团队已有 Gradle 项目，否则推荐 Maven——依赖声明更直观，生态更成熟。

Spring Initializr：项目脚手架

Web 方式创建项目

访问：https://start.spring.io

![Spring Initializr 配置示例]

1
2
3
4
5
6
7
8
Project: Maven
Language: Java
Spring Boot: 3.4.x
Group: com.example
Artifact: ai-agent-demo
Dependencies:
  - Spring Web
  - Spring AI (搜索添加)

下载后运行

1
2
3
unzip ai-agent-demo.zip
cd ai-agent-demo
mvn spring-boot:run

curl 方式创建（命令行用户）

1
2
3
4
5
6
7
8
9
10
11
12
curl https://start.spring.io/starter.zip \
  -d type=maven \
  -d language=java \
  -d bootVersion=3.4.1 \
  -d baseDir=ai-agent-demo \
  -d groupId=com.example \
  -d artifactId=ai-agent-demo \
  -d name=ai-agent-demo \
  -d packageName=com.example.aiagent \
  -d javaVersion=21 \
  -d dependencies=web,spring-ai-starter-model-openai \
  -o ai-agent-demo.zip && unzip ai-agent-demo.zip

Spring AI 依赖配置（pom.xml）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
<?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
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.4.1</version>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>ai-agent-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <properties>
        <java.version>21</java.version>
        <spring-ai.version>1.0.0-M6</spring-ai.version>
    </properties>

    <dependencies>
        <!-- Spring AI OpenAI -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-openai</artifactId>
        </dependency>

        <!-- Spring AI Ollama（本地模型）-->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-ollama</artifactId>
        </dependency>

        <!-- Spring Web（REST API）-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Test -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.ai</groupId>
                <artifactId>spring-ai-bom</artifactId>
                <version>${spring-ai.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

⚠️ 版本号：1.0.0-M6 是 Milestone 版本，生产环境建议确认最新 GA 版本。

项目结构（推荐）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
ai-agent-demo/
├── pom.xml
├── src/main/java/com/example/aiagent/
│   ├── AiAgentApplication.java
│   ├── config/
│   │   └── AIConfig.java              # AI Bean 配置
│   ├── controller/
│   │   └── ChatController.java        # REST 接口
│   └── service/
│       └── ChatService.java           # 业务逻辑
├── src/main/resources/
│   ├── application.yml                # 主配置
│   └── application-local.yml          # 本地开发配置
└── .env                               # API Keys（不提交Git）

环境变量配置（.env）

1
2
3
4
5
6
7
# .env 文件（加入 .gitignore）
OPENAI_API_KEY=sk-xxxxx
SPRING_AI_OPENAI_API_KEY=${OPENAI_API_KEY}

# 本地 Ollama（可选）
OLLAMA_BASE_URL=http://localhost:11434
SPRING_AI_OLLAMA_BASE_URL=${OLLAMA_BASE_URL}

application.yml 读取环境变量

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
spring:
  application:
    name: ai-agent-demo
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o
          temperature: 0.7

---
spring:
  config:
    activate:
      on-profile: local
  ai:
    openai:
      base-url: https://api.siliconflow.cn/v1   # 国内镜像

常用 AI Java 库生态

库说明
Spring AI官方 AI 集成框架，支持 OpenAI/Anthropic/Ollama 等
Semantic Kernel微软出品，Java 支持较新，企业 Microsoft 生态首选
LangChain4jJava 移植版 LangChain，功能较全
Dify API低代码平台，通过 HTTP API 集成（Java 最友好）