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按下面配置选项值ProjectMavenLanguageJavaSpring Boot3.2.x 或更高Java17Dependencies 里搜索并添加Spring WebSpring AI OpenAI注意Spring Initializr 里的 Spring AI 版本可能不是最新的。如果列表里没有或者版本太老后面手动改 pom.xml 也行。填好 Group 和 Artifact点击 Generate下载解压。2.2 手动加依赖如果 Initializr 没有 Spring AI打开pom.xml在dependencyManagement里加 BOMdependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion1.0.0-M6/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagement然后在dependencies里加dependencies!-- Spring Boot Web --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency!-- Spring AI OpenAI Starter --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-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 硬编码到代码里。怎么设环境变量WindowsPowerShell$env:DEEPSEEK_API_KEYsk-xxxxxxxxMac/LinuxexportDEEPSEEK_API_KEYsk-xxxxxxxx或者在 IDEA 的 Run Configuration 里加 Environment Variables。三、写第一个 Controller3.1 最简单的对话接口在src/main/java/com/example/demo/下新建一个ChatController.javapackagecom.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;RestControllerRequestMapping(/ai)publicclassChatController{privatefinalChatClientchatClient;publicChatController(ChatClient.BuilderchatClientBuilder){this.chatClientchatClientBuilder.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,producesMediaType.TEXT_EVENT_STREAM_VALUE)publicFluxStringchatStream(RequestParamStringmessage){returnchatClient.prompt().user(message).stream().content();}把.call()换成.stream()返回类型改成FluxString前端用 EventSource 接收就能实现打字机效果。测试可以用 curlcurl-Nhttp://localhost:8080/ai/chat/stream?message讲一个程序员笑话你会看到文字一个一个蹦出来而不是等半天一次性显示。五、Gradle 用户看这里前面都是 Maven 的示例Gradle 的同学配置如下build.gradleplugins { 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 不用改。六、常见问题Q1Spring Initializr 里找不到 Spring AISpring AI 还没进官方 Starter 列表手动加依赖就行不影响使用。Q2用 OpenAI 官方 API 怎么配把base-url删掉或注释掉默认就是 OpenAI 的官方地址。model 改成gpt-4o或gpt-3.5-turbo。Q3temperature 是什么控制 AI 回答的「随机性」。值越大比如 1.0回答越放飞值越小比如 0.1回答越保守、越确定。日常用 0.7 左右比较平衡。Q4报错Connection timeout检查网络。DeepSeek 的 API 地址在国内一般能直接访问但某些公司网络可能有防火墙限制。可以先用 curl 测试连通性curlhttps://api.deepseek.com/v1/models-HAuthorization: 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 篇企业级应用与最佳实践如果这篇文章对你有帮助欢迎点赞收藏关注系列持续更新中