Spring AI 环境搭建：JDK/Maven/API Key 配置与第一个对话

本节目标：配好开发环境，用 Spring AI 跑通第一个对话程序。学完你能独立搭建一个能调用大模型的最小项目。

2.1 需要准备什么

开发环境需要三样东西：

JDK 17 或更高版本，建议直接用 21。
Maven 3.6+ 或 Gradle，任选其一。
一个大模型厂商的 API Key。

本教程以 Maven 为例。API Key 推荐用 OpenAI，或任何兼容 OpenAI 协议的国内服务（DeepSeek、硅基流动等）。它们的接入方式几乎一样，只是 base-url 和模型名不同。

用 Gradle 的读者注意：BOM 的引入方式是 implementation platform(“org.springframework.ai:spring-ai-bom:2.0.0”)，其余逻辑一致，后文仍以 Maven 展示。

获取 API Key 的流程大同小异：注册账号、充值、在控制台创建密钥。密钥是敏感信息，别提交到代码仓库。IDE 用不用都行，命令行加文本编辑器也够用。

团队内网或代理环境要注意：Maven 和运行时都要能访问 Maven Central 和模型厂商的 API 域名。公司代理拦得严的，先在 IDE 或构建配置里把代理设好，再谈写代码。

Note

版本基线：本教程示例基于 Spring Boot 4.0.x 与 spring-ai-bom 2.0.0。官方文档指出 Spring AI 2.0.x 支持 Spring Boot 4.0.x / 4.1.x（对应 Spring Framework 7.0）。还在用 Boot 3.4/3.5 的旧项目，可参考 1.1.x 维护线。环境与示例不一致时，以官方文档为准。

2.2 创建项目

两种方式：start.spring.io 网页生成，或手动建 Maven 工程。

网页生成按下面几步走：

打开 start.spring.io。
语言选 Java，版本选 21，Spring Boot 选 4.0.x。
依赖搜索框勾选 Spring Web，再勾选 Spring AI 相关依赖（或先跳过，后面手动加）。
点 Generate 下载压缩包，解压后用 IDE 打开。

start.spring.io 已提供 AI 依赖选项，找不到对应选项时也没关系，后面手动加。也可以直接手写 pom.xml，下面这份是最小配置：

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

<properties>
    <java.version>21</java.version>
    <spring-ai.version>2.0.0</spring-ai.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </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>

BOM 是纯依赖管理，不含插件声明，也不直接引用 Spring Boot。Boot 版本仍由 spring-boot-starter-parent 控制，两者各管各的，不冲突。

两个关键点：

spring-ai-bom 负责统一 Spring AI 各模块的版本。你只写一次版本号，其他模块不用再带版本。
spring-ai-starter-model-openai 是 OpenAI 模型的 Starter。换厂商就换这个依赖，代码不动。

Starter 干了两件事：拉进模型模块的依赖，以及通过自动配置生成 ChatClient.Builder 等 Bean。所以代码里什么都不用 new，注入就能用。首次构建会下载不少依赖，耐心等几分钟。

项目结构保持 Spring Boot 惯例即可：

src/
├── main/
│   ├── java/com/example/ai/
│   │   ├── AiApplication.java
│   │   └── FirstChatRunner.java
│   └── resources/
│       └── application.properties
└── test/

发布版本都在 Maven Central，不需要额外配置仓库。想用快照版才需要加 Spring 的快照仓库，入门阶段用不到。国内拉依赖慢的话，给 Maven 配置阿里云镜像，改 settings.xml 的 mirror 节点即可，Spring AI 的包镜像同步没问题。换镜像后如果构建报奇怪的包错误，先清一次本地仓库缓存（~/.m2/repository）再重试。

2.3 配置 API Key

在 src/main/resources/application.properties 里配置：

spring.ai.openai.api-key=${OPENAI_API_KEY}
spring.ai.openai.chat.model=gpt-4o-mini

三个配置项各管一件事：

配置项	作用
spring.ai.openai.api-key	调用模型用的密钥
spring.ai.openai.base-url	API 地址，默认指向 OpenAI 官方
spring.ai.openai.chat.model	使用的模型名

api-key 不要直接写死。用环境变量 OPENAI_API_KEY 注入，密钥就不会出现在代码里。环境变量的设置方式随系统不同：Windows 用 setx，macOS/Linux 写进 ~/.zshrc 或 ~/.bashrc，IDE 里也可以在运行配置中指定。改完环境变量要重开终端或 IDE 才生效，没生效先检查这一步。

用兼容 OpenAI 协议的国产服务时，加一行 base-url 就行：

spring.ai.openai.base-url=https://api.deepseek.com
spring.ai.openai.api-key=${DEEPSEEK_API_KEY}
spring.ai.openai.chat.model=deepseek-chat

模型名要写成厂商真实存在的。写错会报 model not found 之类的错误。这些配置写在 application.properties 或 application.yaml 里效果一样，按团队习惯选。同时对接多个厂商时，各自用独立前缀配置，互不干扰。新申请的 Key 通常带免费额度，够跑完本教程。注意厂商的限流规则，短时间大量请求可能被限。

2.4 第一个对话

建一个启动类，再写一个 CommandLineRunner。应用启动后自动问一次模型，把回答打印出来：

@SpringBootApplication
public class AiApplication {

    public static void main(String[] args) {
        SpringApplication.run(AiApplication.class, args);
    }
}

@Component
public class FirstChatRunner implements CommandLineRunner {

    private final ChatClient chatClient;

    public FirstChatRunner(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @Override
    public void run(String... args) {
        String answer = this.chatClient.prompt()
                .user("用一句话介绍 Spring AI")
                .call()
                .content();
        System.out.println("AI: " + answer);
    }
}

这段代码做了三件事：

注入自动配置的 ChatClient.Builder，build() 出 ChatClient。
prompt().user() 构造请求，call() 真正调用模型。
content() 取出回答文本。

ChatClient.Builder 是 Spring Boot 自动配置好的原型 Bean，注入即用，不需要自己 new。

这一串调用的完整链路是：ChatClient 构造 Prompt，交给 ChatModel，由厂商 SDK 发 HTTP 请求到模型服务，响应再原路返回。中间任何一环出问题，都能在日志里找到线索。

启动类、Runner、配置文件三件套齐了，运行 mvn spring-boot:run，看到控制台输出回答，第一个对话就成功了。

想做成 Web 接口，把 Runner 换成 Controller 即可：

@RestController
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @GetMapping("/chat/ask")
    public String ask(@RequestParam(defaultValue = "你好") String message) {
        return this.chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

启动后浏览器访问 http://localhost:8080/chat/ask?message=你好，就能看到模型回答。命令行验证用 curl 也一样。参数没传时 defaultValue 兜底，接口不会因为缺参报错。想换模型厂商，改依赖和配置即可，Controller 一行不用动——这就是第 1 章说的可移植性。

Tip

两种写法只是载体不同：Runner 适合验证和批处理，Controller 适合对外提供服务。核心都是那三行链式调用。跑通第一个对话后，把 Key 换成其他兼容厂商试试，体会一下”业务代码不动”的承诺。

2.5 常见问题

401 Unauthorized：API Key 不对或没配好。检查环境变量是否真的传进了应用。
404 / model not found：模型名不存在，或 base-url 写错。对照厂商文档核对。
请求超时：国内访问 OpenAI 官方需要网络方案。换国内兼容服务最省事。
想看请求细节：把日志级别调低，后面讲 Advisor 时会介绍 SimpleLoggerAdvisor。
报错提示缺少 WebClient：stream() 流式调用依赖 spring-boot-starter-webflux，需要时再加。
用 Boot 3.4 且涉及图像模型时（1.x 时代的坑），官方文档提示要设置 spring.http.client.factory=jdk，否则 AI 工作流会异常。2.0 对应 Boot 4，这个规避不再需要。
启动报 NoClassDefFoundError：依赖没下全。检查 Maven 镜像配置和网络，清掉本地仓库缓存重试。
端口被占用：改 server.port 配置项，或关掉占用进程。
回答不是中文：模型按提示词语言回答。想让输出稳定用中文，在提示词里写明”请用中文回答”。

环境准备与第一个 AI 对话

2.1 需要准备什么

2.2 创建项目

2.3 配置 API Key

2.4 第一个对话

2.5 常见问题

2.6 小结