nageoffer/ragent

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

     

🚀 什么是 Ragent AI？

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

• 混合检索：向量、关键词、知识图谱、联网搜索并行召回，支持去重、RRF 融合与 Rerank。
• 问题理解：支持查询词映射、问题重写与拆分、树形意图识别和多知识库路由。
• 模型与工具：支持模型档位、首包探测、熔断降级，以及 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 常见误区

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

常规 RAG 的流程如下：

🏗️ Ragent 核心设计

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

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

一次用户提问，在 Ragent AI 服务里经过的核心链路如下所示：

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

✨ 项目质量怎么样？

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

1. 规模与完整度

• 后端：4 个 Maven 模块，约 6.1 万行 Java 主代码、553 个主代码文件。
• 前端：约 2.75 万行代码、27 个页面级 TSX 文件。
• 数据与测试：22 张业务表、30 个 Java 测试文件、84 个 @Test 测试点。

代码量本身不等于质量，但这些模块组成了数据进入系统—检索生成答案—展示证据—收集反馈—追踪与审计的完整业务闭环，不仅是简单的 API 示例。

2. 工程质量

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

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

3. 可扩展性

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

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

4. 生产级特性

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

5. 完整控制台

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

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

5.1 用户问答界面

用户访问 Ragent 首页后，可在输入框中直接输入问题发起问答，同时支持开启深度思考模式以获得更高质量的回答。

输入框下方提供示例问题标签，用户点击即可自动填充问题，方便快速体验系统能力。

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

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

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

5.2 管理后台

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

为了避免传统系统常见的毛坯界面体验，Ragent 的控制台经过多轮 AI 辅助设计与优化，逐步迭代完善，最终呈现出当前简洁、美观且实用的界面效果。

6. 和市面上项目的区别

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

❓ 常见问题答疑

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

🌟 为什么开源？

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

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