一、Spring AI 是什么Spring AI 是 Spring 官方推出的AI应用开发框架核心做了三件事统一抽象层把OpenAI、通义千问、DeepSeek、Ollama等不同模型提供商的API差异屏蔽掉你换模型只改配置不改代码。工程化封装Prompt模板、结构化输出、Function Calling、RAG、向量存储……这些AI开发的高频需求全部有开箱即用的API。Spring原生集成自动配置、依赖注入、Actuator监控跟你写了十年的Spring Boot应用无缝融合。用一张图理解Spring AI的核心架构关键洞察这跟当年Spring Data JPA统一各种数据库的操作是一模一样的思路。Spring最擅长的事情就是——在混乱的API之上建立统一的抽象。二、项目初始化3分钟跑起来2.1 创建项目使用 Spring Initializrhttps://start.spring.io创建项目选择以下依赖Spring Boot 3.3.x最低要求3.2Spring WebSpring AI DashScope Starter通义千问或Spring AI OpenAI Starter如果你用Maven手动创建核心POM配置如下!-- 父POM锁定Spring Boot版本 -- parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.3.5/version relativePath/ /parent properties java.version17/java.version !-- Spring AI版本截至2024年底稳定版 -- spring-ai.version1.0.0-M4/spring-ai.version /properties dependencies !-- Spring Boot Web -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring AI BOM统一管理所有AI相关依赖版本 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency !-- 接入通义千问DashScope -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-starter/artifactId version1.0.0-M3.2/version /dependency !-- 或者接入DeepSeek兼容OpenAI协议 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency /dependencies !-- Spring AI的Milestone仓库必须加否则拉不到包 -- repositories repository idspring-milestones/id nameSpring Milestones/name urlhttps://repo.spring.io/milestone/url snapshotsenabledfalse/enabled/snapshots /repository /repositories2.2 配置API Key在application.yml中配置方式一接入通义千问DashScopespring: ai: dashscope: api-key: ${AI_DASHSCOPE_API_KEY} # 从环境变量读取别硬编码到代码里 chat: options: model: qwen-plus # 模型名称qwen-plus / qwen-turbo / qwen-max temperature: 0.7 # 温度0~1越高越发散方式二接入DeepSeek兼容OpenAI协议spring: ai: openai: api-key: ${AI_DEEPSEEK_API_KEY} base-url: https://api.deepseek.com # DeepSeek的API地址 chat: options: model: deepseek-chat # 或 deepseek-reasonerR1推理模型 temperature: 0.7为什么DeepSeek用OpenAI的starter因为DeepSeek的API完全兼容OpenAI协议只需要改base-url和api-key就行。这也是Spring AI统一抽象的威力——兼容OpenAI协议的模型统统用同一个starter。三、5行代码接入大模型ChatClient初体验3.1 最简版本RestController public class ChatController { private final ChatClient chatClient; // 构造器注入Spring AI自动配置已经帮你创建好了ChatClient.Builder public ChatController(ChatClient.Builder builder) { this.chatClient builder.build(); } GetMapping(/chat) public String chat(RequestParam String message) { return chatClient.prompt(message).call().content(); } }就这5行核心代码构造器注入 一行调用启动项目后访问http://localhost:8080/chat?message用一句话解释什么是依赖注入你会收到类似这样的回复依赖注入是一种设计模式对象不自己创建依赖项而是由外部容器将所需依赖注入进来从而实现松耦合。一个GET请求接入了大模型。这就是Spring AI的入门体验。3.2 理解调用链路别急着往下走我们先搞懂这行代码背后发生了什么chatClient.prompt(message) // 1. 构建Prompt .call() // 2. 发起同步HTTP请求到模型API .content(); // 3. 提取文本内容忽略token使用量等元数据完整链路是这样的你的代码 → ChatClient → ChatModel → 模型API通义千问/DeepSeek ↓ 返回 ChatResponse ↓ .content() 提取纯文本ChatClient是面向开发者的高级API类似Spring Data的RepositoryChatModel是底层模型接口。你日常开发90%的场景用ChatClient就够了。3.3 带系统提示词的对话实际业务中你通常需要设定AI的角色和行为规则。Spring AI用链式API优雅地处理这个GetMapping(/assistant) public String assistant(RequestParam String question) { return chatClient.prompt() // system消息设定AI角色和行为约束 .system(你是一个资深的Java技术顾问回答简洁专业 每次回答不超过200字代码示例用Java语言。) // user消息用户实际输入 .user(question) // 调用配置 .call() // 获取结构化结果包含内容、token用量等 .chatResponse() .getResult() .getOutput() .getContent(); }对比一下如果你自己拼接OpenAI的JSON请求体需要手动构造messages数组、区分system和user角色、解析返回的JSON……Spring AI把这些全封装了。3.4 多模型切换只改配置不改代码这是Spring AI最值钱的设计。你写好的ChatController代码切换模型只需要改配置# 开发环境用通义千问便宜 spring: ai: dashscope: api-key: ${AI_DASHSCOPE_API_KEY} chat: options: model: qwen-turbo # 生产环境切到DeepSeek性价比高 # spring: # ai: # openai: # api-key: ${AI_DEEPSEEK_API_KEY} # base-url: https://api.deepseek.com # chat: # options: # model: deepseek-chat当然如果你想在运行时动态切换模型比如简单问题用turbo、复杂问题用max可以通过注入多个ChatModel实现Service public class SmartChatService { private final ChatClient qwenClient; // 通义千问 private final ChatClient deepseekClient; // DeepSeek public SmartChatService( Qualifier(dashScopeChatModel) ChatModel qwenModel, Qualifier(openAiChatModel) ChatModel deepseekModel) { this.qwenClient ChatClient.builder(qwenModel).build(); this.deepseekClient ChatClient.builder(deepseekModel).build(); } public String chat(String question, String model) { ChatClient client deepseek.equalsIgnoreCase(model) ? deepseekClient : qwenClient; return client.prompt(question).call().content(); } }这种模型路由的思路在后面Day 89的综合项目里会详细展开这里先埋个种子。四、进阶结构化输出——让AI返回Java对象大模型默认返回的是自然语言文本但在工程中我们经常需要AI返回结构化数据比如JSON直接映射成Java对象。4.1 场景智能情感分析假设你有一个用户评论分析系统需要AI判断评论的情感倾向并返回结构化结果// 定义输出结构Java RecordJDK 16 public record SentimentResult( String sentiment, // POSITIVE / NEGATIVE / NEUTRAL double confidence, // 置信度 0~1 String summary // 一句话摘要 ) {} RestController public class SentimentController { private final ChatClient chatClient; public SentimentController(ChatClient.Builder builder) { this.chatClient builder.build(); } PostMapping(/analyze) public SentimentResult analyze(RequestBody MapString, String body) { String review body.get(review); return chatClient.prompt() .system(你是一个情感分析专家。分析用户评论的情感倾向 返回POSITIVE/NEGATIVE/NEUTRAL给出置信度和摘要。) .user(请分析以下评论\n review) .call() // 核心魔法entity()方法自动将AI输出转换为指定类型的Java对象 .entity(SentimentResult.class); } }调用示例curl -X POST http://localhost:8080/analyze \ -H Content-Type: application/json \ -d {review: 这个ERP系统太好用了库存管理清晰报表功能强大强烈推荐}返回结果{ sentiment: POSITIVE, confidence: 0.95, summary: 用户对ERP系统的库存管理和报表功能给予高度评价。 }原理entity()方法底层使用了BeanOutputConverter它做了三件事根据目标Java类型自动生成JSON Schema追加到Prompt中告诉模型输出格式调用模型获取文本响应将文本解析为JSON并反序列化为Java对象这意味着你不需要写任何JSON解析代码Spring AI帮你全搞定了。4.2 对比传统方案的痛点如果没有Spring AI你需要// 传统做法手动拼接 手动解析 String prompt 分析以下评论的情感返回JSON格式 {\sentiment\:\POSITIVE/NEGATIVE/NEUTRAL\, \confidence\:0.0,\summary\:\\}\n review; String response callLlmApi(prompt); // 自己封装HTTP调用 // 手动解析JSON还可能遇到模型不按格式返回的问题 ObjectMapper mapper new ObjectMapper(); SentimentResult result mapper.readValue(response, SentimentResult.class);痛点很明显Prompt和代码耦合、JSON格式不稳定、没有类型安全、换模型要改HTTP调用代码。Spring AI把这些问题全解决了。五、模型选型与成本对比很多开发者问我该选哪个模型我的建议是根据业务场景和预算来维度通义千问 (qwen-plus)DeepSeek (deepseek-chat)GPT-4o中文能力优秀优秀良好代码能力良好优秀性价比之王优秀输入价格¥0.008/1K tokens¥0.001/1K tokens¥0.035/1K tokens输出价格¥0.02/1K tokens¥0.002/1K tokens¥0.07/1K tokens免费额度有新用户有限时无上下文窗口128K128K128K合规性国内合规国内合规需评估价格数据为2024年底公开价格实际以官方为准。我的选型建议内部工具/原型验证DeepSeek便宜到几乎不花钱面向用户的中文场景通义千问中文表达自然复杂代码推理DeepSeek-R1推理模型或GPT-4o数据敏感场景后面Day 61会讲Ollama本地部署六、建议建议1API Key永远不要硬编码// ❌ 错误硬编码到代码里一旦提交到Git就完蛋 Value(${spring.ai.dashscope.api-key}) private String apiKey sk-xxxxxxx; // ✅ 正确用环境变量注入 // application.yml中写 ${AI_DASHSCOPE_API_KEY} // 启动时export AI_DASHSCOPE_API_KEYsk-xxxxxxx更进一步生产环境用Nacos配置中心或Vault管理密钥不要放在代码仓库里。建议2永远设置超时和重试大模型API的延迟远高于传统接口通常2~10秒不设超时会拖垮你的线程池yaml复制spring: ai: dashscope: chat: options: model: qwen-plus # Spring AI的retry配置M4版本支持 retry: max-attempts: 3 # 最多重试3次 backoff: initial-interval: 1000 # 首次重试等待1秒 multiplier: 2 # 指数退避1s → 2s → 4s同时你的HTTP客户端Tomcat/Undertow也要确保超时时间大于模型的最大响应时间server: tomcat: connection-timeout: 30000 # 30秒超时 threads: max: 200 # 根据并发量调整建议3从简单场景开始不要一上来就RAG我见过太多团队一上来就搞RAG知识库结果文档切分、向量检索、重排序一堆问题项目延期两个月。正确的节奏是第一步ChatClient跑通基础对话今天这篇 ↓ 第二步Prompt工程让AI按你的规则输出Day 27 ↓ 第三步结构化输出 Function Calling让AI调你的业务接口 ↓ 第四步RAG给AI喂你的私有知识Day 71每一步都要确保上一步能稳定运行。AI应用开发的坑不在框架而在调优和边界处理。下篇预告Day 27 —— 《Spring AI Prompt工程PromptTemplate/FewShot/角色系统》我们将深入Prompt模板化管理把调教AI这件事工程化、可版本管理地做起来。