系列说明本文是《Spring AI 实战系列》第 1 篇面向 Java 开发者从零开始掌握 Spring AI。前置知识熟悉 Spring Boot、了解基本 AI 概念即可。前言说实话我第一次听说 Spring AI 的时候内心是有点抗拒的。作为一个写了多年 Java 的老码农AI 这块一直给我一种「Python 专属」的刻板印象。LangChain、LlamaIndex 这些框架确实香但让我为了做 AI 项目切到 Python 生态那是不可能的。直到 2024 年 Spring AI 正式发布我才发现原来 Java 开发者也能这么优雅地玩大模型。这篇文章我会把 Spring AI 是什么、为什么要用它、以及怎么快速上手给你讲清楚。一、Spring AI 到底是什么1.1 诞生背景2023 年 ChatGPT 爆火之后整个技术圈都在讨论怎么把大模型能力集成到业务系统里。Python 生态反应最快LangChain、LlamaIndex 这些框架迅速崛起。Java 这边呢大多数团队只能手写 HTTP 客户端去调 OpenAI 的 API代码又臭又长换个模型提供商就得重写一堆逻辑。Spring 团队看不下去了。2024 年Spring AI 正式诞生。定位很明确让 Java 开发者用 Spring 的方式做 AI 应用。1.2 核心定位Spring AI 不是 LangChain 的 Java 移植版。它是为 Spring 生态量身打造的 AI 框架核心就三件事。可移植的抽象层一套 API 对接 OpenAI、Anthropic、DeepSeek、Ollama 等 N 个模型提供商切换只需改配置。Spring 原生体验自动配置、Starter 依赖、依赖注入完全遵循 Spring 的设计哲学。企业级能力RAG、Tool Calling、对话记忆、可观测性生产环境需要的它都有。1.3 与 LangChain/LangChain4j 的对比很多人问我Spring AI 和 LangChain4j 有什么区别我用哪个我的建议是如果你的项目已经是 Spring Boot 生态直接上 Spring AI无缝集成学习成本最低。如果你需要更灵活的编排能力LangChain4j 的 Chain 概念更丰富可以作为补充。如果你是从 Python 迁移过来Spring AI 的 API 设计更贴近 Spring 开发者习惯。实际项目中两者甚至可以混用并不冲突。二、Spring AI 解决了什么问题2.1 供应商锁定问题假设你一开始用的 OpenAI代码里到处都是OpenAiApi的调用。后来公司要求换国产模型比如通义千问或者 DeepSeek你怎么办重写所有调用逻辑Spring AI 的做法是提供统一抽象// 不管是什么模型都是 ChatClientChatClientchatClientChatClient.builder(chatModel).build();StringresponsechatClient.prompt().user(讲一个关于程序员的笑话).call().content();换模型改个配置就行# OpenAIspring:ai:openai:api-key:${OPENAI_API_KEY}# 换成 DeepSeekspring:ai:openai:api-key:${DEEPSEEK_API_KEY}base-url:https://api.deepseek.com代码一行不用改。2.2 复杂的 Prompt 管理直接拼字符串写 Prompt那是初学者做法。Spring AI 提供了PromptTemplate支持占位符和动态填充PromptTemplatepromptTemplatenewPromptTemplate( 你是一位{role}请用{style}的风格回答以下问题 {question} );PromptpromptpromptTemplate.create(Map.of(role,Java 技术专家,style,通俗易懂,question,什么是 Spring AI));配合 Spring 的 ResourceLoader还能把 Prompt 模板放到外部文件里管理方便团队协作和版本控制。2.3 企业级 AI 应用的刚需做 Demo 很简单但上生产环境就麻烦了。怎么让 AI 回答基于企业私有数据RAG检索增强生成。怎么让 AI 调用业务系统的 APITool Calling。怎么记住用户的对话上下文ChatMemory。怎么监控 AI 的调用成本和响应质量可观测性。这些 Spring AI 都内置了不用自己造轮子。三、核心概念速览在写代码之前先搞清楚几个核心概念。3.1 Model模型AI 模型是处理信息并生成输出的算法。Spring AI 目前支持三类模型Chat Model比如 GPT-4、Claude、DeepSeek用于文本对话Embedding Model比如 text-embedding-3-small用于文本向量化Image Model比如 DALL-E、Stable Diffusion用于图像生成3.2 Prompt提示词Prompt 是指导 AI 模型生成特定输出的输入文本。Spring AI 的 Prompt 不是简单的字符串它包含多个 Message每个 Message 都有角色System Message设定 AI 的行为和背景User Message用户的输入Assistant MessageAI 的回复用于多轮对话PromptpromptnewPrompt(List.of(newSystemMessage(你是一位幽默的 Java 技术专家),newUserMessage(什么是 Spring AI)));3.3 Embedding嵌入Embedding 是把文本转换成向量的技术。这些向量可以表示文本的语义信息用于语义搜索、文本相似度计算、RAG 中的文档检索。ListDoubleembeddingembeddingModel.embed(Spring AI 很强大);// 返回一个 1536 维的向量取决于模型3.4 TokenToken 是模型处理文本的基本单位。理解 Token 很重要因为它直接关系到调用成本按 Token 数量计费、上下文窗口模型一次能处理的最大 Token 数、性能Token 越多响应越慢。Spring AI 提供了 Token 计数工具方便你做成本控制和性能优化。四、快速上手第一个 Spring AI 项目4.1 环境准备JDK 17Spring AI 1.0 要求Maven 或 GradleIDEA推荐AI 模型的 API KeyOpenAI、DeepSeek、智谱等均可4.2 创建项目用 Spring Initializrhttps://start.spring.io创建项目ProjectMavenLanguageJavaSpring Boot3.2.x 或更高Dependencies添加Spring AI如果可选列表里没有手动加依赖4.3 添加依赖dependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion1.0.0-M5/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagementdependencies!-- Spring Boot Starter --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也是spring-ai-openai-spring-boot-starter因为 DeepSeek 兼容 OpenAI 的 API 格式。4.4 配置 API Keyspring:ai:openai:api-key:${OPENAI_API_KEY}# 如果用 DeepSeek加上 base-url# base-url: https://api.deepseek.comchat:options:model:gpt-4otemperature:0.74.5 编写第一个 ControllerRestControllerRequestMapping(/ai)publicclassChatController{privatefinalChatClientchatClient;publicChatController(ChatClient.BuilderchatClientBuilder){this.chatClientchatClientBuilder.build();}GetMapping(/chat)publicStringchat(RequestParamStringmessage){returnchatClient.prompt().user(message).call().content();}}启动项目访问GET http://localhost:8080/ai/chat?message你好Spring AI如果看到 AI 的回复恭喜你第一个 Spring AI 项目跑通了4.6 流式输出上面的例子是同步调用等 AI 全部生成完才返回。如果回复很长用户体验会很差。Spring AI 支持流式输出GetMapping(value/chat/stream,producesMediaType.TEXT_EVENT_STREAM_VALUE)publicFluxStringchatStream(RequestParamStringmessage){returnchatClient.prompt().user(message).stream().content();}前端用 EventSource 接收就能实现打字机效果了。五、版本说明与选型建议5.1 当前版本状态截至 2025 年Spring AI 的版本情况1.0.0-M5Milestone 版本功能基本稳定API 可能微调1.1.xGA 正式发布新增 Agent 框架、MCP 支持生产环境建议用1.1.x GA版本。5.2 本系列使用的版本本系列文章基于Spring AI 1.0.0部分高级特性如 Agent、MCP需要1.1.x。我会在涉及新特性的地方特别标注版本要求。写在最后这篇文章是系列的开篇主要是让你对 Spring AI 有个整体认知并跑通第一个项目。下一篇我会深入讲解ChatClient 的完整用法包括多模型切换、Prompt 模板、以及各种配置选项的实战技巧。如果你已经迫不及待想继续深入可以先去 Spring AI 官方文档 逛逛但相信我跟着这个系列走你会少走很多弯路。系列目录第 1 篇Spring AI 概述与快速上手 ✅本文第 2 篇ChatClient 详解与多模型集成第 3 篇结构化输出与多模态第 4 篇Embedding 与向量数据库第 5 篇RAG 检索增强生成第 6 篇Tool Calling 工具调用第 7 篇Advisor 机制与对话管理第 8 篇MCP 模型上下文协议第 9 篇AI Agent 开发实战第 10 篇企业级应用与最佳实践如果这篇文章对你有帮助欢迎点赞收藏关注系列持续更新中
Spring AI 实战系列 | 第 1 篇：Spring AI 概述与快速上手
发布时间：2026/6/5 22:12:42
系列说明本文是《Spring AI 实战系列》第 1 篇面向 Java 开发者从零开始掌握 Spring AI。前置知识熟悉 Spring Boot、了解基本 AI 概念即可。前言说实话我第一次听说 Spring AI 的时候内心是有点抗拒的。作为一个写了多年 Java 的老码农AI 这块一直给我一种「Python 专属」的刻板印象。LangChain、LlamaIndex 这些框架确实香但让我为了做 AI 项目切到 Python 生态那是不可能的。直到 2024 年 Spring AI 正式发布我才发现原来 Java 开发者也能这么优雅地玩大模型。这篇文章我会把 Spring AI 是什么、为什么要用它、以及怎么快速上手给你讲清楚。一、Spring AI 到底是什么1.1 诞生背景2023 年 ChatGPT 爆火之后整个技术圈都在讨论怎么把大模型能力集成到业务系统里。Python 生态反应最快LangChain、LlamaIndex 这些框架迅速崛起。Java 这边呢大多数团队只能手写 HTTP 客户端去调 OpenAI 的 API代码又臭又长换个模型提供商就得重写一堆逻辑。Spring 团队看不下去了。2024 年Spring AI 正式诞生。定位很明确让 Java 开发者用 Spring 的方式做 AI 应用。1.2 核心定位Spring AI 不是 LangChain 的 Java 移植版。它是为 Spring 生态量身打造的 AI 框架核心就三件事。可移植的抽象层一套 API 对接 OpenAI、Anthropic、DeepSeek、Ollama 等 N 个模型提供商切换只需改配置。Spring 原生体验自动配置、Starter 依赖、依赖注入完全遵循 Spring 的设计哲学。企业级能力RAG、Tool Calling、对话记忆、可观测性生产环境需要的它都有。1.3 与 LangChain/LangChain4j 的对比很多人问我Spring AI 和 LangChain4j 有什么区别我用哪个我的建议是如果你的项目已经是 Spring Boot 生态直接上 Spring AI无缝集成学习成本最低。如果你需要更灵活的编排能力LangChain4j 的 Chain 概念更丰富可以作为补充。如果你是从 Python 迁移过来Spring AI 的 API 设计更贴近 Spring 开发者习惯。实际项目中两者甚至可以混用并不冲突。二、Spring AI 解决了什么问题2.1 供应商锁定问题假设你一开始用的 OpenAI代码里到处都是OpenAiApi的调用。后来公司要求换国产模型比如通义千问或者 DeepSeek你怎么办重写所有调用逻辑Spring AI 的做法是提供统一抽象// 不管是什么模型都是 ChatClientChatClientchatClientChatClient.builder(chatModel).build();StringresponsechatClient.prompt().user(讲一个关于程序员的笑话).call().content();换模型改个配置就行# OpenAIspring:ai:openai:api-key:${OPENAI_API_KEY}# 换成 DeepSeekspring:ai:openai:api-key:${DEEPSEEK_API_KEY}base-url:https://api.deepseek.com代码一行不用改。2.2 复杂的 Prompt 管理直接拼字符串写 Prompt那是初学者做法。Spring AI 提供了PromptTemplate支持占位符和动态填充PromptTemplatepromptTemplatenewPromptTemplate( 你是一位{role}请用{style}的风格回答以下问题 {question} );PromptpromptpromptTemplate.create(Map.of(role,Java 技术专家,style,通俗易懂,question,什么是 Spring AI));配合 Spring 的 ResourceLoader还能把 Prompt 模板放到外部文件里管理方便团队协作和版本控制。2.3 企业级 AI 应用的刚需做 Demo 很简单但上生产环境就麻烦了。怎么让 AI 回答基于企业私有数据RAG检索增强生成。怎么让 AI 调用业务系统的 APITool Calling。怎么记住用户的对话上下文ChatMemory。怎么监控 AI 的调用成本和响应质量可观测性。这些 Spring AI 都内置了不用自己造轮子。三、核心概念速览在写代码之前先搞清楚几个核心概念。3.1 Model模型AI 模型是处理信息并生成输出的算法。Spring AI 目前支持三类模型Chat Model比如 GPT-4、Claude、DeepSeek用于文本对话Embedding Model比如 text-embedding-3-small用于文本向量化Image Model比如 DALL-E、Stable Diffusion用于图像生成3.2 Prompt提示词Prompt 是指导 AI 模型生成特定输出的输入文本。Spring AI 的 Prompt 不是简单的字符串它包含多个 Message每个 Message 都有角色System Message设定 AI 的行为和背景User Message用户的输入Assistant MessageAI 的回复用于多轮对话PromptpromptnewPrompt(List.of(newSystemMessage(你是一位幽默的 Java 技术专家),newUserMessage(什么是 Spring AI)));3.3 Embedding嵌入Embedding 是把文本转换成向量的技术。这些向量可以表示文本的语义信息用于语义搜索、文本相似度计算、RAG 中的文档检索。ListDoubleembeddingembeddingModel.embed(Spring AI 很强大);// 返回一个 1536 维的向量取决于模型3.4 TokenToken 是模型处理文本的基本单位。理解 Token 很重要因为它直接关系到调用成本按 Token 数量计费、上下文窗口模型一次能处理的最大 Token 数、性能Token 越多响应越慢。Spring AI 提供了 Token 计数工具方便你做成本控制和性能优化。四、快速上手第一个 Spring AI 项目4.1 环境准备JDK 17Spring AI 1.0 要求Maven 或 GradleIDEA推荐AI 模型的 API KeyOpenAI、DeepSeek、智谱等均可4.2 创建项目用 Spring Initializrhttps://start.spring.io创建项目ProjectMavenLanguageJavaSpring Boot3.2.x 或更高Dependencies添加Spring AI如果可选列表里没有手动加依赖4.3 添加依赖dependencyManagementdependenciesdependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-bom/artifactIdversion1.0.0-M5/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagementdependencies!-- Spring Boot Starter --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也是spring-ai-openai-spring-boot-starter因为 DeepSeek 兼容 OpenAI 的 API 格式。4.4 配置 API Keyspring:ai:openai:api-key:${OPENAI_API_KEY}# 如果用 DeepSeek加上 base-url# base-url: https://api.deepseek.comchat:options:model:gpt-4otemperature:0.74.5 编写第一个 ControllerRestControllerRequestMapping(/ai)publicclassChatController{privatefinalChatClientchatClient;publicChatController(ChatClient.BuilderchatClientBuilder){this.chatClientchatClientBuilder.build();}GetMapping(/chat)publicStringchat(RequestParamStringmessage){returnchatClient.prompt().user(message).call().content();}}启动项目访问GET http://localhost:8080/ai/chat?message你好Spring AI如果看到 AI 的回复恭喜你第一个 Spring AI 项目跑通了4.6 流式输出上面的例子是同步调用等 AI 全部生成完才返回。如果回复很长用户体验会很差。Spring AI 支持流式输出GetMapping(value/chat/stream,producesMediaType.TEXT_EVENT_STREAM_VALUE)publicFluxStringchatStream(RequestParamStringmessage){returnchatClient.prompt().user(message).stream().content();}前端用 EventSource 接收就能实现打字机效果了。五、版本说明与选型建议5.1 当前版本状态截至 2025 年Spring AI 的版本情况1.0.0-M5Milestone 版本功能基本稳定API 可能微调1.1.xGA 正式发布新增 Agent 框架、MCP 支持生产环境建议用1.1.x GA版本。5.2 本系列使用的版本本系列文章基于Spring AI 1.0.0部分高级特性如 Agent、MCP需要1.1.x。我会在涉及新特性的地方特别标注版本要求。写在最后这篇文章是系列的开篇主要是让你对 Spring AI 有个整体认知并跑通第一个项目。下一篇我会深入讲解ChatClient 的完整用法包括多模型切换、Prompt 模板、以及各种配置选项的实战技巧。如果你已经迫不及待想继续深入可以先去 Spring AI 官方文档 逛逛但相信我跟着这个系列走你会少走很多弯路。系列目录第 1 篇Spring AI 概述与快速上手 ✅本文第 2 篇ChatClient 详解与多模型集成第 3 篇结构化输出与多模态第 4 篇Embedding 与向量数据库第 5 篇RAG 检索增强生成第 6 篇Tool Calling 工具调用第 7 篇Advisor 机制与对话管理第 8 篇MCP 模型上下文协议第 9 篇AI Agent 开发实战第 10 篇企业级应用与最佳实践如果这篇文章对你有帮助欢迎点赞收藏关注系列持续更新中
