Spring AI实战：从恋爱大师到ReAct自主规划智能体开发指南

项目概览：2000+ Star 的 Java AI 实战教程

在 AI 应用开发逐渐成为 Java 开发者必备技能的当下，一个名为 yu-ai-agent 的开源项目在 GitHub 上迅速走红，短时间内收获超过 2199 颗 Star 和 508 个 Fork。该项目由知名技术博主鱼皮（liyupi）发起，基于 Spring Boot 3 + Java 21 + Spring AI 技术栈，构建了两个完整的 AI 应用——AI 恋爱大师和 ReAct 模式自主规划智能体 YuManus，为 Java 开发者提供了一条从入门到实战的 AI 开发学习路径。

Spring AI 技术架构与核心特性

现代化的技术选型

项目采用了当前 Java 生态中最前沿的技术组合：

• Spring Boot 3：最新一代 Spring 框架，原生支持 GraalVM，性能显著提升
• Java 21：LTS 版本，支持虚拟线程、模式匹配等现代语言特性
• Spring AI：Spring 官方推出的 AI 集成框架，为 Java 开发者提供了统一的 AI 大模型接入抽象层

这套技术栈的选择颇具前瞻性。Spring AI 作为 Spring 生态对 AI 时代的回应，正在快速迭代中，其设计理念与 Spring 一贯的风格一致——通过抽象和标准化降低开发复杂度，让开发者可以用熟悉的 Spring 编程模型来构建 AI 应用。

Spring AI 框架深度解析

Spring AI 是 Spring 官方于 2023 年底正式推出的 AI 集成框架，其设计灵感来源于 Python 生态中的 LangChain，但完全遵循 Spring 的编程范式。它提供了 ChatClient、EmbeddingClient 等核心抽象接口，支持 OpenAI、Anthropic、Ollama、阿里通义千问等多种大模型后端的无缝切换。开发者只需更改配置即可在不同模型间迁移，无需修改业务代码。Spring AI 还内置了对向量存储（如 PGVector、Milvus、Chroma）的支持，以及结构化输出解析、函数调用等高级特性。这意味着 Java 开发者终于拥有了一个与 LangChain 对标的、原生于 Spring 生态的 AI 开发框架。

Java 21 虚拟线程对 AI 应用的赋能

Java 21 引入的虚拟线程（Virtual Threads，即 Project Loom）对 AI 应用开发具有重要意义。AI 应用通常涉及大量的网络 I/O 操作——调用大模型 API、查询向量数据库、访问外部工具接口等，这些操作都是 I/O 密集型的。传统的平台线程模型下，每个阻塞的 I/O 操作都会占用一个操作系统线程，导致并发能力受限。虚拟线程允许在单个平台线程上运行数百万个轻量级线程，极大提升了 AI 应用在高并发场景下的吞吐量，特别适合需要同时处理大量用户对话请求的 Agent 系统。结合 Spring Boot 3 对虚拟线程的原生支持，开发者只需一行配置即可启用这一特性。

覆盖的核心知识体系

项目涵盖了 AI 应用开发中几乎所有关键技术点：

• AI 大模型接入：通过 Spring AI 统一接口对接各类大语言模型
• Prompt 工程与优化：系统化的提示词设计与调优方法论
• RAG 检索增强生成：结合外部知识库提升模型回答质量
• 向量数据库：为 RAG 提供高效的语义检索能力
• Tool Calling 工具调用：让 AI 具备调用外部工具和 API 的能力
• MCP 模型上下文协议：Anthropic 提出的标准化模型交互协议
• AI Agent 智能体开发：构建具备自主规划和执行能力的智能体

RAG 检索增强生成技术原理

RAG（Retrieval-Augmented Generation）是解决大语言模型「幻觉」问题和知识时效性问题的关键技术。其工作流程分为两个阶段：索引阶段，将外部文档切分为文本块（Chunk），通过 Embedding 模型转换为高维向量并存入向量数据库；检索生成阶段，将用户查询同样转换为向量，在向量数据库中进行相似度检索（通常使用余弦相似度或内积），找到最相关的文本块，将其作为上下文注入到 Prompt 中，再交由大模型生成回答。这样模型的回答就有了可靠的知识来源，大幅降低了胡编乱造的概率。在企业应用中，RAG 常用于客服问答、文档检索、知识管理等场景。

向量数据库技术细节

向量数据库是专门为高维向量的存储和相似性搜索而设计的数据库系统。与传统关系型数据库基于精确匹配不同，向量数据库支持近似最近邻（ANN）搜索，能在毫秒级别从数百万条向量中找到语义最相似的结果。主流的向量数据库包括 Milvus（开源分布式）、Pinecone（云原生）、Chroma（轻量级）、PGVector（PostgreSQL 扩展）等。其底层索引算法包括 HNSW（分层可导航小世界图）、IVF（倒排文件索引）等，在检索精度和速度之间做出平衡。Spring AI 对这些向量数据库提供了统一的 VectorStore 抽象，开发者可以根据项目规模和部署环境灵活选择。

Tool Calling 工具调用机制

Tool Calling（也称 Function Calling）是大语言模型与外部世界交互的核心机制。其工作原理是：开发者在调用模型时，除了传入用户消息外，还传入一组工具的描述（包括工具名称、功能说明、参数的 JSON Schema）。模型在生成回复时，如果判断需要使用某个工具，会输出一个结构化的工具调用请求（而非自然语言文本），包含工具名和参数值。应用层接收到这个请求后，执行实际的工具调用（如查询数据库、调用 API），将结果返回给模型，模型再基于工具返回的结果生成最终回答。OpenAI 于 2023 年 6 月率先推出此功能，现已成为行业标准。在 Spring AI 中，开发者只需使用 @Tool 注解标记方法即可将其注册为可供模型调用的工具。

MCP 模型上下文协议详解

MCP（Model Context Protocol）是 Anthropic 于 2024 年 11 月提出的开放标准协议，旨在解决 AI 模型与外部数据源和工具之间的连接碎片化问题。在 MCP 出现之前，每个 AI 应用都需要为每个外部服务编写定制化的集成代码，形成 M×N 的复杂度。MCP 通过定义统一的客户端-服务器架构，将这一复杂度降为 M+N。MCP Server 暴露工具（Tools）、资源（Resources）和提示模板（Prompts），MCP Client 通过标准协议发现和调用这些能力。这类似于 USB 协议统一了外设接口，MCP 正在统一 AI 应用的工具调用接口。目前已有大量 MCP Server 实现，覆盖文件系统、数据库、搜索引擎、代码仓库等常见服务，Spring AI 也已提供了对 MCP 协议的原生支持。

两大 AI 实战项目详解

AI 恋爱大师：Spring AI 入门实战

作为入门级项目，AI 恋爱大师应用展示了如何利用 Spring AI 快速构建一个垂直领域的 AI 对话应用。这类项目虽然看似轻松有趣，但背后涉及的技术要素——Prompt 工程、对话管理、上下文维护、RAG 知识增强——都是企业级 AI 应用开发中的核心能力。

通过这个项目，开发者可以掌握 Spring AI 的基础用法，理解如何通过精心设计的 System Prompt 来塑造 AI 的角色和行为，以及如何利用 RAG 技术注入领域知识以提升回答的专业性。System Prompt 的设计是 Prompt 工程中最关键的环节之一，它定义了模型的角色定位、回答风格、知识边界和行为约束，直接决定了 AI 应用的用户体验质量。

YuManus：基于 ReAct 模式的自主规划智能体

YuManus 是项目的重头戏，它是对当前热门的 AI Agent 框架 Manus 的 Java 实现。该智能体采用 ReAct（Reasoning + Acting） 模式，这是目前最主流的 Agent 架构范式之一。

Manus Agent 框架背景

Manus 是 2025 年初由中国团队推出的通用 AI Agent 产品，因其展示的强大自主任务执行能力而引发广泛关注。Manus 能够自主浏览网页、编写代码、操作文件系统、部署应用等，被视为 AGI 方向的重要探索。其核心架构采用了多 Agent 协作模式，结合了 ReAct 推理循环和丰富的工具集。由于 Manus 本身并未完全开源，社区涌现了大量复现项目，如 OpenManus（Python 实现）和本文介绍的 YuManus（Java 实现），这些项目帮助开发者理解 Agent 的核心架构设计。

ReAct 模式的学术背景与工作原理

ReAct 模式源自 2022 年由 Google Research 和普林斯顿大学联合发表的论文《ReAct: Synergizing Reasoning and Acting in Language Models》。该论文证明，让语言模型交替生成推理轨迹（Reasoning Traces）和任务特定的动作（Actions），能够显著提升模型在复杂任务上的表现。与纯推理（Chain-of-Thought）相比，ReAct 能与外部环境交互获取信息；与纯行动（Act-only）相比，ReAct 的推理步骤提供了可解释性和错误纠正能力。这一模式已成为 AutoGPT、BabyAGI、LangChain Agent 等主流 Agent 框架的理论基础。

ReAct 模式的核心思想是让 AI 在执行任务时交替进行「推理」和「行动」：

1. Reasoning（推理）：分析当前状态，制定下一步计划
2. Acting（行动）：调用工具或执行操作
3. Observation（观察）：获取行动结果，作为下一轮推理的输入

这种循环使得 AI Agent 能够处理复杂的多步骤任务，具备自主规划和动态调整的能力。例如，当用户要求「帮我调研某个技术方案并生成报告」时，Agent 会自主分解任务为多个子步骤——搜索相关资料、阅读文档、对比方案、撰写报告——每一步都基于上一步的结果动态调整策略。YuManus 通过 Tool Calling 和 MCP 协议，可以调用各种外部工具，实现真正意义上的「自主规划智能体」。

Java 开发者为什么要学 Spring AI Agent 开发

填补 Java AI 生态空白

长期以来，AI 应用开发的主流语言是 Python，LangChain、LlamaIndex 等框架几乎垄断了 AI 开发工具链。Java 开发者在 AI 浪潮中一度处于被动地位。Spring AI 的出现和 yu-ai-agent 这类实战项目的涌现，正在改变这一局面。

对于数量庞大的 Java/Spring 开发者群体而言，无需切换技术栈就能进入 AI 开发领域，这无疑降低了巨大的学习门槛。据统计，全球有超过 900 万 Java 开发者，其中大量从事企业级应用开发。这些开发者已经熟悉 Spring 的依赖注入、AOP、声明式事务等编程模型，Spring AI 让他们可以用完全相同的思维方式来构建 AI 应用，而不必从零学习 Python 生态的异步编程、包管理等全新概念。

企业级 AI 应用的参考范本

相比 Python 生态中大量的脚本式 Demo，基于 Spring Boot 构建的 AI 应用天然具备企业级特性——依赖注入、配置管理、安全框架、监控体系等都可以无缝复用。这使得从原型到生产的路径更加顺畅。

具体而言，Spring Boot 的 Actuator 提供了开箱即用的健康检查和指标监控，Spring Security 可以为 AI 接口添加认证授权，Spring Cloud 的服务治理能力可以管理多个 AI 微服务的调用链路，而 Micrometer + Prometheus + Grafana 的可观测性方案可以监控模型调用的延迟、Token 消耗和错误率。这些在生产环境中不可或缺的能力，在 Python 生态中往往需要额外引入多个独立组件来实现。

Spring AI 学习路径建议

对于想要入门 AI 应用开发的 Java 开发者，建议按照以下路径循序渐进：

1. 基础阶段：先理解 Spring AI 的核心抽象（ChatClient、Prompt、Message 等概念），完成 AI 恋爱大师项目，掌握基本的模型调用和对话管理
2. 进阶阶段：深入学习 RAG 架构，理解文档切分策略、Embedding 模型选择、向量数据库部署，以及 Tool Calling 的注册和调用机制
3. 高级阶段：研究 ReAct 模式和 Agent 架构，理解推理循环的实现、工具编排、错误处理和超时控制，完成 YuManus 项目
4. 拓展阶段：了解 MCP 协议的服务端和客户端实现，探索多 Agent 协作（如 Supervisor 模式、层级式 Agent）和生产部署方案（包括流式响应、Token 限流、成本控制等）

总结

yu-ai-agent 项目的价值不仅在于提供了两个可运行的 AI 应用 Demo，更在于它系统性地串联了 AI 应用开发的完整知识链条。在 AI 能力正在从「锦上添花」变为「核心竞争力」的今天，掌握 Spring AI 和 Agent 开发技术对于 Java 开发者的职业发展具有重要的战略意义。Spring AI 生态虽然仍在早期阶段，但其背后有 Spring 社区的强大支撑，未来发展值得期待。随着 Spring AI 1.0 正式版的发布和更多企业的采用，Java 在 AI 应用开发领域的地位将持续提升，而现在正是 Java 开发者布局 AI 技能的最佳时机。

核心要点

• 项目基于 Spring Boot 3 + Java 21 + Spring AI 构建，为 Java 开发者提供了完整的 AI 应用开发实战路径
• 包含两个实战项目：AI 恋爱大师（入门级）和 YuManus 自主规划智能体（进阶级），覆盖从基础到高级的 AI 开发技能
• YuManus 采用 ReAct 模式实现自主规划智能体，是热门 AI Agent 框架 Manus 的 Java 实现
• 覆盖 Prompt 工程、RAG 检索增强、向量数据库、Tool Calling、MCP 协议等 AI 开发核心技术
• 填补了 Java 生态在 AI 应用开发领域的实战教程空白，GitHub 已获 2199 Star