ragent

🚀 什么是 Ragent AI？

Ragent 是一个面向 Agentic RAG 演进的生产级 Java AI 应用平台，覆盖从文档入库到智能问答的完整链路。

• 混合检索：向量、关键词、知识图谱、联网搜索并行召回，支持去重、RRF 融合与 Rerank。
• 问题理解：支持查询词映射、问题重写与拆分、树形意图识别和多知识库路由。
• 模型与工具：支持模型档位、首包探测、熔断降级，以及 AgentScope 的 MCP 工具发现与调用。
• 会话记忆：最近 N 轮消息结合持久化摘要，控制 Token 成本并保留关键上下文。
• 流量保护：Redis 公平排队与分布式并发控制，避免突发请求压垮模型服务。
• 知识闭环：提供可编排入库 Pipeline、远程刷新、回答溯源、用户反馈、Trace 和管理后台。

生产落地智能体会踩的坑，这里都有对应方案，一套经过真实场景锤炼的工程实践，系统补全 RAG / Agent / MCP 等知识，面试写进简历聊得起来。

🧭 快速导航

觉得不错？先点个 Star 收藏，所有链接都会在新标签页打开，不会离开本页 👇

	链接	说明
📖	官网文档	Ragent AI 完整文档
🚀	在线体验	无需部署，直接体验 Ragent AI
⚡	快速启动	本地搭建 Ragent AI 前后端项目
📝	简历怎么写	项目如何写到简历上
💡	为什么不用 Spring AI / LangChain4j	技术选型的思考

🤝 贡献

Ragent AI 仍在持续迭代中，欢迎参与共建，一起把项目打磨得更好。 感谢各位亦菲、彦祖们对 Ragent AI 的贡献：

❤️ 赞助与支持

感谢以下伙伴对 Ragent AI 的支持！

---

💡 为什么学习 AI 项目

AI 这波浪潮，Java 程序员已经躲不过去了。

不管你现在做的是业务系统还是中间件，面试的时候多多少少都会被问到 AI 相关的东西。RAG 是什么？Agent 怎么实现？用过 MCP 吗？这些问题越来越高频。可以说，AI 已经从加分项变成了必答题。

但说实话，对于大多数应用层的开发者来说，去死磕大模型的微调、蒸馏、Transformer 原理，性价比并不高。真正实用的，是掌握 RAG 和 Agent 这些应用层的东西——能落地、能出活、面试也能聊得起来。

1. 校招现状

简历上清一色的 CRUD 项目——商城、外卖、博客，面试官早就审美疲劳了。当别人还在写基于 SpringBoot 的 XX 管理系统时，你简历上有一个完整的 AI 项目，区分度直接拉满。而且大厂校招越来越看重候选人对新技术的敏感度，AI 项目能直接证明你的学习能力和技术视野。

2. 社招现状

2024 年以来，几乎所有技术团队都在往 AI 方向靠。很多公司已经把有 AI 相关经验写进了 JD 里。你可能 Java/Go 写得很溜，但面试官会问：你对 LLM 了解多少？RAG 做过没有？向量检索怎么实现的？答不上来，直接少了一个谈薪的筹码。

说白了，学 AI 项目的核心原因就三个：

1. 简历差异化。从 RAG 知识问答到 ReAct 多轮推理、MCP 工具调用和 Skills 技能应用，Ragent V2 覆盖完整实战链路。把实际完成的功能、解决的问题和验证结果写进简历，体现你的 AI 应用开发能力。
2. 面试有东西聊。Workflow 与 Agent 如何选型、ReAct 如何决策和调用工具、Skills 如何按需加载、上下文如何压缩、长期记忆如何跨会话保留，以及写操作的人工确认、Langfuse 对推理、工具调用和 Token 的追踪，都能结合源码与设计取舍展开聊。
3. 实际工作用得上。从有依据的知识问答，到调用外部系统、执行多步任务并确认关键操作，混合检索、MCP、上下文管理、模型容错和链路追踪，都是构建可调试、可扩展、运行有保障的 AI 应用所需的能力。

3. 问题是，怎么学？

很多人跟着 B 站视频或者 GitHub 上的开源项目撸了一遍，以为自己懂了。结果面试一问深的，直接懵了。原因很简单：那些 Demo 级别的项目，和企业真正要用的东西，差距太大了。

还有些同学报了训练营，发现清一色是 Python。语言不熟、生态不通，学完感觉收获有限，回到 Java 这边还是不知道怎么下手。就算用 Spring AI 或者 LangChain4j，版本迭代太快，低版本功能缺，高版本升级约等于重写，也是一肚子苦水。

基于这些问题，我决定做一个 Agentic RAG 实战项目，名字叫 Ragent。

这个项目覆盖 RAG 全链路和 Agent 智能体两条主线，同时涉及 MCP/Skills 集成。更重要的是，它不是我看了几篇文章拼凑出来的玩具——我在公司实际落地过 Agentic RAG 系统，解决过信息孤岛、知识检索、效率提升这些真实的业务问题。所以 Ragent 的复杂度，就是企业级项目该有的复杂度。

学完之后，你可以放心大胆地跟面试官讲：企业里就是这么做的。

⚠️ RAG / Agent 常见误区

市面上打着 RAG / Agent 旗号的项目不少，但很多要么是玩具级 Demo，要么是概念包装。在学之前，先把这几个误区理清楚，避免踩坑。

传统 RAG 的基本链路如下，Agent 在此基础上增加了任务决策与工具执行：

1. 调个 API 就算会 RAG / Agent 了

很多教程的套路是：调一下 OpenAI 的 Embedding 接口，往向量数据库里塞点数据，再用 LLM 生成答案——完事了。这顶多算跑通了一个 Demo。Agent 也一样，接上 MCP、让模型调一次工具，只是起点。

真正的 RAG 系统要考虑的问题多得多：文档怎么切分效果最好？检索召回率不够怎么办？多路召回怎么融合排序？幻觉怎么控制？到了 Agent，还要考虑工具选错、调用失败后怎么处理，什么时候继续推理、什么时候结束任务。这些才是面试官会追问的点。

跑通 Demo 和做出能上线的系统之间，差的不是代码量，是对每个环节的深入理解。

2. RAG 只是“检索 + 生成”，Agent 只是多调几次工具

Retrieval-Augmented Generation 这个名字确实容易让人觉得就是检索加生成。但实际工程中，从 RAG 问答到 Agent 执行任务，至少涉及这些环节：

• 数据处理：PDF、Word、PPT、网页，格式五花八门，光是解析成干净文本就是一堆脏活。PDF 里的表格、扫描件、双栏排版，每一个都是坑。
• 分块策略：切太大检索不精准，切太小上下文丢失。按段落切、按固定字数切、按语义切，不同文档可能需要不同策略。
• 问题重写：用户问“报销咋整”，你拿这四个字去检索，效果能好吗？多轮对话里用户说“怎么申请”，不补上下文系统根本不知道在问啥。
• 意图识别：用户是想查知识库，还是要调用业务系统？是闲聊还是正经提问？走错了路，答案肯定不对。
• 检索策略：纯向量检索对精确匹配很弱，用户问一个订单号，向量检索可能完全找不到。混合检索怎么融合、top-k 选多少、要不要重排序，都是取舍。
• 会话记忆：20 轮对话全塞给模型？Token 成本扛不住。只带最近几轮？可能丢关键上下文。Agent 还会积累工具结果和推理上下文，需要裁剪、摘要压缩，并按需保留跨会话的长期记忆。
• 任务执行：ReAct 根据工具结果继续决策，Skills 按需提供任务指导；查几次、用什么工具、何时停止，都要有执行边界。

固定问答可以用 Workflow，需要动态规划的任务再交给 Agent，V2 中两条链路并存。每一环都有坑，每一环都值得深挖。面试的时候能把这些讲清楚，比背概念有用得多。

3. 接入框架和 MCP 就是企业级

框架和 MCP 能简化模型与工具接入，但接通能力之后，还有一系列工程问题要解决。企业场景下要面对的是：

• 大规模文档的增量更新，不可能每次全量重建索引
• 多租户隔离和权限控制，不同部门看到的知识库不一样
• 高并发下的检索性能，模型调用的成本控制和容错
• 请求风控，防止用户套取敏感信息或恶意攻击
• 模型负载均衡，多供应商切换和降级策略
• 工具参数校验、失败处理，以及写操作的人工确认
• 可观测性，通过 Langfuse 等工具追踪推理、工具调用、耗时与 Token，结合效果评估和用户反馈定位问题

这些问题不能只靠框架的 QuickStart 解决，面试和实际业务都会追问具体设计。

4. 只关注模型，忽略工程能力

RAG / Agent 项目的效果既取决于模型，也取决于工程化能力。同样的模型，检索策略不同、Prompt 设计不同、分块粒度不同，再加上工具选择和上下文管理的差异，最终效果可以天差地别。

举个例子：用户对电商助手说“上周买的耳机能退吗？能退就帮我申请”。Agent 需要先确认具体订单，通过 MCP 工具查询订单状态，再检索知识库中的退货政策，根据结果判断是否符合条件；信息不足时继续追问，符合条件时展示申请内容，经用户确认后调用售后工具提交。这就是 Agentic RAG：根据任务和执行结果动态决定下一步，把知识检索与业务操作串起来。背后的检索准确性、工具参数校验、用户权限和重复提交防护，都需要工程设计，换个更强的模型也不能省略。

面试中能把这些工程细节讲清楚的人，远比只会说“我用了某个最强模型”的人有说服力。

🏗️ Ragent 核心设计

采用前后端分离的模块化单体架构，后端按职责分为七个 Maven 模块：

模块	职责
infra-ai	Chat / Embedding / Rerank / VLM 模型客户端、模型档位、路由、首包探测、健康状态与降级
system	用户认证与审计日志，位于各业务引擎之下的系统支撑域
rag	RAG 问答、知识库、入库 Pipeline、意图树、检索、会话及管理端 API
agent	AgentScope ReAct 执行引擎，接入知识检索与 MCP 工具，支持技能、记忆和人工确认
bootstrap	启动装配层，仅含启动类与主配置
framework	统一响应与异常、幂等、分布式 ID、MQ 适配、SSE 与跨节点流式取消等基础能力
mcp-server	基于 MCP Java SDK 的独立工具示例服务，内置通用工具（日期、天气、联网搜索）、企业助手和比特严选商城三组工具

这个分层不是为了炫技，而是把业务编排、AI 供应商差异和通用基础设施隔离开。切换模型、向量库或对象存储时，核心问答流程不需要跟着重写。

一次提问在服务里怎么走，v1 和 v2 是两套路子。

MCP 客户端只在 agent 模块中装配，使用 AgentScope 连接和发现工具，服务地址配置在 agent.mcp.servers。意图树中的 MCP 节点仍指定可用工具及确认规则；Workflow 只识别知识库和系统意图，不连接 MCP 服务。mcp-server 是独立示例服务，使用与 AgentScope 一致的 MCP Java SDK 版本实现服务端协议。

• v1 是 Workflow 编排，路径写死在代码里：问题重写、意图识别、多路召回、组装生成，一步接一步走完。
• v2 换成 Agentic 架构，路径由模型自己定：知识检索、MCP 工具和 Skills 技能都变成它手里的工具，查不查、查几次、查完接着干什么，在 ReAct 循环里边推理边决定。所以链路比 v1 长，也不再是一条直线。

下图是 v2 的核心流程。实际项目代码中的逻辑比图上更复杂，落地过程中还涉及很多细节和优化。

两套并存，不是谁替代谁。问答类知识助手需求走 v1 更快也更可控，要规划、要动手操作的场景才交给 v2。

✨ 项目质量怎么样？

这里的质量不靠一张架构图来证明，而是看代码边界、测试、故障处理和运维闭环是否真实存在。以下数据按当前仓库统计，代码行数包含注释和空行。

This is the beginning of the README. Read the rest at the original. Read the full README ↗