理论基础什么是 Spring AISpring AI是 Spring 官方推出的 AI 应用开发框架旨在简化大语言模型LLM应用的开发流程。它提供了统一的抽象层让开发者可以用一致的方式与不同的 AI 模型交互。为什么需要 Spring AI问题传统方式Spring AI 方案多模型适配每个模型写一套代码统一 API切换配置即可集成复杂度手动处理 HTTP、认证、重试开箱即用自动处理生态整合自己实现缓存、监控与 Spring 生态无缝集成核心概念ChatClient高级抽象简化对话调用ChatModel底层模型接口支持更多定制Prompt发送给 AI 的指令包含系统消息、用户消息ResponseAI 的回复支持流式和非流式架构图你的代码 → ChatClient → ChatModel → AI 提供商 API ↑ (统一抽象层)1.1 Spring AI 介绍Spring AI 是一个基于 Spring Framework 的 AI 应用开发框架提供了与各种大语言模型LLM交互的标准化 API。主要特性✅ 统一的 ChatClient API✅ 支持多种 AI 模型通义千问、文心一言、Kimi、DeepSeek 等✅ 流式响应支持✅ 函数调用能力✅ RAG 检索增强生成1.2 环境要求必需环境环境版本说明JDK17Java Development KitMaven3.8项目构建工具Spring Boot3.x应用框架Spring AI1.xAI 集成框架1.3 项目创建Maven 依赖propertiesjava.version25/java.versionspring-ai.version1.0.0-M6/spring-ai.version/propertiesdependencies!-- Spring Boot Web --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency!-- Spring AI OpenAI (兼容阿里百炼) --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-openai-spring-boot-starter/artifactIdversion${spring-ai.version}/version/dependency/dependencies配置文件spring:ai:api-key:${AI_API_KEY}model:qwen3.5-plus# 默认使用通义千问 3.5 Plus1.4 第一个 AI 对话示例Controller 代码/** * author Joe.Ye * blog https://www.appblog.cn */RestControllerRequestMapping(/api/ai)publicclassDemoController{privatestaticfinalLoggerlogLoggerFactory.getLogger(DemoController.class);privatefinalChatClientchatClient;publicDemoController(ChatClientchatClient){this.chatClientchatClient;}/** * AI 对话接口 * POST /api/ai/demo * Body: {message: 你好} */PostMapping(/demo)publicChatResponsechat(RequestBodyChatRequestrequest){log.info(收到 AI 请求{},request.getMessage());StringresponsechatClient.prompt().user(request.getMessage()).call().content();log.info(AI 响应{},response);returnnewChatResponse(response,qwen3.5-plus,Instant.now().toEpochMilli());}/** * 健康检查 */GetMapping(/health)publicStringhealth(){returnAI Service is running!;}}1.5 API 接口Controller1 个Controller路径接口数功能DemoController/api/demo1基础对话接口接口列表接口方法说明/api/demoPOST基础对话1.6 接口测试真实数据 - qwen3.5-plus测试 1基础对话接口POST接口POST /api/demo请求命令curl-XPOST http://localhost:8080/api/demo\-HContent-Type: application/json\-d{message:你好请介绍一下自己}请求参数{message:你好请介绍一下自己}请求参数说明参数类型必填说明messagestring是用户输入的消息真实返回结果{message:你好 我是通义千问Qwen阿里巴巴集团旗下的超大规模语言模型。我能够理解并生成多种语言的文本比如中文、英文、法语、西班牙语、葡萄牙语、俄语、阿拉伯语、日语、韩语、越南语、泰语、印尼语等支持跨语言交流与创作。\n\n我可以帮助你\n✅ 回答各类问题知识性、逻辑性、生活常识、学术概念等 \n✅ 创作文字写故事、公文、邮件、剧本、诗歌、歌词等 \n✅ 编程辅助解释代码、调试建议、多语言代码生成 \n✅ 逻辑推理与数学计算 \n✅ 多轮对话与上下文理解记得我们之前的交流内容让对话更自然连贯 \n✅ 表达观点、总结提炼、润色改写、翻译等\n\n我注重准确性、安全性和实用性也会坦诚说明自己的能力边界——比如不实时联网除非你开启“联网搜索”功能、不掌握2024年10月之后的事件、不处理个人隐私或敏感信息。\n\n很高兴认识你 如果你有任何问题、想法或者只是想聊聊随时欢迎告诉我 你想从哪里开始呢,model:qwen3.5-plus,timestamp:1774171001390}返回参数说明参数类型说明messagestring用户输入的消息timestamplong响应时间戳modelstring使用的 AI 模型1.7 VSCode配置VSCode运行环境基本配置.vscode//setting.json{ // 项目默认使用的JDK版本 java.configuration.runtimes: [ { name: JavaSE-1.8, path: C:/Program Files/Java/jdk1.8.0_333 }, { name: JavaSE-25, path: D:/soft/jdk-25.0.2, default: true // 设为项目默认 } ], // 配置Windows终端默认使用UTF-8编码 terminal.integrated.profiles.windows: { PowerShell: { source: PowerShell, args: [-NoExit, /c, chcp 65001] } }, // 默认用PowerShell终端 terminal.integrated.defaultProfile.windows: PowerShell, // Maven执行文件路径 maven.executable.path: D:/soft/apache-maven-3.8.9, // Maven settings.xml配置文件路径 maven.settingsFile: D:/soft/apache-maven-3.8.9/conf/settings.xml, java.configuration.updateBuildConfiguration: interactive, // 可选本地仓库路径默认在用户目录.m2/repository可自定义 //maven.localRepository: }1.8 常见问题Q1: 如何配置 API Key答在application.yml中配置spring:ai:openai:api-key:sk-your-api-key或使用环境变量exportSPRING_AI_OPENAI_API_KEYsk-your-api-keyQ2: API 调用返回 404 错误 ⭐⭐⭐⭐⭐现象curl-XPOST http://localhost:8080/api/ai/demo\-d{message: 你好}# 返回{status:500,message:404 - }原因Spring AI 1.0.0-M6 的OpenAiApi类硬编码了 API 路径会在base-url后面自动拼接/v1/chat/completions。如果配置的base-url已经包含了/v1会导致 URL 重复# ❌ 错误配置spring:ai:openai:base-url:https://dashscope.aliyuncs.com/compatible-mode/v1# ^^ 这里有/v1# Spring AI 内部拼接# base-url /v1/chat/completions# https://dashscope.aliyuncs.com/compatible-mode/v1/v1/chat/completions# ^^^ 重复→ 404解决方案base-url不要包含/v1Spring AI 会自动添加# ✅ 正确配置spring:ai:openai:api-key:sk-your-api-keybase-url:https://dashscope.aliyuncs.com/compatible-mode# 注意不要加 /v1Spring AI 会自动拼接 /v1/chat/completionschat:options:model:qwen3.5-plustemperature:0.7Q3: JSON 请求需要class参数 ⭐⭐⭐⭐现象curl-XPOST http://localhost:8080/api/ai/demo\-d{message: 你好}# 返回{status:400,message:missing type id property class}原因RedisConfig.java中配置了全局ObjectMapper并启用了activateDefaultTyping导致所有 JSON 反序列化都需要类型信息。解决方案添加WebConfig.java配置专门用于 HTTP 请求的 ObjectMapperConfigurationpublicclassWebConfig{BeanPrimarypublicObjectMapperobjectMapper(){returnJackson2ObjectMapperBuilder.json().featuresToDisable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES).build();}}Q5: 如何切换模型答修改application.yml中的model配置
Spring-AI 第 01 章 - 开发快速入门
理论基础什么是 Spring AISpring AI是 Spring 官方推出的 AI 应用开发框架旨在简化大语言模型LLM应用的开发流程。它提供了统一的抽象层让开发者可以用一致的方式与不同的 AI 模型交互。为什么需要 Spring AI问题传统方式Spring AI 方案多模型适配每个模型写一套代码统一 API切换配置即可集成复杂度手动处理 HTTP、认证、重试开箱即用自动处理生态整合自己实现缓存、监控与 Spring 生态无缝集成核心概念ChatClient高级抽象简化对话调用ChatModel底层模型接口支持更多定制Prompt发送给 AI 的指令包含系统消息、用户消息ResponseAI 的回复支持流式和非流式架构图你的代码 → ChatClient → ChatModel → AI 提供商 API ↑ (统一抽象层)1.1 Spring AI 介绍Spring AI 是一个基于 Spring Framework 的 AI 应用开发框架提供了与各种大语言模型LLM交互的标准化 API。主要特性✅ 统一的 ChatClient API✅ 支持多种 AI 模型通义千问、文心一言、Kimi、DeepSeek 等✅ 流式响应支持✅ 函数调用能力✅ RAG 检索增强生成1.2 环境要求必需环境环境版本说明JDK17Java Development KitMaven3.8项目构建工具Spring Boot3.x应用框架Spring AI1.xAI 集成框架1.3 项目创建Maven 依赖propertiesjava.version25/java.versionspring-ai.version1.0.0-M6/spring-ai.version/propertiesdependencies!-- Spring Boot Web --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-web/artifactId/dependency!-- Spring AI OpenAI (兼容阿里百炼) --dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-openai-spring-boot-starter/artifactIdversion${spring-ai.version}/version/dependency/dependencies配置文件spring:ai:api-key:${AI_API_KEY}model:qwen3.5-plus# 默认使用通义千问 3.5 Plus1.4 第一个 AI 对话示例Controller 代码/** * author Joe.Ye * blog https://www.appblog.cn */RestControllerRequestMapping(/api/ai)publicclassDemoController{privatestaticfinalLoggerlogLoggerFactory.getLogger(DemoController.class);privatefinalChatClientchatClient;publicDemoController(ChatClientchatClient){this.chatClientchatClient;}/** * AI 对话接口 * POST /api/ai/demo * Body: {message: 你好} */PostMapping(/demo)publicChatResponsechat(RequestBodyChatRequestrequest){log.info(收到 AI 请求{},request.getMessage());StringresponsechatClient.prompt().user(request.getMessage()).call().content();log.info(AI 响应{},response);returnnewChatResponse(response,qwen3.5-plus,Instant.now().toEpochMilli());}/** * 健康检查 */GetMapping(/health)publicStringhealth(){returnAI Service is running!;}}1.5 API 接口Controller1 个Controller路径接口数功能DemoController/api/demo1基础对话接口接口列表接口方法说明/api/demoPOST基础对话1.6 接口测试真实数据 - qwen3.5-plus测试 1基础对话接口POST接口POST /api/demo请求命令curl-XPOST http://localhost:8080/api/demo\-HContent-Type: application/json\-d{message:你好请介绍一下自己}请求参数{message:你好请介绍一下自己}请求参数说明参数类型必填说明messagestring是用户输入的消息真实返回结果{message:你好 我是通义千问Qwen阿里巴巴集团旗下的超大规模语言模型。我能够理解并生成多种语言的文本比如中文、英文、法语、西班牙语、葡萄牙语、俄语、阿拉伯语、日语、韩语、越南语、泰语、印尼语等支持跨语言交流与创作。\n\n我可以帮助你\n✅ 回答各类问题知识性、逻辑性、生活常识、学术概念等 \n✅ 创作文字写故事、公文、邮件、剧本、诗歌、歌词等 \n✅ 编程辅助解释代码、调试建议、多语言代码生成 \n✅ 逻辑推理与数学计算 \n✅ 多轮对话与上下文理解记得我们之前的交流内容让对话更自然连贯 \n✅ 表达观点、总结提炼、润色改写、翻译等\n\n我注重准确性、安全性和实用性也会坦诚说明自己的能力边界——比如不实时联网除非你开启“联网搜索”功能、不掌握2024年10月之后的事件、不处理个人隐私或敏感信息。\n\n很高兴认识你 如果你有任何问题、想法或者只是想聊聊随时欢迎告诉我 你想从哪里开始呢,model:qwen3.5-plus,timestamp:1774171001390}返回参数说明参数类型说明messagestring用户输入的消息timestamplong响应时间戳modelstring使用的 AI 模型1.7 VSCode配置VSCode运行环境基本配置.vscode//setting.json{ // 项目默认使用的JDK版本 java.configuration.runtimes: [ { name: JavaSE-1.8, path: C:/Program Files/Java/jdk1.8.0_333 }, { name: JavaSE-25, path: D:/soft/jdk-25.0.2, default: true // 设为项目默认 } ], // 配置Windows终端默认使用UTF-8编码 terminal.integrated.profiles.windows: { PowerShell: { source: PowerShell, args: [-NoExit, /c, chcp 65001] } }, // 默认用PowerShell终端 terminal.integrated.defaultProfile.windows: PowerShell, // Maven执行文件路径 maven.executable.path: D:/soft/apache-maven-3.8.9, // Maven settings.xml配置文件路径 maven.settingsFile: D:/soft/apache-maven-3.8.9/conf/settings.xml, java.configuration.updateBuildConfiguration: interactive, // 可选本地仓库路径默认在用户目录.m2/repository可自定义 //maven.localRepository: }1.8 常见问题Q1: 如何配置 API Key答在application.yml中配置spring:ai:openai:api-key:sk-your-api-key或使用环境变量exportSPRING_AI_OPENAI_API_KEYsk-your-api-keyQ2: API 调用返回 404 错误 ⭐⭐⭐⭐⭐现象curl-XPOST http://localhost:8080/api/ai/demo\-d{message: 你好}# 返回{status:500,message:404 - }原因Spring AI 1.0.0-M6 的OpenAiApi类硬编码了 API 路径会在base-url后面自动拼接/v1/chat/completions。如果配置的base-url已经包含了/v1会导致 URL 重复# ❌ 错误配置spring:ai:openai:base-url:https://dashscope.aliyuncs.com/compatible-mode/v1# ^^ 这里有/v1# Spring AI 内部拼接# base-url /v1/chat/completions# https://dashscope.aliyuncs.com/compatible-mode/v1/v1/chat/completions# ^^^ 重复→ 404解决方案base-url不要包含/v1Spring AI 会自动添加# ✅ 正确配置spring:ai:openai:api-key:sk-your-api-keybase-url:https://dashscope.aliyuncs.com/compatible-mode# 注意不要加 /v1Spring AI 会自动拼接 /v1/chat/completionschat:options:model:qwen3.5-plustemperature:0.7Q3: JSON 请求需要class参数 ⭐⭐⭐⭐现象curl-XPOST http://localhost:8080/api/ai/demo\-d{message: 你好}# 返回{status:400,message:missing type id property class}原因RedisConfig.java中配置了全局ObjectMapper并启用了activateDefaultTyping导致所有 JSON 反序列化都需要类型信息。解决方案添加WebConfig.java配置专门用于 HTTP 请求的 ObjectMapperConfigurationpublicclassWebConfig{BeanPrimarypublicObjectMapperobjectMapper(){returnJackson2ObjectMapperBuilder.json().featuresToDisable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES).build();}}Q5: 如何切换模型答修改application.yml中的model配置
