Spring AI 实战系列 | 第 1.2 篇：环境准备与第一个项目
Spring AI 实战系列 | 第 1.2 篇：环境准备与第一个项目
系列说明：本文是《Spring AI 实战系列》第 1 篇的补充细化，手把手带你从零搭环境、跑通第一个 AI 对话。
前置知识：已经了解 Spring AI 是什么（没看过上文的建议先翻一下）。
前言
上篇文章聊完 Spring AI 是啥，评论区收到最多的留言就是：「别光说不练，到底怎么跑起来？」
这篇就来填坑。我会从最基础的环境准备开始，一步步带你搭好项目，最后让 AI 跟你说上第一句话。
整个过程大概 15 分钟。JDK 装好的同学可能 10 分钟就够了。
一、环境准备
1.1 JDK 版本
Spring AI 1.0+ 要求JDK 17 或更高。
怎么查自己现在的版本？
java-version如果显示 17、21 这种，直接跳过这节。如果还是 8 或 11，得先升级一下。JDK 17 的下载地址去 Oracle 官网或者 Adoptium 都行，不赘述。
1.2 构建工具
Spring AI 支持 Maven 和 Gradle，本文用 Maven 演示。Gradle 的同学对照着改一下依赖格式就行，逻辑完全一样。
1.3 一个 AI 模型的 API Key
这是最容易卡住的地方。
你需要一个支持 OpenAI 兼容格式的 API Key。三个选择：
- OpenAI 官方：需要海外信用卡，国内同学基本告别
- DeepSeek：国产模型，API 兼容 OpenAI 格式，注册就送额度，推荐
- 智谱 GLM / 通义千问：也是兼容格式，按需选择
本文用 DeepSeek 演示，因为国内能直接用，而且便宜。
注册地址：platform.deepseek.com，注册完在「API Keys」页面创建一个 key，复制下来备用。
二、创建项目
2.1 用 Spring Initializr
打开 https://start.spring.io，按下面配置：
| 选项 | 值 |
|---|---|
| Project | Maven |
| Language | Java |
| Spring Boot | 3.2.x 或更高 |
| Java | 17 |
Dependencies 里搜索并添加：
- Spring Web
- Spring AI OpenAI
注意：Spring Initializr 里的 Spring AI 版本可能不是最新的。如果列表里没有，或者版本太老，后面手动改 pom.xml 也行。
填好 Group 和 Artifact，点击 Generate，下载解压。
2.2 手动加依赖（如果 Initializr 没有 Spring AI）
打开pom.xml，在<dependencyManagement>里加 BOM：
<dependencyManagement><dependencies><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-bom</artifactId><version>1.0.0-M6</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement>然后在<dependencies>里加：
<dependencies><!-- Spring Boot Web --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- Spring AI OpenAI Starter --><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-openai-spring-boot-starter</artifactId></dependency></dependencies>用 DeepSeek 也是这个 starter，因为 DeepSeek 的 API 格式和 OpenAI 兼容，Spring AI 把它们归到同一套实现里。
2.3 配置 API Key
在src/main/resources/application.yml里写：
spring:ai:openai:api-key:${DEEPSEEK_API_KEY}base-url:https://api.deepseek.comchat:options:model:deepseek-chattemperature:0.7api-key这里用了环境变量引用，实际开发推荐这么干，别把 key 硬编码到代码里。
怎么设环境变量？
Windows（PowerShell）：
$env:DEEPSEEK_API_KEY="sk-xxxxxxxx"Mac/Linux：
exportDEEPSEEK_API_KEY=sk-xxxxxxxx或者在 IDEA 的 Run Configuration 里加 Environment Variables。
三、写第一个 Controller
3.1 最简单的对话接口
在src/main/java/com/example/demo/下新建一个ChatController.java：
packagecom.example.demo;importorg.springframework.ai.chat.client.ChatClient;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RequestMapping;importorg.springframework.web.bind.annotation.RequestParam;importorg.springframework.web.bind.annotation.RestController;@RestController@RequestMapping("/ai")publicclassChatController{privatefinalChatClientchatClient;publicChatController(ChatClient.BuilderchatClientBuilder){this.chatClient=chatClientBuilder.build();}@GetMapping("/chat")publicStringchat(@RequestParamStringmessage){returnchatClient.prompt().user(message).call().content();}}代码不多，核心就这几行：
ChatClient.Builder是 Spring AI 自动注入的，不用你手动 new.prompt()开始构建请求.user(message)把用户的问题塞进去.call()发起同步调用.content()取 AI 的回复文本
3.2 启动项目
直接运行DemoApplication的 main 方法，或者：
mvn spring-boot:run看到Started DemoApplication in x.x seconds就是启动成功了。
3.3 测试一下
打开浏览器或者 Postman，访问：
http://localhost:8080/ai/chat?message=你好，请用一句话介绍Spring AI如果一切正常，你会看到类似这样的回复：
Spring AI 是 Spring 官方推出的 AI 应用开发框架，让 Java 开发者可以用熟悉的方式集成大语言模型。第一次调用可能要等 3-5 秒，后面就快了。
如果报错，先检查这几个地方：
- API Key 有没有设对— 日志里如果看到 401，就是 key 的问题
- 网络能不能访问 api.deepseek.com— 公司内网可能要走代理
- base-url 有没有加— 用 DeepSeek 必须配这个，默认是 OpenAI 的官方地址
四、流式输出，让回复像打字一样
上面的例子是等 AI 全部生成完才返回，如果回复很长，用户会盯着空白页面发呆。
Spring AI 支持流式输出，一行代码搞定：
importorg.springframework.http.MediaType;importreactor.core.publisher.Flux;@GetMapping(value="/chat/stream",produces=MediaType.TEXT_EVENT_STREAM_VALUE)publicFlux<String>chatStream(@RequestParamStringmessage){returnchatClient.prompt().user(message).stream().content();}把.call()换成.stream()，返回类型改成Flux<String>，前端用 EventSource 接收，就能实现打字机效果。
测试可以用 curl：
curl-N"http://localhost:8080/ai/chat/stream?message=讲一个程序员笑话"你会看到文字一个一个蹦出来，而不是等半天一次性显示。
五、Gradle 用户看这里
前面都是 Maven 的示例，Gradle 的同学配置如下：
build.gradle：
plugins { id 'java' id 'org.springframework.boot' version '3.2.x' } dependencies { implementation 'org.springframework.boot:spring-boot-starter-web' implementation 'org.springframework.ai:spring-ai-openai-spring-boot-starter' } dependencyManagement { imports { mavenBom "org.springframework.ai:spring-ai-bom:1.0.0-M6" } }代码部分完全一样，Controller 不用改。
六、常见问题
Q1：Spring Initializr 里找不到 Spring AI？
Spring AI 还没进官方 Starter 列表，手动加依赖就行，不影响使用。
Q2：用 OpenAI 官方 API 怎么配？
把base-url删掉或注释掉，默认就是 OpenAI 的官方地址。model 改成gpt-4o或gpt-3.5-turbo。
Q3：temperature 是什么？
控制 AI 回答的「随机性」。值越大（比如 1.0），回答越放飞；值越小（比如 0.1），回答越保守、越确定。日常用 0.7 左右比较平衡。
Q4：报错Connection timeout？
检查网络。DeepSeek 的 API 地址在国内一般能直接访问，但某些公司网络可能有防火墙限制。可以先用 curl 测试连通性：
curlhttps://api.deepseek.com/v1/models-H"Authorization: Bearer$DEEPSEEK_API_KEY"写在最后
到这儿，你的第一个 Spring AI 项目应该已经跑起来了。
回顾一下我们干了什么：
- 确认 JDK 17+
- 用 Spring Initializr 创建项目
- 加了 Spring AI OpenAI Starter
- 配了 DeepSeek 的 API Key
- 写了一个 ChatController，支持同步和流式调用
- 测试成功，AI 回复了消息
下一篇会深入讲ChatClient 的完整用法，包括多模型切换、Prompt 模板、以及各种配置参数的实战技巧。
如果你在这一步遇到了问题，欢迎在评论区留言，我会尽量回复。
系列目录：
- 第 1 篇：Spring AI 概述与快速上手
- 第 1.2 篇：环境准备与第一个项目 ✅（本文）
- 第 2 篇：ChatClient 详解与多模型集成
- 第 3 篇：结构化输出与多模态
- 第 4 篇：Embedding 与向量数据库
- 第 5 篇：RAG 检索增强生成
- 第 6 篇：Tool Calling 工具调用
- 第 7 篇：Advisor 机制与对话管理
- 第 8 篇：MCP 模型上下文协议
- 第 9 篇：AI Agent 开发实战
- 第 10 篇：企业级应用与最佳实践
如果这篇文章对你有帮助，欢迎点赞收藏关注，系列持续更新中！