Modular RAG MCP Server

一个可插拔、可观测的模块化 RAG（检索增强生成）服务框架，通过 MCP（Model Context Protocol）协议对外暴露工具接口，支持 Copilot / Claude 等 AI 助手直接调用。同时也是一份专为大模型相关岗位学习与面试求职设计的实战项目与配套教学资源。

---

📖 目录

• 项目概述
• 分支说明
• 快速开始
• 谁适合用这个项目 & 怎么用
• 简历参考
• 常见问题
• 后续安排

---

🏗️ 项目概述

这个项目是什么

本项目将 RAG 面试中最常见的核心环节——检索（Hybrid Search + Rerank）、多模态视觉处理（Image Captioning）、RAG 评估（Ragas + Custom）、生成（LLM Response）——以及当下热门的应用协议 MCP（Model Context Protocol） 串联为一个完整的、可运行的工程项目。

项目的一大亮点是极易适配到你自己的业务中。得益于全链路可插拔架构，你可以快速将它结合到自己已有的项目里，无论你的背景和需求如何，都能找到适合自己的使用方式。具体的使用策略会在后文 谁适合用这个项目 & 怎么用 中详细展开。

不只是项目，更是一整套思路

比这个项目本身更有价值的，是它背后蕴含的一整套工程化思路：

• 如何编写 DEV_SPEC（开发规格文档）来驱动开发
• 如何用 Skill 基于 Spec 自动完成代码编写
• 如何用 Skill 进行自动化测试、打包、环境配置
• 如何基于可插拔架构进行扩展（比如扩展到 Agent）

学会了思路，你可以自己做全新的项目和扩展。以上每一步的具体做法、设计思路，在笔记中都有对应的视频讲解，建议配合观看。

核心能力一览

| 模块 | 能力 | 说明 | |------|------|------| | 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 — 最干净的完整代码

• 始终只有 1 个 commit，包含项目的最新完整代码
• 适合人群：
  • 想要快速体验项目完整功能的同学
  • 时间紧迫，想要快速拿到一个项目去面试、跳过中间开发过程的同学
  • 想要直接在该项目基础上做二次扩展的同学
• 使用方式：克隆后直接运行 Setup Skill 即可体验

dev — 保留完整开发记录

• 代码与 main 完全一致，但保留了完整的 commit 历史
• 记录了从零开始逐步构建的每一步过程，包含大量中间节点
• 适合人群：想了解项目是如何一步步从零搭建起来的同学，可以通过 commit 历史回溯开发思路

clean-start — 干净起点，从零开始

• 仅包含工程骨架（Agent Skills + DEV_SPEC），所有任务进度清零
• 保留了完整的 Skill 配置，可以使用 Agent 辅助开发
• 适合人群：
  • 时间充分、想要从头开发的同学（强烈建议）
  • 想要体验完整工作流的同学：写 Spec → 拆任务 → 写代码 → 写测试 → 迭代优化
  • 甚至可以基于自己的理解重新设计架构，用自己的思路实现，深度理解每一个模块
  • 使用我们讲的所有对应思路（Spec 驱动开发、测试先行、可插拔架构等）来完成整个项目
• 核心理念：整个项目的代码编写是 让 AI 基于 DEV_SPEC 来自动完成的，你自己不需要手写代码。AI 通过 Skill 读取 Spec 中的任务定义、架构设计和接口规范，自动生成符合规格的代码。这个思路请参考笔记对应视频讲解：5.1 项目 Skills 使用：如何让 AI 使用 Skill 遵循 DEV_SPEC 完成代码。

---

🚀 快速开始

1. 克隆项目

git clone <repo-url>
cd Modular-RAG-MCP-Server

2. 一键配置（Setup Skill）

本项目提供了 Setup Skill 一键完成所有环境配置，包括：Provider 选择 → API Key 配置 → 依赖安装 → 配置文件生成 → Dashboard 启动。

在 VS Code 中打开项目，通过 Copilot / Claude 对话框输入：

setup

Agent 会自动引导你完成全部配置流程。

💡 如果不熟悉 Skill 的使用方式，请观看配套笔记中的 Setup Skill 使用讲解视频。

---

🎯 谁适合用这个项目 & 怎么用

大家的背景不同——有的校招、有的社招；基础也不同——有的有 AI 项目经验、有的是转方向。因此对于这个项目的使用策略也应该不同，请一定灵活使用，切忌生搬硬套。

不过有一点是通用的：整套项目背后的思路——如何写 Spec 快速拉起一个项目、如何用 Skill 驱动 AI 自动编码和测试——这些工程化方法论适用于任何项目，值得所有人参考学习。

对于项目本身在不同场景下的使用策略，我会提供一些具体的例子，并以我自己的亲身经历展开——如果是我自己，面对不同的情况，我会怎么使用这个项目——给大家作为参考。

1. 纯学习 RAG —— 把项目当作 RAG 全流程的学习材料

这个项目本身就是一个完整的 RAG 系统，可以作为学习 RAG 的配套实战项目。

我最开始学习 RAG 的时候，看的是这本书：《大模型RAG实战：RAG原理、应用与系统构建》（汪鹏、谷清水、卞龙鹏等人工智能领域专家编著）。你完全可以结合这本书来学习 RAG，书中涉及的典型环节——检索、生成、向量数据库、分块策略、重排序等——其实不管你看哪本 RAG 相关的书，核心内容都是这些。

这个项目就是把这些步骤串起来了，所以它可以作为一个通用的 RAG 全流程项目来学习整个过程。你可以配这本书，我相信你也可以配其它的 RAG 书籍，因为流程是通的。面试 RAG 其实也无非是这些过程的组合、原理，以及在实际中遇到的困难和优化。

2. 时间紧迫 —— 缺一个项目拿去面试

如果你现在没有 AI 相关项目、急需一个项目去面试，那么可以：

1. 直接使用本项目，克隆 main 分支，用 Setup Skill 跑起来
2. 结合 Resume Writer Skill 写自己的简历（Skill 会根据你的背景定制化生成项目描述）
3. 尝试理解项目，跑通核心流程，结合我后续总结的该项目面试问题，先去面试
4. 随着面试深入理解、扩展项目——面试本身就是最好的学习驱动力

比如现在 3 月份，需要找暑期实习的同学，时间紧迫——先写上去，一边面试一边学习，有时间再扩展。解决你着急面试没有项目的燃眉之急。思路就是：先写上去 → 去面试 → 根据面试反馈改进项目。

通常暑期实习从 3 月到 7 月都有机会。找到了实习、有了一个大模型项目经验后，再以此为跳板继续学习——7~10 月秋招，甚至到明年 3 月春招，你有大量的时间持续积累。现在开始虽然看起来有点晚，但其实不晚。如果你能保持学习节…