企业官网建设流程全解析

很多 Java 开发者第一次接触 Spring AI 时，第一反应都是：这不就是把大模型 API 包了一层吗？等真正动手做项目才发现，问题远比想象中复杂。模型返回的 JSON 结构不稳定、知识库检索结果不相关、Agent 调用工具经常失败，一个比一个头疼。

这篇文章会根据我学习 Spring AI 的完整路径，把 LangChain4j、Tools、RAG、Agent 这几个核心概念一次性讲透。从环境搭建到项目实战，每一部分都会给出可以直接运行的代码示例和调试思路。不管你之前有没有接触过 AI 应用开发，只要按照这里的步骤走一遍，都能把 Spring AI 项目的完整链路跑通。

1. 为什么 Java 开发者需要 Spring AI

过去做 AI 应用，技术栈基本被 Python 垄断。Java 开发者要么硬着头皮写 Python 服务，要么用 HTTP 请求直接调大模型接口，然后自己处理 JSON 解析、会话管理、上下文拼接这些琐碎工作。接口调用本身不难，难的是把这些能力组织成可以维护的业务系统。

Spring AI 的出现改变了这个局面。它把大模型接入、提示词管理、结构化输出、向量检索、工具调用这些能力统一封装成 Spring 风格的 API。你不需要学习 Python，也不需要理解深度学习的数学原理，只要会 Spring Boot，就能开发 AI 应用。

Spring AI 和 LangChain4j 是这个领域最值得关注的两个 Java 框架。LangChain4j 借鉴了 Python 生态的 LangChain 设计思路，功能覆盖很全；Spring AI 则由 Spring 官方团队维护，和 Spring Boot、Spring Cloud 的集成天然无缝。这两个框架不是竞争关系，而是互补关系。在小项目里，两个框架的写法差异不大；但在企业级应用中，Spring AI 的 Spring 生态集成优势会更明显。

这篇文章会用 Spring AI 为主线，穿插对比 LangChain4j 的实现思路。这样你既能掌握一个框架的具体用法，也能理解这类框架的通用设计逻辑。

2. 核心概念：从 LLM 到 RAG 再到 Agent

2.1 ChatModel 与 ChatClient：一切功能的入口

Spring AI 的所有功能都围绕ChatModel接口展开。它抽象了对大模型的访问能力，底层支持 OpenAI、Ollama、通义千问、DeepSeek 等多种模型。你可以把ChatModel理解为 Spring 中的JdbcTemplate——它屏蔽了底层差异，提供了统一的操作入口。

ChatClient是更上层的一个流式 API，类似 Java 8 的Stream。它提供了一种链式调用的写法，让代码可读性更强。实际项目中大多数功能都可以基于ChatClient来实现。

2.2 Tools：让模型拥有调用外部工具的能力

大模型本身是「无法执行动作的」。它只能根据训练数据中的知识来生成文本，无法查询数据库、调用接口或修改文件。Tools（也叫 Function Calling）解决了这个问题：你可以把一些函数注册给模型，模型在生成回复时判断是否需要调用这些函数。

这个机制听起来简单，但它背后有一个关键变化：模型会在生成内容之前发起一次「请求调用工具」的动作，然后等待工具执行结果返回来生成最终答案。这意味着 Spring AI 的调用过程从「一次请求」变成了「多轮交互」。

2.3 RAG：把知识库接入到大模型回答中

大模型的知识截止日期是固定的，而且它对公司内部文档一无所知。如果不解决这个问题，AI 应用就只能回答通用问题，无法回答「我们公司的报销流程是什么」这类私域问题。

RAG（Retrieval-Augmented Generation）的思路是：提问时先从一个向量数据库中检索相关文档片段，把检索结果和用户问题一起交给大模型生成答案。这就像考试时先开卷查资料，再回答问题的过程。相比重新训练模型，RAG 成本低、更新方便、可解释性强。

2.4 Agent：从单次问答到复杂任务编排

Agent 是目前最受关注但也最容易被误解的概念。很多人把 Agent 理解为「能自动完成任务的机器人」，实际上 Agent 的本质是一种基于大模型的任务编排机制。

在 Spring AI 项目中，Agent 就是通过 System Prompt 给模型设定角色和目标，结合 Reply 机制（比如ReAct模式）让模型自主判断需要调用哪些工具、按什么顺序调用。核心是让模型来掌控决策，而不是预设死板的代码逻辑。

3. 环境准备与项目初始化

动手之前，先把环境准备好。我这里演示的环境配置如下，版本信息请以实际项目为准，重点理解思路。

3.1 基础环境要求

• JDK 17 及以上
• Maven 3.8 或以上
• Spring Boot 3.x 项目
• 一个可用的 LLM API Key（本文以通义千问为例）
• 本地可选安装 Ollama 用于本地模型调试

3.2 创建 Spring Boot 项目

打开 Spring Initializr，选择 Spring Boot 3.x 版本，添加 Spring Web 依赖，然后导入 IDE。也可以直接用 IDEA 的 Spring Initializr 创建。

创建完成后，在pom.xml中加入 Spring AI 的 BOM 和核心依赖：

<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>1.0.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-qwen</artifactId> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-vector-store-redis</artifactId> </dependency> </dependencies>

这里用到的版本号请以 Maven 中央仓库实际发布的版本为准。spring-ai-starter-model-qwen是 Spring AI 为通义千问提供的 Starter，配置好 API Key 就可以直接使用。

3.3 配置文件

在application.yml中配置模型供应商的 API Key：

spring: application: name: spring-ai-demo ai: model: qwen: api-key: ${DASHSCOPE_API_KEY} model: qwen-plus

如果你的环境变量里没有DASHSCOPE_API_KEY，可以直接写死测试，但生产环境强烈建议用配置中心或环境变量管理密钥。这里的qwen-plus是通义千问的模型名称，具体可选模型以官方文档为准。

3.4 快速验证是否配置成功

在 Spring Boot 启动类同目录下，创建一个 controller 来测试基本调用：

package com.example.demo; import org.springframework.ai.chat.client.ChatClient; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; @RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient = builder.build(); } @GetMapping("/chat") public String chat(@RequestParam(defaultValue = "你好") String message) { return chatClient.prompt() .user(message) .call() .content(); } }

启动项目后访问http://localhost:8080/chat?message=介绍一下SpringAIFramework。如果返回一段通顺的中文介绍，说明配置成功。这一步是整个教程的基础，后面所有功能都建立在这个调用链路之上。

4. 深入理解 ChatClient：常用用法与代码示例

ChatClient是 Spring AI 的核心 API，它有几种不同的调用方式，在异步和流式场景各有讲究。

4.1 同步调用与参数化 Prompt

上文的示例展示了最基本的同步调用。实际开发中，用户输入通常是变化的，我们需要把用户参数拼接到 Prompt 中。

Spring AI 提供了一种类似于 MyBatis 参数绑定的写法：

@GetMapping("/poem") public String poem(@RequestParam String topic) { return chatClient.prompt() .user(userSpec -> userSpec .text("请写一首关于{topic}的短诗，要求语言优美、意境深远。") .param("topic", topic)) .call() .content(); }

.param("topic", topic)会把{topic}占位符替换成实际值。这样做有两个好处：一是 Prompt 模板和参数分离，维护起来更清晰；二是避免字符串拼接导致 Prompt 内容混乱。

4.2 流式调用

大模型生成内容需要时间，如果一直等全部生成完再返回，用户体验会很差。流式调用可以在生成过程中逐步把内容推送给前端，类似 ChatGPT 的打字效果。

@GetMapping("/stream") public Flux<String> stream(@RequestParam String message) { return chatClient.prompt() .user(message) .stream() .content(); }

注意返回类型是Flux<String>，这是 Reactor 提供的响应式类型。前端可以通过 SSE（Server-Sent Events）来接收流式数据。如果是 WebFlux 项目，直接返回Flux即可；如果是传统的 Spring MVC，可以配合SseEmitter使用。

4.3 ChatMemory：让多轮对话拥有记忆

默认情况下，ChatClient 每一次调用都是独立的，模型不会记得之前的对话内容。要实现多轮对话，必须显式维护历史会话。

Spring AI 提供了ChatMemory接口来处理这个问题。我们可以用InMemoryChatMemory在内存中保存会话历史，或者用数据库实现持久化。

@Component public class ChatAssistant { private final ChatClient chatClient; private final ChatMemory chatMemory = new InMemoryChatMemory(); public ChatAssistant(ChatClient.Builder builder) { this.chatClient = builder .defaultSystem("你是一个乐于助人的AI助手") .build(); } public String chat(Long sessionId, String message) { return chatClient.prompt() .user(message) .chatMemory(chatMemory) .chatId(sessionId) .call() .content(); } }

这里的chatId可以设置为用户 ID 或会话 ID。Spring AI 会把这个会话的历史消息自动携带到请求中。需要注意，如果会话历史太长，token 消耗会很大。实际项目里要设置消息过期时间，或者定期清理历史记录。

5. Tools 实战：定义并使用自定义函数

Tools 是 Spring AI Agent 能力的基石，也是其魅力所在。这里用一个实际场景来演示：让模型查询数据库中的用户信息并计算订单金额。

5.1 注册 Tool 函数

package com.example.demo.tools; import com.example.demo.service.UserOrderService; import org.springframework.stereotype.Component; import java.util.function.Function; @Component public class UserOrderTool implements Function<UserOrderTool.Request, UserOrderTool.Response> { private final UserOrderService userOrderService; public UserOrderTool(UserOrderService userOrderService) { this.userOrderService = userOrderService; } public record Request(Long userId) {} public record Response(String userInfo, Double totalAmount) {} @Override public Response apply(Request request) { // 模拟查询数据库 String userInfo = userOrderService.getUserById(request.userId()); Double totalAmount = userOrderService.getUserOrderTotal(request.userId()); return new Response(userInfo, totalAmount); } }

5.2 在 ChatClient 中注册并使用 Tool

@RestController public class AgentController { private final ChatClient chatClient; public AgentController(ChatClient.Builder builder, UserOrderTool userOrderTool) { this.chatClient = builder .defaultTools(userOrderTool) .build(); } @GetMapping("/agent/order") public String queryOrder(@RequestParam Long userId) { return chatClient.prompt() .user("请查询用户ID为" + userId + "的基本信息和累计订单金额") .call() .content(); } }

这里的关键是defaultTools(userOrderTool)——Spring AI 会自动扫描Function实现类，提取Request类的字段信息作为函数的 JSON Schema，描述给大模型。

当用户问「用户ID为1001的用户订单金额是多少」，模型会判断需要调用UserOrderTool函数，然后 Spring AI 自动执行该函数，把结果返回给模型，最后模型基于函数结果给出自然语言回复。

5.3 多个 Tools 协同与调用链

实际业务中，一次问答往往需要调用多个工具。比如用户问「用户 1001 最近的订单里有没有退货」，模型可能需要先调用订单查询工具，再调用退货状态查询工具，最后汇总答案。

Spring AI 的defaultTools支持传入多个 Tool 对象：

public AgentController(ChatClient.Builder builder, UserOrderTool userOrderTool, RefundStatusTool refundStatusTool) { this.chatClient = builder .defaultTools(userOrderTool, refundStatusTool) .build(); }

模型会根据用户问题的上下文，自主决定调用哪个工具、按什么顺序调用。这也是 Agent 的核心机制：通过多轮「思考-调用-观察」循环来完成任务。

5.4 避坑指南

Tools 开发中比较容易踩的坑有三个。第一，Tool 描述要尽量详细，因为模型的函数选择完全依赖参数名和结构，如果参数名是a、b这种无意义的名称，模型根本不知道应该传什么。第二，Tool 内部一定要有异常处理，工具执行失败会直接导致整个对话链路中断。第三，不要在 Tool 中执行耗时过长的操作，模型有响应超时限制。

6. RAG 实战：构建一个 Java 知识库问答系统

RAG 是当前企业落地 AI 最实用的技术方向。Spring AI 对 RAG 的支持已经比较完善，接下来从零构建一个基于 Redis 向量存储的知识库问答系统。

6.1 RAG 核心流程

先理解 RAG 的完整流程：

1. 文档加载：读取 PDF、TXT、Word 等格式的文档。
2. 文档切分：把长文档按照一定策略切分成多个片段（chunk）。
3. 向量化：把每个片段通过 Embedding 模型转换成向量。
4. 向量存储：把向量写入向量数据库。
5. 检索：用户提问时，把问题向量化，在向量库中检索最相似的片段。
6. 生成：把检索到的片段作为上下文，和用户问题一起交给大模型生成回答。

6.2 文档加载与切分

Spring AI 提供了多种文档加载器和切分器。以常见的 PDF 文档为例：

package com.example.demo.rag; import org.springframework.ai.document.Document; import org.springframework.ai.reader.pdf.PagePdfDocumentReader; import org.springframework.ai.transformer.splitter.TokenTextSplitter; import org.springframework.ai.vectorstore.VectorStore; import org.springframework.stereotype.Service; import java.util.List; @Service public class KnowledgeService { private final VectorStore vectorStore; public KnowledgeService(VectorStore vectorStore) { this.vectorStore = vectorStore; } public void ingestPdf(String filePath) { // 1. 加载 PDF 文档 PagePdfDocumentReader reader = new PagePdfDocumentReader(filePath); List<Document> documents = reader.get(); // 2. 切分文档 TokenTextSplitter splitter = new TokenTextSplitter(); List<Document> chunks = splitter.apply(documents); // 3. 写入向量库 vectorStore.add(chunks); } }

切分策略是 RAG 效果好坏的关键。如果切分得太小，语义信息不完整；切分得太大，检索结果可能包含太多无关内容。常用的策略包括固定大小切分、按标题切分、按段落切分、语义切分等。Spring AI 内置了多种切分器，实际项目中建议先分析文档结构，再选择合适的切分策略。

6.3 向量化与向量存储

Spring AI 通过EmbeddingModel接口抽象了向量化能力。使用通义千问的 Embedding 模型时，只需要在配置文件中指定即可：

spring: ai: model: qwen: embedding: model: text-embedding-v1

向量存储方面，Spring AI 支持 Redis、Milvus、PgVector、Chroma 等多种向量数据库。以 Milvus 为例，它更适合大规模向量检索，是生产环境中常见的选择。

spring: ai: vectorstore: milvus: host: localhost port: 19530 database: default collection-name: knowledge_base index-type: IVF_FLAT metric-type: COSINE

无论选择哪种向量数据库，Spring AI 都统一通过VectorStore接口操作。这就是框架的价值所在：底层实现可以随时切换，业务代码不需要改动。

6.4 使用检索增强生成回答

@RestController public class RagController { private final ChatClient chatClient; public RagController(ChatClient.Builder builder, VectorStore vectorStore) { this.chatClient = builder .defaultAdvisors(MessageWindowChatMemory.builder().build()) .build(); } @PostMapping("/rag/ask") public String ask(@RequestBody String question) { return chatClient.prompt() .advisors(advisorSpec -> advisorSpec .param("vectorStore", vectorStore) .param("topK", 4)) .user(question) .call() .content(); } }

这里用到了 Spring AI 的 Advisor 机制。QuestionAnswerAdvisor会自动完成「向量化用户问题、检索知识库、拼装上下文、调用大模型」这整个流程。你不需要手动写检索逻辑，只需要在 Prompt 的参数中传入vectorStore即可。

需要注意的是，QuestionAnswerAdvisor需要显式配置。如果你的项目里没有主动设置这个 Advisor，上面的代码不会生效。更稳妥的方式是手动实现检索逻辑，把结果作为上下文传给模型：

@PostMapping("/rag/ask/manual") public String askManual(@RequestBody String question) { List<Document> documents = vectorStore.similaritySearch(question, 4); String context = documents.stream() .map(Document::getText) .collect(Collectors.joining("\n")); System.out.println("检索到的上下文: " + context); return chatClient.prompt() .system("你是一个知识库问答助手，请基于以下参考资料回答问题。如果资料中没有相关内容，请明确表示不知道。\n" + context) .user(question) .call() .content(); }

这段代码展示了 RAG 的本质：核心是「检索」和「拼接」。无论用 Advisor 还是手动实现，理解了这个过程，你就掌握了 RAG 的精髓。

6.5 混合检索与重排

普通向量检索在专业领域效果有时不理想，因为向量相似度并不完全等于语义相关性。生产级的 RAG 系统通常使用混合检索（关键词检索 + 向量检索）加重排（Rerank）来提升准确率。

混合检索的思路是：同时用 BM25 关键词检索和向量检索各查一批结果，然后通过 Rerank 模型重新排序，选出最相关的片段。这个方案在中文场景下尤其重要——中文分词质量直接影响到检索效果。

LangChain4j 对混合检索和重排的支持比 Spring AI 更直接，如果你需要这种能力，可以在 Spring AI 项目中嵌入 LangChain4j 的检索模块，或者使用 Milvus 提供的混合检索能力。

7. 结构化输出：让模型返回稳定的 JSON

很多开发者都遇到过这样的问题：用大模型提取数据时，第一次返回 JSON，第二次返回纯文本，第三次在 JSON 外面加了 Markdown 代码块。这种不稳定性在业务系统中是无法接受的。

Spring AI 提供了BeanOutputConverter，可以强制模型按照 Java 类的结构输出数据：

public record OrderInfo( String orderId, String productName, Double amount, String status, List<String> items ) {} @GetMapping("/extract") public OrderInfo extractOrder(@RequestParam String text) { BeanOutputConverter<OrderInfo> converter = new BeanOutputConverter<>(OrderInfo.class); String formatInstruction = converter.getFormatInstruction(); String response = chatClient.prompt() .user(userSpec -> userSpec .text("请从以下文本中提取订单信息：\n{text}\n\n{format}") .param("text", text) .param("format", formatInstruction)) .call() .content(); return converter.convert(response); }

这个机制实际上是在 Prompt 中注入一段 JSON Schema 描述，告诉模型「必须输出符合以下结构的 JSON」。BeanOutputConverter则负责把模型输出的 JSON 反序列化成 Java 对象。

结构化输出是 AI 应用接入业务系统的关键一步。不管是做信息抽取、表单自动填写，还是 Agent 的中间状态处理，都建议用这种方式来保证数据质量。

8. Agent 开发实战：让模型自主完成任务

最后进入 Agent 部分。这是整个教程中最有挑战性但也最有趣的内容。结合前面的 Tools 和 RAG 能力，来构建一个能够自主完成任务的 Agent。

8.1 Agent 的核心机制

Spring AI 的 Agent 能力基于ReAct（Reasoning + Acting）模式。模型在回答复杂问题时，会遵循一个循环模式：

1. 思考（Thought）：分析当前问题，决定下一步要做什么。
2. 行动（Action）：调用选定的工具。
3. 观察（Observation）：查看工具执行结果。
4. 重复以上过程，直到得出结论。

这个过程本质上是把「决策权」交给了模型。开发者只需预先定义好工具集，并给出清晰的角色说明。

8.2 用 ChatClient 构建最小 Agent

@Component public class TravelAgent { private final ChatClient chatClient; public TravelAgent(ChatClient.Builder builder, FlightSearchTool flightSearchTool, HotelSearchTool hotelSearchTool, WeatherQueryTool weatherQueryTool) { this.chatClient = builder .defaultSystem(""" 你是一个专业的旅行规划助手。你的任务是帮助用户规划旅行行程。 你可以使用以下工具： 1. flightSearchTool：查询航班信息 2. hotelSearchTool：查询酒店信息 3. weatherQueryTool：查询天气信息 在回答用户问题时，请按照以下步骤执行： 1. 先了解用户的出行日期和目的地 2. 查询航班和酒店信息 3. 查询目的地的天气情况 4. 综合考虑后给出建议 如果用户提供的信息不完整，请主动询问。 """) .defaultTools(flightSearchTool, hotelSearchTool, weatherQueryTool) .build(); } public String planTrip(String request) { return chatClient.prompt() .user(request) .call() .content(); } }

这个 Agent 的核心逻辑完全在 System Prompt 中定义，工具的执行由底层框架自动完成。当用户说「帮我规划下周五从北京到上海的行程」，模型会依次调用航班查询工具、酒店查询工具和天气查询工具，最后汇总所有信息给出完整方案。

8.3 Agentic RAG：检索与推理结合

把 RAG 和 Agent 结合，就形成了目前备受关注的 Agentic RAG。传统 RAG 只会做一次检索然后回答，Agentic RAG 则可以让模型根据自己的判断决定是否需要进一步检索、是否需要修改检索关键词、是否需要查询外部 API。

实际项目中，Agentic RAG 的模式可以这样实现：

public String agenticRag(String question) { return chatClient.prompt() .system(""" 你是一个企业知识库智能助手。 你可以使用以下工具： 1. knowledgeSearchTool：在企业知识库中检索信息 2. userInfoTool：查询用户的部门、职级等信息 回答问题时： 1. 如果问题涉及企业内部政策或流程，请先查询知识库 2. 如果问题涉及个人权益，请先查询用户信息 3. 如果知识库中没有相关内容，请明确告知用户 """) .defaultTools(knowledgeSearchTool, userInfoTool) .user(question) .call() .content(); }

这种方式比自己写 if-else 判断要灵活得多。模型的意图识别能力可以覆盖各种复杂的问答场景，而传统代码很难预先穷举所有可能的分支。

8.4 多 Agent 协作的原理

多 Agent 协作是 Agent 开发的进阶方向，很多人一开始会下意识地认为它的重点是「多个 Agent 互相对话」。但核心其实在于「分工」和「协调」。你可以为不同角色配置不同的 System Prompt，通过一个主控制器来分配任务。不过在 Spring AI 目前版本中，真正生产级的多 Agent 编排能力还在逐步完善，中小型项目建议先从单 Agent + 多个 Tools 开始，把问题拆解到 Tools 维度来解决。

9. 性能优化与调优建议

9.1 Prompt 优化

Prompt 的质量直接决定输出质量。好的 Prompt 包含角色设定、任务说明、约束条件和输入格式，例如明确指定「如果信息不足请说不知道，不要编造」。避免使用模糊的指令，尽量用具体、可执行的语言描述预期行为。

9.2 RAG 调优的关键参数

RAG 项目的效果主要受三个参数影响：topK（召回片段数量）、切分大小和重排序策略。topK太小容易漏掉关键信息，太大则可能引入噪声。建议先用 4 作为基线，根据回答质量调整。切分大小建议从 500 到 1000 个 token 开始实验，针对不同文档类型做针对性调整。

9.3 缓存与成本控制

大模型 API 调用成本不容忽视。对于频繁询问的相同问题，可以增加一层缓存：先用问题文本的哈希值查询缓存，命中则直接返回，未命中再调用模型。Spring 的@Cacheable注解可以很方便地实现这一层：

@Cacheable(cacheNames = "chatCache", key = "#message") public String chatWithCache(String message) { return chatClient.prompt() .user(message) .call() .content(); }

这个优化在 RAG 场景中尤其有效，因为知识库问题的重复率通常较高。

10. 常见问题与排查方法

这里重点说一下日志调试方法。Spring AI 内置了请求和响应的日志输出能力，很多问题的根源都藏在模型返回的原始请求体中。建议在开发阶段开启 DEBUG 日志：

logging: level: org.springframework.ai: DEBUG

这样你会看到完整的模型请求头和响应体，工具调用的参数、RAG 检索的结果都在里面。

11. 对 Java 开发者的工程建议

做 Spring AI 项目，技术之外的一些工程习惯同样重要。

第一个建议是：配置和代码分离。API Key、模型名称、向量数据库地址等配置，一律通过配置中心管理，不要硬编码在代码中。尤其是 API Key，一旦泄露到代码仓库，会造成直接的经济损失。

第二个建议是：给 Prompt 建立版本管理。Prompt 是 AI 应用的核心资产，它的迭代频率不亚于代码。建议把 Prompt 模板放在单独的目录或数据库中，用配置平台管理，不要散落在 Java 代码中，这样方便追溯效果变化。

第三个建议是：设计评估机制。调用大模型需要引入质量评估环节，不能只看代码逻辑是否正确。可以准备一批验证问题集，每次修改 Prompt 或调整 RAG 参数后都跑一遍回归测试，用评分来评估效果。

第四个建议是：控制好异常粒度和超时时间。外部模型调用的稳定性远低于内部服务调用，必须有超时控制、重试机制和降级方案。多轮对话场景尤其要注意超时设置，避免用户长时间等待后失败。

12. 总结与进阶学习路径

从 Spring AI 基础调用到 Tools、RAG、Agent，这篇文章实际上是沿着一条完整的学习路径展开的：先跑通最小调用链路，然后理解 ChatClient 的核心玩法，再接入外部工具扩展模型能力，接着通过 RAG 让模型具备私域知识库的回答能力，最后把这一切组合成 Agent。

对大多数 Java 开发者来说，最值得投入精力的方向依次是：RAG 和 Tools。RAG 是当前企业落地 AI 最确定的场景，任何需要基于文档问答的项目都离不开它；Tools 是让 AI 能力与业务系统产生实际交互的关键桥梁。Agent 虽然更有想象力，但在生产环境中的稳定性仍需要大量打磨，建议先在业务相对简单的场景做试点。

进阶学习可以从扩展模型供应商、向量数据库调优、主流 Agent 框架源码阅读这几个方向推进。如果项目对响应实时性要求高，可以深入研究流式输出和 SSE 协议；如果项目涉及大量 PDF、表格类文档，可以进一步学习布局分析、表格结构识别等文档解析技术。

技术的演进速度很快，但底层的工程方法论是相通的。把 Spring AI 当作一个可以随时替换的组件来学习，而不是只背 API。理解了模型交互的本质，未来无论出现新的框架或模型，你都能快速跟上。