A community-driven registry for Claude, Cursor, Windsurf, Cline & more. Not affiliated with Anthropic.
Are you the author? Sign in to claim
A modular RAG (Retrieval-Augmented Generation) system with MCP Server architecture. Using Skill to make AI follow each s
一个可插拔、可观测的模块化 RAG（检索增强生成）服务框架，通过 MCP（Model Context Protocol）协议对外暴露工具接口，支持 Copilot / Claude 等 AI 助手直接调用。同时也是一份专为大模型相关岗位学习与面试求职设计的实战项目与配套教学资源。
本项目将 RAG 面试中最常见的核心环节——检索（Hybrid Search + Rerank）、多模态视觉处理（Image Captioning）、RAG 评估（Ragas + Custom）、生成（LLM Response）——以及当下热门的应用协议 MCP（Model Context Protocol） 串联为一个完整的、可运行的工程项目。
项目的一大亮点是极易适配到你自己的业务中。得益于全链路可插拔架构，你可以快速将它结合到自己已有的项目里，无论你的背景和需求如何，都能找到适合自己的使用方式。具体的使用策略会在后文 谁适合用这个项目 & 怎么用 中详细展开。
比这个项目本身更有价值的，是它背后蕴含的一整套工程化思路：
学会了思路，你可以自己做全新的项目和扩展。以上每一步的具体做法、设计思路，在笔记中都有对应的视频讲解，建议配合观看。
| 模块 | 能力 | 说明 |
|---|---|---|
| Ingestion Pipeline | PDF → Markdown → Chunk → Transform → Embedding → Upsert | 全链路数据摄取，支持多模态图片描述（Image Captioning） |
| Hybrid Search | Dense (向量) + Sparse (BM25) + RRF Fusion + Rerank | 粗排召回 + 精排重排的两段式检索架构 |
| MCP Server | 标准 MCP 协议暴露 Tools | query_knowledge_hub、list_collections、get_document_summary |
| Dashboard | Streamlit 六页面管理平台 | 系统总览 / 数据浏览 / Ingestion 管理 / 摄取追踪 / 查询追踪 / 评估面板 |
| Evaluation | Ragas + Custom 评估体系 | 支持 golden test set 回归测试，拒绝"凭感觉"调优 |
| Observability | 全链路白盒化追踪 | Ingestion 与 Query 两条链路的每一个中间状态透明可见 |
| Skill 驱动全流程 | 从编写到测试、打包、配置一键完成 | auto-coder / qa-tester / package / setup 等 Skill 覆盖完整开发生命周期（笔记中每个 Skill 的使用和设计思路均有讲解，请参考配套视频） |
🔌 全链路可插拔架构：LLM / Embedding / Reranker / Splitter / VectorStore / Evaluator 每一个核心环节均定义了抽象接口，支持"乐高积木式"替换，通过配置文件一键切换后端，零代码修改。
🔍 混合检索 + 重排：BM25 稀疏检索解决专有名词精确匹配 + Dense Embedding 解决同义词语义匹配，RRF 融合后可选 Cross-Encoder / LLM Rerank 精排，平衡查全率与查准率。
🖼️ 多模态图像处理：采用 Image-to-Text 策略，利用 Vision LLM 自动生成图片描述并缝合进 Chunk，复用纯文本 RAG 链路即可实现"搜文字出图"。
📡 MCP 生态集成：遵循 Model Context Protocol 标准，可直接对接 GitHub Copilot、Claude Desktop 等 MCP Client，零前端开发，一次开发处处可用。
📊 可视化管理 + 自动化评估：Streamlit Dashboard 提供完整的数据管理与链路追踪能力，集成 Ragas 等评估框架，建立基于数据的迭代反馈回路。
🧪 三层测试体系：Unit / Integration / E2E 分层测试，覆盖独立模块逻辑、模块间交互、完整链路（MCP Client / Dashboard）。
🤖 Skill 驱动全流程：内置 auto-coder（自动编码）、qa-tester（自动测试）、package（清理打包）、setup（一键配置）等 Agent Skill，覆盖从代码编写到测试、打包、部署的完整开发生命周期。每个 Skill 的使用方法和设计思路在笔记的项目部分均有讲解视频，可参考学习。
📖 详细架构设计、模块说明和任务排期请参阅 DEV_SPEC.md
本项目提供三个分支，面向不同使用场景，请根据自身需求选择：
main — 最干净的完整代码dev — 保留完整开发记录main 完全一致，但保留了完整的 commit 历史clean-start — 干净起点，从零开始git clone <repo-url>
cd Modular-RAG-MCP-Server
本项目提供了 Setup Skill 一键完成所有环境配置，包括：Provider 选择 → API Key 配置 → 依赖安装 → 配置文件生成 → Dashboard 启动。
在 VS Code 中打开项目，通过 Copilot / Claude 对话框输入：
setup
Agent 会自动引导你完成全部配置流程。
💡 如果不熟悉 Skill 的使用方式，请观看配套笔记中的 Setup Skill 使用讲解视频。
大家的背景不同——有的校招、有的社招；基础也不同——有的有 AI 项目经验、有的是转方向。因此对于这个项目的使用策略也应该不同，请一定灵活使用，切忌生搬硬套。
不过有一点是通用的：整套项目背后的思路——如何写 Spec 快速拉起一个项目、如何用 Skill 驱动 AI 自动编码和测试——这些工程化方法论适用于任何项目，值得所有人参考学习。
对于项目本身在不同场景下的使用策略，我会提供一些具体的例子，并以我自己的亲身经历展开——如果是我自己，面对不同的情况，我会怎么使用这个项目——给大家作为参考。
这个项目本身就是一个完整的 RAG 系统，可以作为学习 RAG 的配套实战项目。
我最开始学习 RAG 的时候，看的是这本书：《大模型RAG实战：RAG原理、应用与系统构建》（汪鹏、谷清水、卞龙鹏等人工智能领域专家编著）。你完全可以结合这本书来学习 RAG，书中涉及的典型环节——检索、生成、向量数据库、分块策略、重排序等——其实不管你看哪本 RAG 相关的书，核心内容都是这些。
这个项目就是把这些步骤串起来了，所以它可以作为一个通用的 RAG 全流程项目来学习整个过程。你可以配这本书，我相信你也可以配其它的 RAG 书籍，因为流程是通的。面试 RAG 其实也无非是这些过程的组合、原理，以及在实际中遇到的困难和优化。
如果你现在没有 AI 相关项目、急需一个项目去面试，那么可以：
main 分支，用 Setup Skill 跑起来比如现在 3 月份，需要找暑期实习的同学，时间紧迫——先写上去，一边面试一边学习，有时间再扩展。解决你着急面试没有项目的燃眉之急。思路就是：先写上去 → 去面试 → 根据面试反馈改进项目。
通常暑期实习从 3 月到 7 月都有机会。找到了实习、有了一个大模型项目经验后，再以此为跳板继续学习——7~10 月秋招，甚至到明年 3 月春招，你有大量的时间持续积累。现在开始虽然看起来有点晚，但其实不晚。如果你能保持学习节奏，从现在到明年 3 月，学习整整一年，校招上岸大模型方向绝对没有问题。关键在于你自己能不能保持这么长时间的学习力。
你可以把这个项目作为起点，根据自己的发展方向进行针对性扩展。DEV_SPEC 中也写了扩展方向，这里列几个常见的：
每个人发展方向不一样——就像项目配套的 Resume Writer Skill，它写简历的时候会先问你的背景和情况。你定位大模型应用开发工程师、RAG 工程师、全栈工程师，校招、社招的要求都是不一样的（具体大模型不同岗位介绍和技术栈可以看笔记的大模型岗位介绍部分），所以需要自己进行针对性扩展。
强烈建议：不管你什么背景、怎么扩展，你大概率需要结合自己的业务来写简历。所以至少试一下——把你自己领域的文档（金融、法律、医疗，或者你的业务文档）丢进去，看一下检索效果。如果效果不好，再去调整和改进。这个过程本身就是最好的学习，也是面试时最有说服力的实战经验。
如果你时间充足，我建议你从 clean-start 分支开始，甚至在 clean-start 的基础上删掉 DEV_SPEC，从文档设计开始，一点点体验：
文档设计 → AI 写代码 → 改进迭代 → 测试 → 部署
整个过程的方法论。其中 DEV_SPEC 怎么写、Skill 怎么设计，这些都在笔记项目部分的对应视频中有讲解。你可以重新设计文档、改进文档，甚至直接做 Agent 方向的东西，来走完整个流程。
这样做你会学习到开发一个项目的完整思路。这套方法最大的好处是下限极低——几乎你都能设计出来、完成整个项目。这样你既学会了思路，又学会了过程，而且项目可以高度定制。群里已经有很多朋友都这么做了。
这其实也是一种很好的策略，我自己可能也会用这种方式。以我亲身经历现身说法：
我之前找工作时，其实已经有 2 个 Agent 项目了，只是 RAG 流程跑得很粗。我简历上大概的写法是"Agent 项目做了啥，其中涉及了一些 RAG 的知识"。面试的时候，面试官多少都会问 RAG 的内容，然后我和他讲，但因为之前项目的 RAG 系统很浅——其实就是做了一个基本的 Embedding 向量匹配，没有粗排、重排等策略——所以面试官一问就比较浅。
做了这个项目之后，一种处理方式是把本项目的 RAG 能力融入到之前的 Agent 项目中，在简历上不作为独立项目，而是作为 Agent 项目的一部分来描述。例如：
"……项目中使用自研的模块化 RAG 系统进行知识检索，采用 BM25 + Dense Embedding 混合召回并通过 RRF 融合排序，结合 Cross-Encoder 重排序提升 Top-K 精准度；支持多模态文档处理（PDF 解析 + Image Captioning），通过 MCP 协议暴露标准化工具接口供 Agent 调用。集成 Ragas 评估框架，建立 Golden Test Set 回归测试机制，持续优化检索质量……"
这样你原有的 Agent 项目就有了 RAG 深度，面试官再问你就有东西可讲了。
大模型产品经理面试越来越多地会考 RAG 相关知识，有些公司甚至要求产品经理自己写一个 POC（Proof of Concept）再交给开发。这个项目和背后的方法论，完全可以帮你做到这一点。
为什么 PM 可以用：
具体怎么做：
main 分支，用 Setup Skill 跑起来，体验完整流程💡 笔记中也提供了 Vibe Coding 相关教程（如 Tina Huang 老师的讲解），非常适合非技术背景的同学参考，用 AI 快速构建原型。
最后我想独立提一点（这一点适用于上面所有情况）：
所有项目的深入优化不是一步到位的。
如果你是转行，项目都是自己做的，多少会遇到面试官觉得你项目浅的问题。我之前也提到过这一点，但不用害怕：
项目深度不是入行的必要条件。 我去年拿了 6 个 offer，其中包括大厂 offer，即使这样，还是有面试官觉得我项目浅。面试还会考虑很多其他方面——理论基础、算法能力、背景匹配、知识广度等等。不要因为觉得自己转行项目浅就觉得自己转不了。
项目是在不断优化和深入的。 面试官说你项目浅，你听他的反馈，一定能听出来他为什么觉得浅——比如觉得你数据不够复杂，那你就造一些复杂数据；觉得你图片处理太简单，那你可以扩展多模态策略。我自己也是在面试过程中不断往项目里加东西：我之前做的 Agent 项目，随着面试推进，我往里加了部署、训练、反思数据、评估模块——整个过程都是随着面试同步进行的。
给自己预留多一点面试时间，一边面试，一边改进和加深。 所以这里就又提到了整套项目的思路——学会这些思路，你才能持续扩展，而且扩展的门槛很低，都是想好想法让 AI 写嘛，所以不用怕。
说一个真实数据：这个项目从立项到完成，是我下班后用了大概 2 个月时间做的，期间我还要上班、做自媒体、自媒体也有其他内容要产出。所以我希望你不要完全指望这个项目作为一个不用扩展就特别深入的项目，特别是社招的同学。但反过来想——两个月的下班时间就做出了这些，如果你学会了这套方法，自己扩展的速度会有多快？
方法都有了，所有的方案、过程、记录都有留档和视频讲解。最终一定要靠你自己去扩展、迭代，做成最适合你自己的项目。
⚠️ 强烈建议：请使用项目内置的 Resume Writer Skill 来生成你的简历项目经历，而不是直接复制下面的示例。
简历项目经历一定是针对性的——需要结合你自己的业务背景、目标岗位、技术侧重来定制化生成。下面的示例仅用于展示 Skill 的输出效果和不同场景的写法参考，直接照搬没有任何意义。
如何使用 Resume Writer Skill：在 VS Code 中通过 Copilot / Claude 对话框输入
写简历或resume，Skill 会引导你完成画像采集并自动生成四段式简历。具体使用方式和设计思路请参考笔记中 项目部分的视频讲解。
Skill 采用 "写作原则 + 项目亮点 + 用户画像 = 定制化简历" 的三角模型，流程如下：
以下为 Skill 基于"校招、RAG 方向、通用框架模式"生成的示例输出：
智能知识检索与问答系统 | 2024.09 - 2025.02 | 独立设计与开发
背景：针对企业级知识库场景中文档分散、检索精度不足、AI 应用难以接入私有知识的共性痛点，设计并实现了模块化 RAG 检索框架。
目标：构建基于混合检索 + MCP 协议的智能知识问答系统，实现精准语义检索与 AI Agent 直接调用私有知识库的能力，将文档问答准确率提升至 90% 以上。
过程：
结果：系统支撑 5000+ 篇文档的实时语义检索，检索准确率（Hit Rate@10）达 92%，端到端查询延迟控制在 800ms 以内，三层测试体系（Unit / Integration / E2E）覆盖 1200+ 测试用例。
技术栈：Python / LangChain / ChromaDB / BM25 / Cross-Encoder / MCP Protocol / Streamlit / Ragas / Azure OpenAI
以下为 Skill 基于"社招、Agent 方向、Windows 平台开发业务背景"生成的示例输出（将 RAG 能力融入已有 Agent 项目）：
Windows 平台智能知识助手 | 2024.06 - 2025.02 | 核心开发
背景：在 Windows 平台开发团队中，版本发布相关信息（Release Notes、变更日志、补丁公告、兼容性说明等）分散于多个 Wiki、文档仓库和内部系统，工程师排查版本差异或回答客户问题时需跨系统翻找，现有关键词搜索无法理解语义，导致检索效率低、信息遗漏频发。
目标：为团队构建基于 Agent + RAG 架构的智能知识助手，实现跨系统文档的语义检索与自动问答，通过 MCP 协议集成至工程师日常工具链（VS Code / Claude Desktop），将文档查找时间缩短 60% 以上。
过程：
结果：系统覆盖团队 8000+ 篇技术文档，工程师日均文档查询时间从 15 分钟缩短至 3 分钟，检索准确率 Hit Rate@10 达 90%，已通过 MCP 协议接入 3 个内部 AI 工具，累计处理查询 2 万+ 次。
技术栈：Python / Agent / Tool Calling / RAG / BM25 / Dense Retrieval / Cross-Encoder / MCP Protocol / ChromaDB / Streamlit / Ragas / Skill-Driven Development / Azure OpenAI
以下为 Skill 基于"社招转 AI、后端/架构方向、金融合规业务背景"生成的示例输出：
合规智能文档检索系统 | 2024.10 - 2025.02 | 设计与主导开发
背景：在某金融机构合规部门，法规文件和内部政策文档持续增长至万级规模，合规团队在审查和咨询场景中需要快速定位特定条款，但现有全文搜索系统只能精确匹配关键词，无法理解"反洗钱"与"AML"等语义近义表达，条款定位效率低下。
目标：设计并实现模块化 RAG 检索系统，将语义检索能力引入合规文档管理流程，支持近义词、跨语言条款匹配，目标将合规条款定位准确率提升至 90% 以上。
过程：
结果：系统上线后支撑 12000+ 篇合规文档的实时语义检索，条款定位准确率从 68% 提升至 91%，单次查询延迟控制在 700ms，合规团队文档审查效率提升约 50%。
技术栈：Python / 可插拔架构 / 工厂模式 / BM25 / Dense Retrieval / RRF / Cross-Encoder / ChromaDB / MCP Protocol / Streamlit / Ragas / Skill-Driven Development / Azure OpenAI
💡 使用提醒与重要说明：
1. 关于放大策略：Resume Writer Skill 中内置了我设计的放大策略——AI 会在合理范围内对你的项目经历进行包装和放大（例如量化指标、业务规模等）。这是我允许的，也是简历写作的正常做法。但这意味着：生成简历后，你必须想清楚面试官可能针对每一条追问什么、你该怎么回答。Skill 在生成简历的同时会自动给出 3-5 条面试追问预测，请认真准备这些问题。
2. 把简历当作实践清单：简历中写到的每一个技术点，你都应该真正去试一下。比如简历写了"检索准确率提升 XX%"——那你就应该在自己的数据上跑一下，看看实际效果如何，过程中遇到了什么问题，你是怎么调优解决的。这些实践经验才是面试时真正有说服力的内容，也是你真正学到东西的过程。简历里没涉及到的部分（比如你没试过多模态、没跑过评估），也可以以此为契机去做代码实验。
3. 生成的是初稿，请务必结合自身情况修改：Skill 生成的简历是初稿，不是终稿。你需要根据自己的实际情况进行调整——哪些技术你确实深入用过、哪些只是了解、哪些数据需要换成你自己的。简历写作有一条铁律：写在简历上的东西，你一定要会讲。即使某个点是放大的，你也要想清楚面试官会怎么问、你怎么自圆其说。说不清楚的东西宁可不写，写上去就要能扛住追问。
4. 方法比模板更重要：整个简历编写的思路是我的——包括放大策略、四段式结构（背景 → 目标 → 过程 → 结果 → 技术栈）、亮点匹配逻辑等，这些都沉淀在 Resume Writer Skill 里。如果你有自己更信任的简历模板，或者你对项目做了扩展修改，完全可以去修改 Skill 本身来适配。学会这套"用 Skill 沉淀方法论、让 AI 按规则执行"的逻辑，比简历本身更有价值——这个思路可以复用到你未来任何项目的简历编写中。
5. 强烈建议写上 Skill 驱动全流程：我个人的意见是，Skill 驱动全流程开发这个闭环，适合写在任何人的简历上。Skill 是当下非常热门的方向，已经是面试中的必考内容，很多公司内部也在研究如何用 Skill 加速项目构建。讲清楚你是如何使用 Skill 完成整个项目从编码 → 测试 → 修复 → 配置 → 打包的完整闭环，这本身就是一个比较创新和前沿的亮点，面试官会对此印象深刻。关于 Skill 相关内容在面试中怎么讲、怎么回答追问，我后面也会提供一些例子给大家参考。
非常简单——直接问 AI 帮你完成即可。
项目从架构设计上使用了工厂模式（Factory Pattern），Provider 的扩展和切换非常方便。你只需要理解内部原理就会发现：不同 API 本质上都是类似的 HTTP 请求，甚至大多数都遵循 OpenAI 的请求格式，切换起来特别容易。
具体操作方式有两种：
原理说明：项目的
src/libs/下的 LLM、Embedding、Reranker 等模块都使用工厂模式，新增一个 Provider 只需要：① 新增一个 Provider 类；② 在工厂注册；③ 更新settings.yaml配置。AI 完全可以自动完成这些步骤。
这两个模块的框架代码已经搭好，但尚未经过完整测试，感兴趣的同学可以自行完善：
| 模块 | 状态 | 需要做什么 |
|---|---|---|
| 自定义评估（Custom Evaluator） | 框架已有，未测试 | 定义评估方法，准备对应的测试数据集 |
| Cross-Encoder Reranker | 框架已有，未测试 | 需要下载本地重排模型（如 cross-encoder/ms-marco-MiniLM-L-6-v2） |
这些 AI 都能帮你写出来。把需求描述清楚，AI 可以帮你实现评估方法、准备数据、下载模型并完成集成测试。完成这些扩展对面试也是加分项，体现了你的独立扩展能力。
这不是一个经过广泛测试的生产级项目，而是一个面试导向的实战项目。 遇到报错是正常的。
直接问 AI 帮你扩展即可。
项目的 Loader 层采用了可插拔的抽象设计（BaseLoader），目前默认实现了 PDF Loader。如果你需要支持 Word、Markdown、HTML 等其他格式，整体架构已经设计好了扩展点，让 AI 帮你新增一个对应的 Loader 实现就可以了。
比如告诉 AI："帮我新增一个 Word 文档的 Loader，参考现有的 PDF Loader 实现"，AI 完全可以搞定。
本项目是一个 MCP Server，可以集成到任何支持 MCP 协议的 AI 工具和 Agent 中。我的演示中已经集成到了 GitHub Copilot 和 Cursor 中，你同样可以集成到 Claude Code 或其他支持 MCP 框架的工具。
如何集成？非常简单——问 AI。
本质上就是给不同的工具写一个 MCP 的配置文件：
当然，也推荐你去理解 MCP 协议的原理——了解 Server 和 Client 之间是如何通信的、Tool 是怎么注册和调用的。这些在面试中也是加分项。
上述大多数问题（Provider 切换、模块扩展、Bug 修复、架构理解）AI 都能解决：
多问 AI，让它指导你。这也是这个项目想要传达的核心理念之一——学会与 AI 协作开发。
我后续会去学习大模型算法、训练方向，会把一些笔记和思路总结在笔记中。因此对于这个项目，不会无限扩展功能或修复 Bug，但会非常乐意持续做的事情是：
本项目配有完整的配套学习资源，包括：
👉 请关注小红书：不转到大模型不改名 获取以上所有资源。
A Jetbrains IDE IntelliJ plugin aimed to provide coding agents the ability to leverage intelliJ's indexing of the codeba
Run Claude Code as an MCP server so any agent can delegate coding tasks to it
@microsoft✓ OfficialBrowser automation using accessibility snapshots instead of screenshots