nageoffer/ragent

后端程序员转型 AI 工程师的第一站

     

🚀 什么是 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 的支持！

---

💡 为什么学习 AI 项目

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

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

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

⚠️ RAG / Agent 常见误区

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

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

🏗️ Ragent 核心设计

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

这个分层不是为了炫技，而是把业务编排、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。

✨ 项目质量怎么样？

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

1. 规模与完整度

• 后端：7 个 Maven 模块，分别承载基础能力、知识库问答、Agent、启动装配和示例 MCP 服务。
• 前端：知识库管理、意图树、Agent 技能、会话与系统配置。
• 数据与测试：平台业务表与 mcp-server 演示业务表分别维护，Java 测试覆盖检索、Agent 工具调用和服务端协议。

代码量本身不等于质量，但这些模块组成了数据进入系统—检索生成答案—展示证据—收集反馈—追踪与审计的完整闭环，另有 Agent ReAct 推理与工具调用链路，不仅是简单的 API 示例。

2. 工程质量

• 模块边界：通用基础设施、AI 能力、RAG 业务、Agent 引擎和 MCP 服务相互隔离，替换模型或存储实现不会侵入问答编排。
• 配置防错：模型档位、候选能力和检索漏斗在启动阶段完成一致性校验，错误配置直接失败而不是静默降质。
• 并发治理：10 个专用线程池隔离负载，TTL 保证用户与 Trace 上下文跨线程传递。
• 关键路径测试：覆盖模型路由、检索预算、会话摘要、入库 Pipeline、MCP 和 Agent 上下文与长期记忆。
• 工程约束：统一响应、错误码和异常处理，认证、幂等、线程安全 SSE 与 Spotless 格式化均已落到代码。

项目中大量应用并发线程，建议配合社群里的 oneThread 动态线程池框架 搭配学习收获更多。

3. 代码是怎么组织的

AI 写代码很强，但掌舵的还是程序员。能不能接着扩展、改一处会不会牵一片，取决于动手前有没有把结构定好。项目里的设计模式，每个都对着一个具体问题：

下一节的那些扩展点，基本都是这些模式带来的结果。

4. 可扩展性

核心能力通过接口、注册表和配置隔离，新增实现可以复用现有编排、容错、日志和管理能力：

扩展的改动主要收敛在新实现和配置中，不必复制一套检索、会话或 Trace 主链路。

5. 生产级特性

这里的生产级特性指项目已经实现生产环境会遇到的关键机制，而不只是功能能跑：

6. 完整控制台

Ragent 提供覆盖普通用户与管理员用户的 React 控制台，不只是聊天页面，也把检索证据和运维入口暴露出来。

系统通过多轮 AI 辅助设计优化，在保证功能完整性的同时，提供更加现代化和友好的交互体验。

6.1 用户问答界面

v2 面向 Agent 任务提供完整的执行过程视图。模型思考、工具调用、并行批次和最终回答会按时间线实时展开，任务做了什么、耗时多久都能直接看到。

遇到下单、修改数据等写操作时，系统会先展示操作内容和原始参数，用户确认后才会继续执行。

v1 保留更轻量的知识问答界面，适合检索路径固定、以答案和引用为主的场景。用户可以直接输入问题，也可以通过示例问题快速体验，并按需开启深度思考模式。

• 支持自然语言输入
• 支持示例问题快速填充
• 支持深度思考模式

用户提交问题后，模型会实时生成回答结果，并提供良好的阅读体验：

• 支持 Markdown 格式渲染
• 支持图片内容展示
• 支持代码高亮显示
• 支持回答来源、原文预览和推荐追问
• 支持回答评价（点赞 / 点踩）

6.2 管理后台

管理员可以通过后台查看仪表盘，管理知识库与 Chunk、知识图谱、意图树、查询词映射、入库任务、示例问题、用户和系统设置，并查看 RAG Trace 与业务变更日志。

控制台围绕实际使用和排障流程持续打磨，在功能完整的基础上，尽量把复杂能力做得直观、易用。

7. 和市面上项目的区别

Ragent 定位于 Java AI 应用的源码级工程参考，重点是完整链路、生产保障和二次开发能力。

❓ 常见问题答疑

一句话：学完 Ragent，你既能跟面试官聊 RAG/Agent 的技术深度，也能证明自己的 Java 工程化水平。

🌟 为什么开源？

原因很简单：对项目质量足够自信。架构设计、代码实现、工程规范，每一行都经得起审视。好不好你 clone 下来自己看——目录结构、提交记录、注释规范，全是明牌。

如果屏幕前的亦菲/彦祖觉得项目还不错，点个 Star 支持一下，这是对开源作者最好的认可！