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）

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

核心能力一览

技术亮点

🔌 全链路可插拔架构：LLM / Embedding / Reranker / Splitter / VectorStore / Evaluator 每一个核心环节均定义了抽象接口，支持"乐高积木式"替换，通过配置文件一键切换后端，零代码修改。

🔍 混合检索 + 重排：BM25 稀疏检索解决专有名词精确匹配 + Dense Embedding 解决同义词语义匹配，RRF 融合后可选 Cross-Encoder / LLM Rerank 精排，平衡查全率与查准率。

🧠 智能查询编排 (Query Orchestration)：服务端内置查询编排能力，支持三种模式——Direct（直通检索）、Synonym Expansion（同义词/别名扩展，融入 BM25 稀疏检索）、Logical Decomposition（LLM 自动拆解复杂问题为多子查询 → 并行检索 → RRF 合并去重 → 全局精排）。全部可配置、可关闭，通过 Streamlit Dashboard 可观测每一步决策。

🖼️ 多模态图像处理：采用 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

🚀 快速开始

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 会自动引导你完成全部配置流程。

3. 独立启动 Streamlit Dashboard

如果只想单独启动可视化管理面板（不通过 Setup Skill），在项目根目录执行：

.venv/bin/python -m streamlit run src/observability/dashboard/app.py --server.port 8501
# 或
uv run streamlit run src/observability/dashboard/app.py --server.port 8501

启动后访问 http://localhost:8501 即可使用。

Dashboard 提供六个功能页面：

📝 简历参考

⚠️ 强烈建议：请使用项目内置的 Resume Writer Skill 来生成你的简历项目经历，而不是直接复制下面的示例。

简历项目经历一定是针对性的——需要结合你自己的业务背景、目标岗位、技术侧重来定制化生成。下面的示例仅用于展示 Skill 的输出效果和不同场景的写法参考，直接照搬没有任何意义。

如何使用 Resume Writer Skill：在 VS Code 中通过 Copilot / Claude 对话框输入 写简历 或 resume，Skill 会引导你完成画像采集并自动生成四段式简历。具体使用方式和设计思路请参考笔记中 项目部分的视频讲解。

Resume Writer Skill 工作方式

Skill 采用 "写作原则 + 项目亮点 + 用户画像 = 定制化简历" 的三角模型，流程如下：

1. 画像采集：Skill 会询问你的目标岗位（RAG Engineer / Backend / Agent 等）、业务背景、技术侧重、特殊要求
2. 亮点匹配：根据你的岗位方向，从项目 10 大技术亮点中筛选 3-5 个最匹配的写入 bullet points
3. 四段式生成：严格按 背景 → 目标 → 过程 → 结果 结构输出，每条 bullet 遵循"动词开头 + 技术细节 + 量化效果"
4. 面试追问预测：自动生成 3-5 条面试官可能的追问，帮你提前准备

示例一：校招 · RAG Engineer 方向

以下为 Skill 基于"校招、RAG 方向、通用框架模式"生成的示例输出：

智能知识检索与问答系统 | 2024.09 - 2025.02 | 独立设计与开发

背景：针对企业级知识库场景中文档分散、检索精度不足、AI 应用难以接入私有知识的共性痛点，设计并实现了模块化 RAG 检索框架。

目标：构建基于混合检索 + MCP 协议的智能知识问答系统，实现精准语义检索与 AI Agent 直接调用私有知识库的能力，将文档问答准确率提升至 90% 以上。

过程：

• 设计 BM25 + Dense Embedding 混合召回架构，通过 RRF 融合排序平衡查全率与查准率，结合 Cross-Encoder 重排序将 Top-10 命中率提升约 25%
• 构建全链路 Ingestion Pipeline（PDF 解析 → Markdown → 语义分块 → Metadata 增强 → Embedding → Upsert），集成 Vision LLM 实现图片自动描述并缝合进 Chunk，复用纯文本链路即可"搜文字出图"
• 实现 LLM / Embedding / Reranker / VectorStore 全链路可插拔架构，定义统一抽象接口，通过配置文件一键切换后端 Provider，支持 4+ LLM Provider 零代码切换
• 集成 Ragas + Custom 双评估体系，建立 Golden Test Set 回归测试机制，覆盖 Faithfulness / Relevancy / Recall 等维度，拒绝"凭感觉"调优
• 基于 Skill 驱动全流程开发，通过 auto-coder / qa-tester / setup / package 等 5 大 Agent Skill 覆盖编码、测试、配置、打包完整生命周期，2 个月业余时间完成 68 个子任务的全量交付

结果：系统支撑 5000+ 篇文档的实时语义检索，检索准确率（Hit Rate@10）达 92%，端到端查询延迟控制在 800ms 以内，三层测试体系（Unit / Integration / E2E）覆盖 1200+ 测试用例。

技术栈：Python / LangChain / ChromaDB / BM25 / Cross-Encoder / MCP Protocol / Streamlit / Ragas / Azure OpenAI

示例二：社招 · 已有 Agent 项目，融入 RAG 深度

以下为 Skill 基于"社招、Agent 方向、Windows 平台开发业务背景"生成的示例输出（将 RAG 能力融入已有 Agent 项目）：

Windows 平台智能知识助手 | 2024.06 - 2025.02 | 核心开发

背景：在 Windows 平台开发团队中，版本发布相关信息（Release Notes、变更日志、补丁公告、兼容性说明等）分散于多个 Wiki、文档仓库和内部系统，工程师排查版本差异或回答客户问题时需跨系统翻找，现有关键词搜索无法理解语义，导致检索效率低、信息遗漏频发。

目标：为团队构建基于 Agent + RAG 架构的智能知识助手，实现跨系统文档的语义检索与自动问答，通过 MCP 协议集成至工程师日常工具链（VS Code / Claude Desktop），将文档查找时间缩短 60% 以上。

过程：

• 设计 Agent + RAG 分层架构，Agent 端负责意图识别与 Tool Calling，RAG 端提供 BM25 + Dense Embedding 混合召回 + Cross-Encoder 精排的两段式检索能力，通过 MCP 协议暴露标准化工具接口供 Agent 调用
• 实现全链路 Ingestion Pipeline，支持 PDF / Markdown 多格式文档解析，集成 Vision LLM 自动生成图片描述（架构图、截图等），解决"搜文字出图"的多模态检索需求
• 构建可插拔后端架构，LLM / Embedding / Reranker / VectorStore 均定义抽象接口，支持 Azure OpenAI ↔ DeepSeek ↔ Ollama 一键切换，适配团队不同网络环境
• 搭建 Streamlit Dashboard 管理平台，提供数据浏览、Ingestion 追踪、查询追踪、评估面板六大功能页，实现全链路白盒化可观测
• 集成 Ragas 评估框架 + Golden Test Set 回归测试，在版本迭代中持续监控检索质量，Faithfulness 评分稳定在 0.85 以上
• 采用 Skill 驱动全流程开发模式，编写 DEV_SPEC 规格文档驱动 auto-coder 自动编码、qa-tester 自动测试与修复、setup 一键环境配置，5 大 Agent Skill 覆盖完整开发生命周期，2 个月业余时间完成 68 个子任务交付

结果：系统覆盖团队 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

示例三：社招 · 后端工程师转 AI 方向

以下为 Skill 基于"社招转 AI、后端/架构方向、金融合规业务背景"生成的示例输出：

合规智能文档检索系统 | 2024.10 - 2025.02 | 设计与主导开发

背景：在某金融机构合规部门，法规文件和内部政策文档持续增长至万级规模，合规团队在审查和咨询场景中需要快速定位特定条款，但现有全文搜索系统只能精确匹配关键词，无法理解"反洗钱"与"AML"等语义近义表达，条款定位效率低下。

目标：设计并实现模块化 RAG 检索系统，将语义检索能力引入合规文档管理流程，支持近义词、跨语言条款匹配，目标将合规条款定位准确率提升至 90% 以上。

过程：

• 主导系统架构设计，采用全链路可插拔架构，LLM / Embedding / Reranker / Splitter / VectorStore 均定义抽象接口与工厂模式，通过 YAML 配置一键切换后端，零代码修改即可适配不同部署环境
• 实现 BM25 稀疏检索 + Dense Embedding 语义检索的混合召回策略，通过 RRF 融合排序兼顾专有名词精确匹配与语义近义匹配，检索准确率较纯向量方案提升 22%
• 构建完整的数据摄取管线，支持 PDF 解析 → 语义分块 → Chunk Refinement → Metadata Enrichment → 向量化存储，实现 DocumentManager 幂等管理，保证文档更新时的数据一致性
• 搭建三层测试体系（Unit / Integration / E2E），覆盖 1200+ 测试用例，集成 Ragas 评估框架建立自动化回归机制，确保迭代过程中检索质量不退化
• 基于 MCP 协议暴露标准化工具接口，支持 GitHub Copilot / Claude Desktop 等 AI 助手直接调用，实现"一次开发、多端调用"的服务化部署
• 实践 Skill 驱动全流程工程化方法，基于 DEV_SPEC 规格文档驱动 AI Agent 自动完成编码（auto-coder）、测试（qa-tester）、环境配置（setup）、清理打包（package），68 个子任务全量由 Agent 交付，开发周期压缩至 2 个月业余时间

结果：系统上线后支撑 12000+ 篇合规文档的实时语义检索，条款定位准确率从 68% 提升至 91%，单次查询延迟控制在 700ms，合规团队文档审查效率提升约 50%。

技术栈：Python / 可插拔架构 / 工厂模式 / BM25 / Dense Retrieval / RRF / Cross-Encoder / ChromaDB / MCP Protocol / Streamlit / Ragas / Skill-Driven Development / Azure OpenAI