Spring AI 从概念到实践：统一抽象、RAG与Agent开发指南

1. 从“玩具”到“生产力”：Spring AI 的定位与价值重估

最近和几个做后端开发的朋友聊天，发现一个挺有意思的现象：半年前大家提起 Spring AI，还觉得它是个“玩具”，是 Spring 生态为了追 AI 热点搞出来的一个实验性项目，离真正的生产落地还很远。但最近几个月，风向明显变了。无论是阿里云推出的 Spring AI Alibaba 套件，还是 Spring AI 2.0 版本带来的新特性，都让这个框架开始显露出“生产力工具”的雏形。我自己在几个内部工具和边缘业务场景里试水之后，感觉它确实不再是那个只能简单调用 OpenAI API 的封装壳了。今天，我就以一个一线开发者的视角，来聊聊 Spring AI 到底能干什么，它的核心设计思想是什么，以及在实际项目中，我们该如何避开那些“看起来很美”的坑，真正把它用起来。

简单来说，Spring AI 的野心，是成为 Java/Spring 开发者进入 AI 应用世界的“官方入口”和“基础设施”。它试图把调用大语言模型（LLM）、处理向量数据、构建 AI Agent 这些复杂且碎片化的操作，抽象成一套符合 Spring 开发者直觉的、声明式的编程模型。你不用再自己去处理 HTTP 客户端、JSON 解析、错误重试、流式响应这些底层细节，而是像使用JdbcTemplate操作数据库，或者用RestTemplate调用 REST 服务一样，通过几个注解和模板类，就能完成与 AI 模型的交互。这对于那些业务逻辑复杂，但 AI 需求相对标准化（比如智能客服、内容生成、代码辅助）的 Spring 应用来说，能极大地降低集成门槛和心智负担。

2. Spring AI 的核心抽象：为什么说它“很 Spring”

Spring 框架的成功，很大程度上得益于它强大的抽象能力。Spring AI 继承了这一基因，它的核心抽象非常清晰，理解这些抽象是高效使用它的前提。

2.1ChatClient与PromptTemplate：对话的基石

最核心的抽象莫过于ChatClient。你可以把它理解为 AI 世界的RestTemplate。无论底层对接的是 OpenAI 的 GPT、Anthropic 的 Claude，还是阿里云的通义千问，在应用代码层面，你面对的都是同一个ChatClient接口。

// 一个典型的调用示例 @Autowired private ChatClient chatClient; public String generateSummary(String text) { Prompt prompt = new Prompt(new UserMessage("请为以下文本生成一段摘要：\n" + text)); ChatResponse response = chatClient.call(prompt); return response.getResult().getOutput().getContent(); }

这段代码是不是非常“Spring”？通过依赖注入拿到ChatClient，构造一个包含用户消息的Prompt对象，然后调用call方法。至于这个请求最终是发往哪个云厂商、用了哪个模型、认证信息是什么，这些配置层面的东西，完全可以通过application.yml来管理，实现了业务代码与基础设施的解耦。

但直接拼接字符串构造提示词（Prompt）是笨拙且容易出错的。这时就需要PromptTemplate。它就像是 MyBatis 里的 SQL 模板，支持占位符和简单的逻辑。

// 定义模板 PromptTemplate promptTemplate = new PromptTemplate(""" 你是一位专业的翻译专家。请将以下{inputLanguage}的文本翻译成{outputLanguage}，并保持原文的专业语气和风格： 文本：{text} """); // 填充变量并创建 Prompt Map<String, Object> model = new HashMap<>(); model.put("inputLanguage", "中文"); model.put("outputLanguage", "英文"); model.put("text", "Spring AI 提供了统一的抽象层。"); Prompt prompt = promptTemplate.create(model);

这种方式不仅更安全（避免提示词注入），也更易于维护和复用。在实际项目中，我建议将复杂的、需要反复使用的 Prompt 模板定义在配置文件或数据库中，而不是硬编码在 Java 类里。

2.2VectorStore：让 AI 理解你的私有数据

大模型有个通病：它们知识广博，但对你的私有数据一无所知。比如，你想让 AI 帮你分析公司内部的季度销售报告，直接问 GPT 是没用的。解决这个问题的关键技术叫做“检索增强生成”（RAG），而 RAG 的核心就是向量数据库。

Spring AI 用VectorStore接口抽象了向量存储的操作。无论是 Pinecone、Milvus 这样的专业向量数据库，还是 PostgreSQL 的 pgvector 扩展，甚至是内存型的简单存储，都可以通过统一的VectorStoreAPI 来操作。

它的工作流程通常是这样的：

1. 文档加载与分块：将你的 PDF、Word、TXT 文档加载进来，并切割成大小适中的文本块（Chunk）。分块策略直接影响检索效果，太小会失去上下文，太大会引入噪声。
2. 向量化嵌入：使用一个嵌入模型（Embedding Model，如 OpenAI 的text-embedding-3-small）将每个文本块转换成高维向量（一堆数字）。语义相近的文本，其向量在空间中的距离也更近。
3. 存储向量：将这些向量和对应的原始文本块，存入VectorStore。
4. 检索：当用户提问时，将问题也用同样的嵌入模型转换成向量，然后在VectorStore中搜索与这个“问题向量”最相似的几个文本块。
5. 增强生成：将检索到的相关文本块作为上下文，和用户问题一起组合成最终的 Prompt，送给大模型生成答案。

# application.yml 配置示例 (以 OpenAI 和简单的内存向量库为例) spring: ai: openai: api-key: ${OPENAI_API_KEY} chat: options: model: gpt-4o-mini vectorstore: in-memory: enabled: true

在代码中，你可以通过VectorStore的add和similaritySearch方法来完成存储和检索。Spring AI 还提供了DocumentReader、TextSplitter等组件，让整个文档处理流水线更加模块化。这里的一个实战心得是：嵌入模型的选择和文本分块的大小，是影响 RAG 效果最关键的参数，需要根据你的文档类型（是技术手册还是对话记录）和问题类型（是事实查询还是开放分析）进行反复调试，没有银弹。

2.3AiStream与函数调用：走向复杂交互

简单的问答和文档总结只是开始。Spring AI 2.0 加强了对流式响应和函数调用的支持，这让构建更复杂的交互式 AI 应用成为可能。

AiStream允许你以流的方式处理模型的响应。对于生成长文本（如文章、报告）的场景，这能极大提升用户体验，让用户看到文字逐个蹦出的过程，而不是等待漫长的全量生成。

public Flux<String> streamStory(String theme) { Prompt prompt = new Prompt(new UserMessage("以‘” + theme + “’为主题写一个短篇故事。")); return chatClient.stream(prompt) .map(response -> response.getResult().getOutput().getContent()); } // 在 Controller 中，你可以返回 Server-Sent Events (SSE) 或 WebFlux 的 Flux。

函数调用则是实现“自主 Agent”的基石。你可以将你的业务能力（如查询数据库、调用外部 API、发送邮件）封装成@Bean方法，并描述其功能。AI 模型在对话过程中，如果判断需要调用这些函数来获取信息或执行操作，就会发起调用。

@Bean @Description("根据城市名称查询实时天气") // 描述很重要，AI 靠它理解函数用途 public Function<WeatherService.Request, WeatherService.Response> weatherFunction() { return request -> { // 这里实现真正的天气查询逻辑 return weatherService.getCurrentWeather(request.city()); }; }

配置好后，当用户问“北京天气怎么样？”时，ChatClient的对话会触发对weatherFunction的调用，获取真实数据后，再整合进对话回复给用户。这就让 AI 从“聊天机器人”变成了可以操作现实系统的“智能体”。

3. Spring AI Alibaba：当 Spring 生态遇见国产云生态

“Spring AI Alibaba”这个词最近热度很高，它本质上是阿里云为 Spring AI 项目提供的一套“实现”和“扩展”。你可以把它理解为 Spring AI 规范在阿里云平台上的官方落地版本。它的出现，解决了国内开发者使用 Spring AI 的几个核心痛点。

首先，是模型接入的合规与便利性。对于国内企业和开发者，直接使用 OpenAI 的 API 存在网络、合规和成本的多重障碍。Spring AI Alibaba 默认深度集成阿里云灵积平台上的各种模型，如通义千问、通义灵码等。你只需要一个阿里云账号和对应的 AK/SK，就能在application.yml里轻松配置，享受和 OpenAI 一样的编程体验。

spring: ai: alibaba: dashscope: api-key: ${ALIBABA_CLOUD_API_KEY} chat: options: model: qwen-max

其次，是数据与服务的生态整合。这是比单纯换模型更有想象力的地方。阿里云有丰富的云产品，如 OSS（对象存储）、RDS（数据库）、MNS（消息服务）等。Spring AI Alibaba 的DataAgent等概念，目标就是让 AI Agent 能够安全、便捷地访问和操作这些云服务背后的数据。

你提到的“spring ai alibaba dataagent 有权限模块吗”，这问到了点子上。目前公开的文档和示例中，DataAgent更像是一个高级抽象，它旨在简化 Agent 访问结构化数据（如数据库表）的过程。关于严格的、生产级的权限模块（例如基于 RBAC 的，控制某个 AI Agent 只能查询特定数据库表的部分列），目前可能还需要开发者基于 Spring Security 等框架在应用层自行构建。DataAgent更关注的是“如何访问”的便利性，而“谁能访问”的权限控制，是需要与你的业务身份认证和授权体系打通的，这也是企业级应用必须考虑的安全环节。

最后，是对本地部署和混合云场景的探索。一些资料显示，Spring AI Alibaba 也在探索与Alibaba Graph（可能指图计算服务或知识图谱）的集成，以及更复杂的 Agent 工作流编排。这暗示了其方向不仅是调用云上模型，更是构建一个能利用整个阿里云技术栈能力的 AI 应用开发平台。

4. 构建“自主 Agent”：从概念到可运行代码

“自主 Agent”是当前 AI 应用的前沿热点。它指的是一个能理解复杂目标、自主规划并调用工具完成任务 AI 系统。Spring AI 提供了构建此类 Agent 的基础模块，但离“开箱即用”的通用智能体还有距离，需要开发者精心设计。

4.1 Agent 的核心循环：ReAct 模式

一个典型的自主 Agent 遵循类似ReAct的模式：思考->行动->观察，循环往复。

1. 思考：分析当前目标和已有信息，决定下一步该做什么（是调用一个工具，还是直接给出答案）。
2. 行动：执行决定，比如调用一个查询天气的函数。
3. 观察：获取行动的结果（比如“北京晴，25度”）。
4. 将观察结果纳入上下文，重新开始“思考”，直到任务完成或达到步骤限制。

在 Spring AI 中，你可以通过组合ChatClient、PromptTemplate（用于给 Agent 设计系统指令，比如“你是一个有帮助的助手，可以调用工具”）、以及一系列Function来模拟这个循环。Spring AI 可能会提供更高阶的Agent抽象来简化这个过程，但底层原理不变。

4.2 一个简单的任务执行 Agent 示例

假设我们要构建一个“旅行规划助手”Agent，它能查询天气和获取航班信息。

@Service public class TravelAgentService { @Autowired private ChatClient chatClient; @Autowired private Function<WeatherRequest, WeatherResponse> weatherFunction; @Autowired private Function<FlightRequest, FlightResponse> flightFunction; public String planTravel(String userRequest) { // 1. 定义系统指令，告诉 AI 它的角色和可用的工具 String systemInstruction = """ 你是一个旅行规划助手。你可以调用工具来获取实时信息。 你可以使用的工具有： 1. weatherFunction: 查询指定城市的当前天气。 2. flightFunction: 查询指定路线的航班信息。 请根据用户的需求，合理规划调用工具的顺序，并最终整合信息给出建议。 """; // 2. 将工具注册给 ChatClient（这里简化，实际有更优雅的绑定方式） // Spring AI 通常通过 `ChatClient` 的配置项或特定的 `Agent` 构建器来关联函数。 // 3. 构造包含系统指令和用户请求的 Prompt Prompt prompt = new Prompt(List.of( new SystemMessage(systemInstruction), new UserMessage(userRequest) )); // 4. 发起对话。配置了函数调用的 ChatClient 会自动处理“思考-行动”循环。 ChatResponse response = chatClient.call(prompt); // 在这个响应过程中，ChatClient 可能会多次与模型交互，中间自动调用了我们的 weatherFunction 和 flightFunction。 // 5. 返回最终结果 return response.getResult().getOutput().getContent(); } }

这个示例极度简化，真实的 Agent 需要处理多轮对话状态管理、工具调用结果的解析、防止无限循环等。Spring AI 的目标就是通过Agent、Chain等更高层抽象，把这些复杂性封装起来。

4.3 避坑指南：Agent 实践中的常见问题

1. 无限循环与高成本：Agent 可能陷入“思考-调用-再思考”的死循环。必须设置最大迭代次数。在 Spring AI 中，这通常通过配置ChatClient的调用选项或使用特定的AgentExecutor来实现。
2. 工具描述的精确性：你给函数写的@Description至关重要。描述不清，AI 就无法正确理解何时该调用它。描述要具体，包含输入输出的格式和语义。
3. 上下文长度限制：每次调用模型都有令牌数限制。Agent 的多次行动和观察历史会不断累积，可能很快超限。需要设计上下文窗口管理策略，比如只保留最近几轮的交互。
4. 错误处理：工具调用可能失败（网络超时、API 限流）。你的 Agent 需要有错误处理机制，能够捕捉异常并决定是重试、换一种方式还是向用户报错。

5. 向生产环境迈进：安全、监控与最佳实践

将 Spring AI 应用从 Demo 推向生产，需要考虑更多工程化问题。

安全是第一要务：

• API 密钥管理：绝不能将api-key硬编码在代码或配置文件中。必须使用环境变量或专业的密钥管理服务（如阿里云 KMS、HashiCorp Vault）。
• 提示词注入防护：如果 Prompt 中包含了用户输入，必须进行严格的过滤和转义，防止用户通过精心构造的输入劫持系统指令，让 AI 执行恶意操作。
• 输出内容过滤：AI 的生成内容是不可控的。必须对输出进行安全审查，过滤不当、偏见或有害信息。可以在调用ChatClient后增加一个内容过滤层。
• 权限控制：如前所述，结合 Spring Security 对能触发 AI 功能的端点进行鉴权，对 AI 能访问的数据资源进行授权。

可观测性不可或缺：

• 日志记录：详细记录每一次 AI 调用的输入（Prompt）、输出、使用的模型、消耗的令牌数、耗时和成本。这对调试、优化和计费至关重要。
• 链路追踪：将 AI 调用嵌入到你的分布式链路追踪系统（如 SkyWalking, Jaeger）中，让你能看清一次用户请求背后，调用了多少次模型、多少次工具函数。
• 指标监控：监控 AI 服务的延迟、成功率、令牌消耗速率等关键指标，并设置告警。

成本与性能优化：

• 模型选型：不是所有任务都需要GPT-4。对于简单的分类、摘要，使用gpt-3.5-turbo或更小的模型能大幅降低成本。Spring AI 的抽象让你可以轻松为不同服务配置不同模型。
• 缓存策略：对于频繁出现的、结果确定的查询（如“公司的退货政策是什么？”），可以将 AI 的回复缓存起来，避免重复调用产生费用。Spring 的@Cacheable注解可以在这里派上用场。
• 异步与批处理：对于非实时性的任务（如批量生成产品描述），可以采用异步处理，甚至将多个请求批量化后发送给模型 API，以提高吞吐量。

从我实际落地的经验来看，Spring AI 最大的优势在于它极大地统一和简化了 AI 能力集成的模式。它可能不是性能极致优化的那个，但绝对是让团队快速拥抱 AI、并将 AI 能力像乐高积木一样嵌入现有 Spring 体系的最平滑路径。随着 Spring AI Alibaba 等厂商实现的加入，这条路径在国内的可用性和实用性正在快速增强。当然，它仍在快速演进中，API 可能变动，生态还在完善，但对于想要稳健起步的 Java 团队来说，现在投入学习并开始试点，已经是一个不错的时机。