1. 项目背景与核心价值Yu-AI-Agent 是一个基于 Spring Boot 3 和 Java 21 技术栈构建的 AI 智能体开发实践项目核心功能包含AI 恋爱大师对话应用和ReAct 模式自主规划智能体两大模块。这个项目最初源自编程导航平台的 AI 开发实战课程经过开发者 My-Riley 的二次开发与功能扩展形成了一个完整的 AI 应用开发样板工程。在实际应用中这类 AI 智能体系统可以解决几个关键问题为缺乏专业情感咨询资源的用户提供 24 小时在线的恋爱指导通过 RAG检索增强生成技术确保情感建议的专业性和准确性验证 ReAct 框架在复杂任务规划中的实际应用效果技术层面上项目完整演示了从大模型接入到业务落地的全流程包括Spring AI 框架的深度集成自定义工具调用链路的实现对话记忆持久化方案知识库构建与检索增强智能体决策逻辑编排2. 技术架构解析2.1 整体架构设计项目采用典型的分层架构前端层Vue3 Vite 接入层Spring MVC REST API 业务层Spring AI 核心组件 自定义业务服务 数据层PGVector 文件存储 工具层7 种内置工具 MCP 扩展服务关键设计决策包括选择 Spring Boot 3.5 作为基础框架充分利用 Java 21 的虚拟线程特性提升并发性能采用 PGVector 而非 Chroma 等专业向量数据库降低运维复杂度实现 SSEServer-Sent Events协议支持满足实时交互需求设计 MCPModel Context Protocol协议实现模块间通信2.2 核心组件实现2.2.1 AI 恋爱大师模块该模块的核心类 LoveAppService 实现了以下关键功能public class LoveAppService { private final ChatClient chatClient; private final VectorStore vectorStore; // RAG 增强的对话方法 public String chatWithContext(String userId, String message) { // 1. 检索相关上下文 ListDocument docs vectorStore.similaritySearch(message); // 2. 构建提示词 Prompt prompt new Prompt(new SystemMessageTemplate(docs), new UserMessage(message)); // 3. 调用大模型 return chatClient.call(prompt).getResult().getOutput().getContent(); } }技术亮点使用 Kryo 序列化实现对话记忆持久化相比 JSON 节省 40% 存储空间通过自定义 Advisor 实现对话重读Re-Reading机制支持生成结构化恋爱分析报告2.2.2 ReAct 智能体实现YuManus 智能体的核心继承体系BaseAgent (基础响应) └── ToolCallAgent (工具调用) └── ReActAgent (ReAct 框架) └── YuManus (业务定制)关键执行流程接收用户请求生成初始思考Thought选择合适工具Action执行并观察结果Observation循环直至任务完成public class ReActAgent extends ToolCallAgent { protected String executePlan(String input) { while (!isTaskComplete()) { String thought generateThought(input); Tool tool selectTool(thought); String observation tool.execute(extractParams(thought)); input refineInput(observation); } return formatResult(input); } }3. 关键技术实现细节3.1 RAG 知识库构建恋爱知识库的处理流程文档采集整理 Markdown 格式的恋爱指南单身/恋爱/已婚三个场景文本分割采用递归字符分割策略设置 512 tokens 的块大小向量化使用 DashScope 的 text-embedding-v2 模型生成嵌入存储存入 PGVector 并建立 IVFFlat 索引关键配置示例spring: ai: vectorstore: pgvector: dimensions: 1536 distance-type: cosine index-type: ivfflat3.2 工具调用机制项目实现了 7 种标准工具WebSearchTool基于 SearchAPI 的联网搜索WebScrapingTool使用 Jsoup 实现网页抓取FileOperationTool文件系统操作ResourceDownloadTool支持 HTTP/FTP 的资源下载TerminalOperationTool受限的本地命令执行PDFGenerationTool利用 iText 生成报告TerminateTool智能体终止开关工具注册流程Configuration public class ToolConfig { Bean public Tool webSearchTool() { return Tool.builder() .name(webSearch) .description(Search the web for up-to-date information) .function(webSearchFunction()) .build(); } private FunctionWebSearchRequest, String webSearchFunction() { return request - { // 调用 SearchAPI 实现 return searchApiClient.search(request.query()); }; } }4. 部署与调优实践4.1 本地开发环境搭建硬件建议配置CPU4 核以上建议 Apple M1/Intel i7内存16GBRAG 处理时需要大量内存磁盘SSD 预留 20GB 空间软件依赖安装步骤安装 JDK 21建议使用 SDKMAN! 管理版本配置 PostgreSQL 15 并安装 PGVector 扩展安装 Maven 3.9可选配置 Ollama 本地模型服务4.2 性能优化技巧对话缓存策略Cacheable(value chatCache, key #userId : #message.hashCode()) public String cachedChat(String userId, String message) { return loveAppService.chat(userId, message); }向量检索优化调整 IVFFlat 的 nlist 参数建议设为 records/1000对高频查询建立部分索引智能体超时控制Bean public ThreadPoolTaskExecutor agentExecutor() { ThreadPoolTaskExecutor executor new ThreadPoolTaskExecutor(); executor.setAwaitTerminationSeconds(30); executor.setWaitForTasksToCompleteOnShutdown(true); return executor; }5. 典型问题排查指南5.1 常见错误与解决方案问题现象可能原因解决方案工具调用超时MCP 服务未启动检查 yu-image-search-mcp-server 日志向量检索结果不相关嵌入模型不匹配确认使用的嵌入模型与索引时一致SSE 连接中断Nginx 代理配置问题添加proxy_read_timeout 300s;记忆丢失Kryo 序列化版本冲突清理旧存储文件或实现版本迁移5.2 调试技巧智能体推理过程可视化agent.setObservationCallback(obs - { log.debug([Agent Observation] {}, obs); });启用 Spring AI 调试日志logging.level.org.springframework.aiDEBUGPGVector 查询分析EXPLAIN ANALYZE SELECT content FROM vector_store ORDER BY embedding [0.1,...,0.2] LIMIT 3;6. 扩展开发建议新增知识领域在 resources/document 添加新 Markdown 文档实现自定义文档加载器继承 DocumentReader注册新的检索器Retriever开发新工具public class WeatherTool implements Tool { Override public String execute(String input) { // 调用天气 API return weatherApi.getCurrent(input); } }多智能体协作实现 AgentCoordinator 协调器使用 CompletableFuture 实现并行任务设计冲突解决策略这个项目最值得借鉴的是其完整的智能体开发范式特别是在工具调用与任务规划方面的实现。我在实际开发中发现合理设置工具超时建议 5-10 秒能显著提升系统稳定性。另外对于中文场景建议在 PGVector 中使用 pg_trgm 扩展辅助相似度计算
