# Modular RAG MCP Server
> 一个可插拔、可观测的模块化 RAG (检索增强生成) 服务框架
[](LICENSE)
[](https://www.python.org/)
---
## 🔧 项目功能
本项目是一个**企业级智能问答与知识检索系统**，可应用于以下场景：
- **📖 文档问答**：支持 PDF、Markdown、代码文件等多格式文档的智能问答，快速从海量文档中提取精准答案
- **🔍 语义搜索**：基于混合检索技术，提供比传统关键词搜索更智能的语义理解能力
- **💡 知识库构建**：将企业内部文档、技术资料转化为可检索的知识库，提升团队协作效率
- **🤖 AI 助手集成**：通过 MCP (Model Context Protocol) 协议，可无缝对接 Claude、GitHub Copilot 等 AI 助手
- **🎯 个性化应用**：可扩展为客服机器人、技术文档助手、代码搜索引擎等垂直领域应用
> 💼 **面试利器**：本项目的模块化设计和完整实现，可直接作为简历项目展示，涵盖 RAG 技术栈的核心知识点，是大模型/AI 工程师面试的绝佳项目案例。
---
## 🎯 项目特点
### 1️⃣ **可插拔架构 (Pluggable Architecture)**
- **LLM 后端灵活切换**：支持 Azure OpenAI、OpenAI API、本地模型（Ollama/vLLM）等多种后端，通过配置文件一键切换，零代码修改
- **模型组件自由替换**：Embedding 模型、Rerank 模型、文档解析器、切分策略等核心组件均采用抽象接口设计，支持"乐高积木式"组合
- **检索策略可配置**：支持纯向量检索、BM25 关键词检索、混合检索（Hybrid Search）等多种模式动态配置
### 2️⃣ **全链路可观测 (Observable)**
- **结构化日志追踪**：每个模块输出详细的结构化日志，便于问题定位与性能分析
- **评测指标体系**：集成 Ragas/DeepEval 等 RAG 评测框架，量化检索质量与生成效果
- **监控与调试友好**：提供完整的请求链路追踪，支持实时性能监控
### 3️⃣ **MCP 协议集成 (Model Context Protocol)**
- **标准化接口**：完整实现 MCP 协议规范，可无缝对接 Claude Desktop、GitHub Copilot 等支持 MCP 的 AI 助手
- **开箱即用**：通过 MCP Server 暴露 RAG 能力，让 AI 助手直接调用项目的检索和问答功能，无需额外开发
- **工具化封装**：将 RAG 流程封装为 MCP Tools，AI 可以自主决策何时调用检索、如何组合多个工具完成复杂任务
- **上下文增强**：为 AI 对话提供实时的知识库支持，让通用大模型具备领域专业知识
### 4️⃣ **工程化 RAG 实践**
- **智能分块策略**：语义感知的文档切分，保留完整语义单元
- **混合检索 (Hybrid Search)**：BM25 + Dense Embedding 融合，平衡查准率与查全率
- **两段式精排**：粗排召回 → Rerank 精排，在性能与精度间取得最优平衡
---
## 📚 AI 驱动开发：让 AI 成为你的协作伙伴
### 💡 核心理念
> **"文档即规范，实现交给 AI"**
本项目采用创新的 **AI 协作开发模式**，让您专注于架构设计与业务逻辑，将代码实现高效委托给 AI：
#### ✨ 项目特色
- **完整的 Skills 体系**：通过精心设计的 Markdown 技能文件（`.trae/skills/`），AI 可以理解项目规范、遵循最佳实践，自动化完成代码实现
- **VibeCoding 实践**：掌握最新的 AI 协作开发技巧（VibeCoding），通过自然语言描述需求，让 AI 自动生成符合规范的代码
- **规范驱动开发**：`DEV_SPEC.md` 作为项目的"宪法"，定义架构、模块设计、技术选型等核心规范，AI 严格遵循文档完成编码
- **零背景快速上手**：即使您不熟悉 RAG 技术栈，只需理解文档、修改需求描述，AI 会自动将您的想法转化为生产级代码
#### 🚀 工作流程
```
1. 📝 理解文档 (DEV_SPEC.md) → 掌握项目设计理念与技术架构
2. ✏️ 修改规范文档 → 根据需求调整设计方案或新增模块
3. 🤖 调用 Skills 交给 AI → 使用 dev-workflow、implement 等技能让 AI 完成编码
4. ✅ 验证与迭代 → Review 代码、运行测试，持续优化
```
#### 📖 配套资源
本项目提供**三位一体**的学习资源，帮助您快速掌握 AI 协作开发模式：
| 资源类型 | 内容说明 |
|---------|---------|
| 📄 **详尽的技术文档** | `DEV_SPEC.md` 提供完整的架构设计、技术选型、模块详解 |
| 💻 **Skills 工作流** | `.trae/skills/` 包含 spec-sync、implement、testing 等 AI 技能，指导 AI 完成开发任务 |
| 🎬 **视频教程** | 从环境搭建到核心模块实现，全程实战演示 |
> 💡 **提示**：详细的设计理念、技术选型与模块设计请参考 [DEV_SPEC.md](DEV_SPEC.md)
### 🎁 你将收获什么
通过学习和实践本项目，你将掌握：
#### 🔥 **最新的 AI 协作技能**
- **Skills 工程化**：学会构建可复用的 AI 技能库，让 AI 成为你的"编程助手"
- **VibeCoding 技巧**：掌握与 AI 高效协作的开发模式，提升 10 倍开发效率
- **文档驱动开发**：理解如何通过规范文档指导 AI 完成复杂工程项目
#### 🎯 **RAG 技术全栈能力**
- **深入每个细节**：从文档解析、智能分块、向量化、混合检索到 Rerank 重排，逐一掌握 RAG 链路的每个环节
- **工程化实践**：不仅是理论，更有生产级代码实现，理解如何将论文技术落地到实际项目
- **性能优化**：学习如何平衡检索速度与精度，优化 Embedding 策略，调优 Rerank 模型
#### 💼 **面试竞争力提升**
- **简历项目加分**：本项目涵盖大模型/AI 工程师岗位的核心技术栈，可直接写入简历作为亮点项目
- **面试问题应对**：配套的面试题库帮你应对"RAG 如何优化召回率"、"Embedding 模型如何选择"等高频问题
- **技术深度展示**：模块化设计、可插拔架构等工程实践，展现你的系统设计能力
---
## 🎓 学习资源与社区
### 📺 配套视频教程
本项目提供**全面的视频讲解**，涵盖：
- ✅ **RAG 核心技术深度剖析**：从分块策略、混合检索到 Rerank 重排，全面解构 RAG 技术细节
- ✅ **代码实战逐行讲解**：环境配置、模块实现、性能优化，手把手带你完成项目
- ✅ **大模型面试真题解析**：精选大厂面试题，结合项目实战讲解答题思路
- ✅ **转行求职指南**：简历撰写技巧、面试准备策略、职业规划建议
### 🎁 额外福利
持续更新中的内容：
- 📝 **基于本项目的简历模板**：如何将技术亮点写进简历
- 🎤 **常见面试问题集锦**：针对 RAG 项目的高频面试题及参考答案
- 💼 **求职经验分享**：从技术学习到拿到 Offer 的完整路径
---
## 🚀 快速开始
```bash
# 1. 克隆项目
git clone https://github.com/yourusername/Modular-RAG-MCP-Server.git
cd Modular-RAG-MCP-Server
# 2. 创建并激活虚拟环境（Python 3.10+）
python -m venv .venv
source .venv/bin/activate # macOS/Linux
# .\.venv\Scripts\Activate.ps1 # Windows
# 3. 安装依赖
python -m pip install -U pip
python -m pip install -e ".[dev]"
# 4. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入您的 API Keys (如 ALIYUN_API_KEY 等)
# 5. 首次数据摄取（测试）
python scripts/ingest.py --path tests/fixtures/sample_documents/ --collection test
# 6. 运行 MCP Server
python src/main.py
```
---
## ⚙️ 配置说明
核心配置文件位于 `config/settings.yaml`，支持热重载。主要配置项说明：
| 配置模块 | 关键字段 | 说明 |
|---------|---------|------|
| **LLM** | `llm.provider` | 支持 `openai`, `azure`, `ollama`。使用 `base_url` 可对接 DeepSeek/Moonshot 等兼容接口。 |
| **Embedding** | `embedding.provider` | 向量模型提供商，支持 `openai`, `ollama`, `local`。 |
| **Vector Store** | `vector_store.backend` | 向量库后端，目前支持 `chroma` (本地持久化)。 |
| **Ingestion** | `ingestion.splitter` | 文档切分策略，推荐 `recursive`。 |
| **Retrieval** | `retrieval.fusion_algorithm` | 混合检索融合算法，默认 `rrf` (Reciprocal Rank Fusion)。 |
| **Rerank** | `rerank.backend` | 精排模型，支持 `cross_encoder` (本地) 或 `llm` (云端)。 |
---
## 🔌 MCP 配置示例
将本项目作为 MCP Server 集成到您的 AI 助手：
### 1. Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"modular-rag": {
"command": "/absolute/path/to/project/.venv/bin/python",
"args": ["/absolute/path/to/project/src/main.py"],
"env": {
"ALIYUN_API_KEY": "sk-xxx",
"ALIYUN_BASE_URL": "https://..."
}
}
}
}
```
### 2. GitHub Copilot / Cursor
编辑项目根目录下的 `.vscode/settings.json` 或工具特定的 MCP 配置文件：
```json
{
"mcp.servers": {
"modular-rag": {
"command": "python",
"args": ["src/main.py"],
"env": { ... }
}
}
}
```
---
## 📊 Dashboard 使用指南
本项目包含一个基于 Streamlit 的可视化管理平台。
**启动 Dashboard：**
```bash
streamlit run src/observability/dashboard/app.py
```
**功能模块：**
1. **Overview (总览)**：查看系统运行状态、文档总量、最近活动。
2. **Data Browser (数据浏览器)**：浏览已摄入的文档库，查看 Chunk 切分详情与 Metadata。
3. **Ingestion Manager (摄取管理)**：上传文件触发处理流程，支持进度实时追踪。
4. **Ingestion Traces (摄取追踪)**：查看历史摄取任务的耗时瀑布图，定位性能瓶颈。
5. **Query Traces (查询追踪)**：可视化查询全链路（检索 -> 排序 -> 生成），对比 Dense/Sparse 结果。
6. **Evaluation (评估面板)**：运行 Golden Test Set，查看 RAG 性能指标 (Hit Rate, MRR)。
---
## 🧪 运行测试
本项目包含完整的测试金字塔：
```bash
# 运行所有测试
pytest
# 仅运行单元测试 (Unit Tests)
pytest tests/unit
# 仅运行集成测试 (Integration Tests)
pytest tests/integration
# 仅运行端到端测试 (E2E Tests)
pytest tests/e2e
# 运行 Dashboard 冒烟测试
pytest tests/e2e/test_dashboard_smoke.py
```
---
## ❓ 常见问题 (FAQ)
**Q: 安装依赖时报错 `ModuleNotFoundError`？**
A: 请确保已激活虚拟环境 (`source .venv/bin/activate`) 且 pip 版本已更新。
**Q: 启动 Server 提示 `API Key not found`？**
A: 检查 `.env` 文件是否存在且已填入 Key，或者直接在 `config/settings.yaml` 中硬编码（不推荐）。
**Q: Dashboard 无法连接到 Server？**
A: Dashboard 直接读取本地数据库与日志文件，无需 Server 进程启动即可查看历史数据。但"查询追踪"需要先产生查询记录。
**Q: 如何切换到本地模型？**
A: 修改 `config/settings.yaml`，设置 `llm.provider: ollama` 并指定 `base_url` (如 `http://localhost:11434`)。
---
## 📂 项目结构
```
.
├── DEV_SPEC.md # 核心设计文档（项目"宪法"）
├── .trae/
│ └── skills/ # AI 协作开发技能库
│ ├── spec-sync/ # 规范同步
│ ├── implement/ # 代码实现
│ ├── testing-stage/ # 测试验证
│ └── ...
├── src/ # 源代码
│ ├── retrieval/ # 检索模块（Hybrid Search, Rerank）
│ ├── generation/ # 生成模块（LLM 调用）
│ ├── pipeline/ # RAG 流程编排
│ └── ...
├── tests/ # 测试用例
└── docs/ # 补充文档
```
---
## 🤝 贡献指南
欢迎提交 Issue 和 Pull Request！在贡献代码前，请：
1. 阅读 [DEV_SPEC.md](DEV_SPEC.md) 了解项目架构与设计理念
2. 遵循项目的代码规范（见 `DEV_SPEC.md` 中的"开发规范"章节）
3. 确保测试通过（`pytest tests/`）
---
## 📄 License
[MIT License](LICENSE)
---
## 🌟 Star History
如果这个项目对您有帮助，欢迎 Star ⭐️ 支持！
---
