企业官网建设流程全解析

先说结论：2026 年这个时间点看 Java 做 AI 应用，Spring AI 已经不是“要不要学”的问题，而是“按照哪条路线学能最快落地”的问题。很多人收藏了各种 Java + Spring AI 2.0 实战教程，但真正打开项目时还是会被四件事卡住：多模型怎么接、Tools 怎么让模型调用 Java 方法、MCP 到底解决什么问题、Agent 怎么把前面这些串起来。

这篇博客就按这条主线来写。目标是帮 Java 后端开发者，在已有 Spring Boot 基础上，快速跑通一个集成了多模型、Tools、MCP、Skills、Agent 的 AI 服务。本文只讲 Spring Boot 工程的真实写法，不依赖任何视频课程，也不堆概念，能跑通的代码直接给。

不管你叫它“2026 版教程”还是“Spring AI 2.0 实战”，核心其实很一致：Spring AI 已经把模型接入、工具调用、结构化输出、MCP、Agent 编排做成了 Spring 风格的组件。你不需要先去学 Python，也不需要重写整套 AI 框架。

1. Spring AI 2.0 核心能力速览

从使用门槛来看，Spring AI 对 Java 团队非常友好。它把“模型厂商差异”藏在依赖和配置层，业务代码不直接依赖某一个模型 SDK。后面接新模型时，改动可以控制在配置层，而不是把业务代码全部重写。

先说清楚边界：Spring AI 不是用来训练模型、微调大模型的。它是“应用开发框架”，负责把大模型的能力接进你的 Spring Boot 系统。如果团队要做模型训练和调参，那还是需要 Python 生态；如果只是做智能客服、文档处理、工具调用、Agent 编排，Spring AI 是当前 Java 生态里最值得投入的方向。

2. Spring AI 2.0 适合谁，不适合谁

适合的读者有三类：

第一，已经有 Java 后端经验，想在现有 Spring Boot 项目里接入大模型能力的开发者。第二，长期用 Python 写 Agent，但需要回迁到 Java 技术栈做企业级集成的团队。第三，要做统一接入层，不希望被某一家模型厂商锁定的架构师。

Spring AI 解决的核心问题可以概括为：用一套统一的ChatClient接口，屏蔽不同模型厂商的差异；用@Tool让模型能够调用 Java 方法；用 MCP 标准化接入外部工具和数据源；用 Advisor 和 ChatMemory 管理会话上下文；再把这些能力组合成 Agent。

不适合的场景也很清楚。如果只是做一个简单的一问一答接口，没必要引入完整 Agent 编排；如果项目需要大规模微调模型，Spring AI 帮不上忙；如果团队没有人熟悉 Spring Boot，学习成本会集中在 Java 侧而不是 AI 侧。

使用边界上有一个必须强调的点：Agent 和 Tools 意味着模型会被允许调用真实业务方法，比如查询数据库、发送通知、调用第三方接口。这些能力如果不下发到测试环境，或者没有加权限校验和调用审计，一旦模型被恶意引导，可能出现越权调用。接入真实业务前，工具方法必须有用户身份校验、参数校验和操作审计。

3. 环境准备与前置条件

先列一套最小可运行环境。

没有 API Key 的情况下，推荐先装 Ollama。Ollama 可以本地拉起 qwen2.5、llama3.1 这些开源模型，Spring AI 有官方 starter 直接对接，非常适合学习阶段调试。需要注意，本地模型推理要占用显存，具体显存占用取决于模型大小和推理服务配置，而不是由 Spring AI 决定。

JDK 和 Maven 装好后，先确认基本环境能用：

java -version mvn -version

如果本机以前装过其他 Java 版本，务必确认当前JAVA_HOME指向 JDK 17 以上。Spring AI 的很多 API 依赖 Java 17 的 record、sealed class 等新特性，JDK 版本不对可能在编译阶段就报错。

4. 搭建 Spring Boot + Spring AI 工程

建议不要手工从零创建 Spring Boot 项目，直接用 Spring Initializr 生成。生成时选择 Java 17、Maven、Spring Web，再手动加入 Spring AI 依赖。

Spring AI 的依赖需要单独引入 BOM。在pom.xml中先加spring-ai-bom：

<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>2.0.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

版本号请根据你当前使用的 Spring AI 官方 BOM 填写，这里只是示例。Spring AI 迭代速度比较快，BOM 版本和 Spring Boot 版本有对应关系，最稳妥的做法是去 Spring Initializr 页面勾选 Spring AI 依赖，让它自动生成兼容版本组合。

接着加入模型 starter。如果接 OpenAI 兼容接口：

<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-openai</artifactId> </dependency>

如果本地用 Ollama：

<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-ollama</artifactId> </dependency>

如果想通过 Spring AI Alibaba 接国内模型，还需要单独引入对应 starter，具体依赖坐标以官方文档为准。

依赖引入后，编写application.yml。以 OpenAI 为例：

spring: application: name: spring-ai-demo ai: openai: api-key: ${OPENAI_API_KEY} base-url: ${OPENAI_BASE_URL} chat: options: model: gpt-4o-mini

这里OPENAI_API_KEY和OPENAI_BASE_URL建议用环境变量注入，不要把密钥写死在配置文件里提交到 Git。

如果本地用 Ollama，配置更简单：

spring: ai: ollama: base-url: http://localhost:11434 chat: options: model: qwen2.5:7b

可以先写一个最简单的 main 方法启动类，确认 Spring 上下文能正常加载，再进行后面的功能测试。

5. 多模型接入：统一 ChatClient 与模型切换

Spring AI 的核心入口是ChatClient。它类似 RestClient 的设计，通过 Builder 构建，调用链路非常直观。先定义一个最基础的服务：

@Service public class ChatService { private final ChatClient chatClient; public ChatService(ChatClient.Builder builder) { this.chatClient = builder.build(); } public String chat(String message) { return chatClient.prompt() .user(message) .call() .content(); } }

这里的关键点是ChatClient是一个统一抽象，底层模型是哪个厂商的并不重要。你只需要在依赖和配置层面切换，业务代码基本不用动。

多模型切换有两种常见方式。

第一种：同时引入多个模型 starter，通过@Qualifier注入不同的ChatModel，再创建多个ChatClientBean：

@Configuration public class ChatClientConfig { @Bean @Qualifier("openAiChatClient") public ChatClient openAiChatClient(ChatClient.Builder builder) { return builder.build(); } @Bean @Qualifier("ollamaChatClient") public ChatClient ollamaChatClient(ChatClient.Builder builder) { return builder.build(); } }

第二种：在配置层通过spring.ai.model.chat指定默认模型。实际项目中，更推荐把“模型路由”做在配置中心，让不同租户、不同业务走不同模型，而不是在代码里写死。

多模型接入的价值在于：不是所有任务都需要最强模型。简单的摘要、分类、意图识别可以用便宜的小模型；复杂推理再切到大模型。这个设计能显著控制成本。

6. 结构化输出：让模型返回 Java 对象

在真实业务中，模型返回的自然语言文本很难直接对接流程。Spring AI 的结构化输出能力可以把 LLM 输出解析成 Java 对象。

定义一个 record：

public record ArticleOutline( String title, List<String> sections, int estimatedMinutes ) {}

调用时直接指定目标类型：

ArticleOutline outline = chatClient.prompt() .user("请生成一篇关于 Spring AI MCP 实战的文章大纲，要求包含标题、章节列表和预计阅读时间") .call() .entity(ArticleOutline.class); System.out.println(outline.title()); System.out.println(outline.sections());

结构化输出对于接入审批流程、表单自动填充、信息抽取非常有用。可以直接把模型输出映射成后端实体，再参与后续业务逻辑。

也可以把结构化输出能力封装成通用工具：

@Service public class StructuredOutputService { private final ChatClient chatClient; public StructuredOutputService(ChatClient chatClient) { this.chatClient = chatClient; } public <T> T extract(String text, Class<T> type) { String prompt = "请从以下内容中抽取结构化信息，严格按 JSON 返回。内容：" + text; return chatClient.prompt() .user(prompt) .call() .entity(type); } }

需要提醒的是：模型输出的 JSON 解析存在不稳定风险。字段名冲突、枚举值不匹配、输出格式被截断都可能导致解析失败。生产环境要加解析异常兜底，结构化输出失败时记录原始响应，方便排查。

7. Tools：给模型安上“动手能力”

Tools 是 Spring AI 最实用的功能之一。它解决的核心问题是：模型本身不具备访问外部系统、执行本地逻辑的能力，所以通过工具调用来扩展。

工具的本质很简单：一段 Java 方法 + 一个@Tool注解 + 清晰的描述信息。Spring AI 会在模型请求时把工具列表和描述传给模型，模型根据用户问题决定是否调用以及传什么参数。

@Component public class OrderTools { @Tool(name = "queryOrder", description = "根据订单号查询订单状态") public String queryOrder(String orderNo) { return "订单 " + orderNo + " 当前状态：已发货，预计明天送达"; } @Tool(name = "cancelOrder", description = "根据订单号取消未发货订单") public String cancelOrder(String orderNo) { return "订单 " + orderNo + " 已取消"; } }

在 ChatClient 调用时把工具对象传进去：

String answer = chatClient.prompt() .system("你是订单助手。用户询问订单状态时调用 queryOrder 工具，要求取消订单时调用 cancelOrder 工具。") .user("订单 1001 现在什么状态？") .tools(new OrderTools()) .call() .content();

从运行效果来看，模型会先返回一个工具调用请求，Spring AI 框架在后台执行 Java 方法，再把方法返回值作为上下文继续让模型生成最终答案。这个“执行工具并把结果反馈给模型”的过程对开发者是透明的。

工具方法设计有几个关键点：

• 方法参数越少越好，复杂对象参数会增加模型出错的概率。
• description要写清楚，模型是靠描述决定是否调用工具的。
• 工具方法内部要做防御性校验，不能信任模型传入的参数。
• 涉及写操作的工单、支付、发送等场景，必须加二次确认和权限校验。

8. MCP：标准化接入外部工具与服务

MCP（Model Context Protocol）是模型上下文协议，主要解决工具接入标准化的问题。之前每个工具都要写一套自定义调用逻辑，MCP 出现后，工具可以通过统一协议暴露给不同的 AI 应用。

Spring AI 在 MCP 生态上做得比较完整，既支持做 MCP Server，也支持做 MCP Client。

先说 MCP Server 场景。假设你有一个订单系统，希望把它暴露成 MCP Server，让其他 AI 应用也能调用。在 Spring Boot 工程里引入 MCP Server 依赖，再把@Tool方法注册进去，就可以通过 SSE 或 Streamable HTTP 对外提供 MCP 服务。

application.yml中配置 MCP Server：

spring: ai: mcp: server: name: order-mcp-server type: webmvc

刚才写的OrderTools如果放在这个 MCP Server 工程里，它就会自动被注册为标准 MCP 工具。其他 AI 应用不需要知道你的内部接口，只需要知道 MCP Server 地址，就能在对话中调用订单查询能力。

再说 MCP Client 场景。假如你的 AI 应用需要调用一个外部 MCP Server，在 Spring Boot 工程里配置客户端连接：

spring: ai: mcp: client: connections: order-server: type: sse url: http://localhost:8080/sse

配置完成后，外部 MCP Server 暴露的工具就会合并进当前 Spring AI 应用的工具列表，模型可以直接调用。这意味着：你的 Agent 不需要在自己工程里实现每个外部能力，只需要通过 MCP Client 接入不同的 MCP Server。

很多产品现在都推出了官方 MCP Server，比如文档处理、设计协作、外部搜索、数据库操作等场景，都开始提供标准 MCP 端点。对 Java 后端团队来说，Spring AI 的 MCP 支持可以直接消费这些能力，省掉大量对接工作。

需要提醒的是，MCP 协议和相关的 Spring AI 配置属性还在快速迭代中。不同版本的工具注册方式、连接配置字段可能存在差异，实际配置时一定要以当前 Spring AI 版本文档为准。

9. Skills：可复用的 Agent 技能封装

Skills 是理解 Spring AI 生产级应用的一个重要概念。很多人会把 MCP 和 Skill 混淆，其实两者关注层次完全不同。

MCP 关注的是工具和数据源的“标准化接入”，解决协议层的问题。Skill 关注的是“应用层封装”，把一次任务需要的 Prompt、工具、校验逻辑、回退策略打包成一个可复用单元。

举一个实际例子。一个“订单售后处理”Skill 可能包含：

• 系统提示词：定义角色、约束和输出格式。
• 工具列表：查询订单、查询物流、提交退款。
• 规则说明：什么情况可以退款、什么情况需要人工介入。
• 回退策略：调用工具失败时如何处理。

在 Spring AI 里，Skills 通常表现为一个封装好的服务组件或一套 Prompt + Tools 的组合配置。用 Java 来描述可以这样组织：

@Component public class AfterSaleSkill { private final ChatClient chatClient; private final OrderTools orderTools; private final LogisticsTools logisticsTools; public AfterSaleSkill(ChatClient chatClient, OrderTools orderTools, LogisticsTools logisticsTools) { this.chatClient = chatClient; this.orderTools = orderTools; this.logisticsTools = logisticsTools; } public String handle(String userMessage) { return chatClient.prompt() .system(""" 你是售后助手。处理用户售后问题必须遵循： 1. 先查询订单状态； 2. 如果订单未发货，提供取消订单方案； 3. 如果订单已发货，优先引导查看物流； 4. 退款超过 1000 元时必须提示转人工审核。 永远不要凭空编造订单数据。 """) .user(userMessage) .tools(orderTools, logisticsTools) .call() .content(); } }

这个AfterSaleSkill的区别在于：它不是一段简单的 prompt 字符串，而是“业务规则 + 工具集合 + 对话流程”的完整封装。之后无论 Agent 在哪一步需要售后能力，都可以直接调用这个 Skill，而不是把规则重新拼一遍。

对于 Java 团队来说，Skills 是沉淀业务逻辑的好载体。把模型行为、工具调用边界、业务规则固化在代码里，后续可测试、可复用、可控权。

10. Agent：多步推理与记忆管理

Agent 是 Spring AI 里把前面所有能力串起来的运行时。当我们说“开发 Agent”时，本质上是在做三件事：

第一，让模型具备多步推理能力。第二，在推理过程中动态调用 Tools、MCP、Skills。第三，维护会话记忆，让多轮对话里的上下文不丢失。

Spring AI 中 Agent 不是靠一个魔法类实现的，而是基于 ChatClient + Advisor + ChatMemory + Tools 组合出来的。

先加入 ChatMemory。会话记忆是 Agent 能连续完成任务的基础：

@Configuration public class AgentConfig { @Bean public ChatMemory chatMemory() { return MessageWindowChatMemory.builder() .maxMessages(20) .build(); } }

然后在服务中组装：

@Service public class OrderAgentService { private final ChatClient chatClient; private final ChatMemory chatMemory; public OrderAgentService(ChatClient.Builder builder, ChatMemory chatMemory) { this.chatMemory = chatMemory; this.chatClient = builder.defaultAdvisors( new MessageChatMemoryAdvisor(chatMemory) ).build(); } public String chatWithAgent(String userId, String userMessage) { return chatClient.prompt() .system("你是一个能查询订单、处理退款的智能助手。必须通过工具获取数据，禁止猜测订单状态。") .user(userMessage) .tools(new OrderTools()) .call() .content(); } }

这里有几个关键设计：

• MessageChatMemoryAdvisor负责自动把最近对话历史拼接到模型请求里。
• .tools()是 Agent 的“动手能力”，不传工具，模型就只能胡猜。
• 工具调用异常时，模型会根据返回的错误信息尝试重新调用或给出替代方案。

Agent 和普通 ChatClient 的核心区别在于：Agent 会动态规划。用户问“订单 1001 现在什么状态，顺便看看能不能改地址”，模型会按需依次调用订单查询、地址修改等工具，而不是简单回复一段话。

在做 Agent 时，一定要设置最大迭代轮次和超时时间，防止模型在工具调用循环里出不来。如果模型反复调用同一个失败工具，应该中断并返回兜底文案。

如果是复杂流程编排，Spring AI Alibaba 提供了 Graph 能力和更上层的工作流编排。团队规模大、业务流程复杂时，可以关注这些扩展方向。

11. 接口 API 与批量任务落地

Spring AI 的集成方法可以直接通过 Controller 暴露成 HTTP API，接入现有业务系统。

@RestController @RequestMapping("/api/ai") public class AiController { private final ChatService chatService; private final OrderAgentService orderAgentService; public AiController(ChatService chatService, OrderAgentService orderAgentService) { this.chatService = chatService; this.orderAgentService = orderAgentService; } @PostMapping("/chat") public Map<String, String> chat(@RequestBody ChatRequest request) { String content = chatService.chat(request.message()); return Map.of("content", content); } @PostMapping("/agent/order") public Map<String, String> orderAgent(@RequestBody AgentRequest request) { String content = orderAgentService.chatWithAgent(request.userId(), request.message()); return Map.of("content", content); } }

配套定义请求体：

public record ChatRequest(String message) {} public record AgentRequest(String userId, String message) {}

流式输出也是生产环境常用能力。用 Flux 返回流式结果：

@PostMapping(value = "/chat/stream", produces = "text/plain; charset=utf-8") public Flux<String> chatStream(@RequestBody ChatRequest request) { return chatClient.prompt() .user(request.message()) .stream() .content(); }

前端可以用 SSE 或 fetch stream 逐字展示，体验接近流式大模型应用。

批量任务方面，Spring AI 本身不限制并发方式，可以结合 Java 线程池、Spring Batch 或消息队列实现。一个简单的批量生成示例：

ExecutorService executor = Executors.newFixedThreadPool(4); List<String> prompts = List.of( "给新产品写三条短文案", "给促销活动写三封营销邮件标题", "给用户回访写一段话术" ); List<CompletableFuture<String>> futures = prompts.stream() .map(prompt -> CompletableFuture.supplyAsync( () -> chatService.chat(prompt), executor)) .toList(); List<String> results = futures.stream() .map(CompletableFuture::join) .toList();

批量任务必须关注限流和错误重试。如果外部模型接口有 QPS 限制，需要在代码里加入重试和退避策略。也要注意内存占用，大批量任务建议走消息队列落库，而不是全部堆在 JVM 内存里。

12. 资源占用与性能观察

Spring AI 本身的资源占用并不高，它的主要开销在两部分：外部模型 API 调用延迟，以及本地模型推理资源。

如果使用 OpenAI 或国内大模型 API：

• 延迟主要看网络、服务端排队和模型响应速度。
• 长文本输入会显著增加首字延迟。
• 并发请求由 Java 侧线程池、模型服务端限流共同决定。
• 需要重点监控 Token 消耗，这直接影响成本。

如果使用 Ollama 本地模型：

• 显存占用由模型大小和推理服务配置决定。7B 量级的量化模型可能占用 6-8GB 显存，实际以 Ollama 日志和nvidia-smi为准。
• CPU 推理很慢，生成长文本时响应时间会明显拉长。
• 显存不足时，Ollama 会降低推理速度或抛出显存不足错误。

建议在压测阶段关注四个指标：

Spring AI 的响应结果中带有 Token 用量信息，可以在日志里记录：

// 用 ChatResponse 接收完整响应，打印 token 用量 ChatResponse response = chatClient.prompt() .user("你好") .call() .chatResponse(); if (response.getMetadata() != null) { Integer inputTokens = response.getMetadata().getUsage().getPromptTokens(); Integer outputTokens = response.getMetadata().getUsage().getCompletionTokens(); log.info("input={}, output={}", inputTokens, outputTokens); }

注意，不同模型的 Usage 返回可能不完全一致，有的模型不返回 Token 统计。这个信息只能作为参考。

降低资源占用和成本的方向：

• 根据任务复杂度选择不同模型，小任务用小模型。
• 限制maxTokens输出长度。
• 使用 ChatMemory 时设置 maxMessages，防止上下文无限增长。
• 对不涉及上下文的问答，不要携带历史消息。

13. 常见问题与排查方法

MCP 相关问题是初学者最容易踩坑的重灾区。建议先拿一个最简单的 MCP Server 示例跑通，再接入自己的工具，不要一上来就配置复杂的多 Server 连接。不同 Spring AI 版本的 MCP 配置属性有变化，网上老文章写的不一定适用于当前版本。

14. 最佳实践与生产建议

从“能跑通”到“能上线”，中间还有一段距离。以下实践是 Spring AI 项目落地时比较关键的建议。

第一，版本管理是最重要的事。Spring AI 的 API 演进速度快，项目里必须用 BOM 锁定版本，并把版本升级作为独立任务处理。不要用网上搜到的散装依赖坐标拼接，直接以官方 Initializr 生成为准。

第二，工具方法是安全边界。所有@Tool注解的方法都必须假设输入不可信。模型传入的参数可能包含恶意内容、错误类型、越权语义。每个工具方法都要校验参数、校验调用者权限、记录审计日志。

第三，Agent 必须设置执行边界。限制最大工具调用轮次，限制单轮响应 Token 长度，限制模型能访问的工具范围。不要让所有工具都默认对模型开放。

第四，MCP 服务端要管理好暴露面。MCP Server 本质上是一个可控的外部调用入口，不要无鉴权地暴露在公网。测试环境与生产环境的 MCP Server 要隔离。

第五，数据合规不要忘。不要向外部模型服务发送敏感个人信息、未脱敏的客户资料、商业机密。如果必须使用外部模型，要做数据脱敏和内容审核。涉及版权素材、人脸、声音等场景时，必须确认授权，这条也适用于任何通过 MCP 接入的外部能力。

第六，上线前要做批量效果回归。AI 应用的问题是“大多数时候正确，少数时候离谱”。把测试集跑一遍，记录输出质量、工具调用准确率、结构化输出失败率，再根据结果调整 Prompt 和工具描述。

15. 总结与下一步

Spring AI 2.0 体系里，最值得先跑通的一条链路是：一个 Spring Boot 工程 + 一个模型接入 + 一个@Tool方法 + 一个 Controller 接口。这条链路通了，后面再扩展 MCP、Skills、Agent 都是顺理成章的事。

最容易踩的坑有三个：版本不匹配、工具描述不规范、MCP 配置照搬旧文章。第一周学习建议把重心放在多模型接入和 Tools 上，不要一上来就追 Agent 编排。

接下来可以继续扩展的方向：接入真实 MCP Server 补充外部数据；用结构化输出对接业务表单；使用 Spring AI Alibaba 的 Graph 能力做复杂流程编排；把批量任务迁到消息队列。先跑通最小链路，后面要接什么工具、组什么样的 Agent 就不难了。

建议把这篇内容收藏备用，动手写代码时对着核心示例改，比自己从官网文档爬坑要快得多。