# 模块化企业知识检索与 Agent RAG 系统（Modular RAG MCP Server）

> 可插拔、可观测的模块化 RAG（Retrieval-Augmented Generation）系统。通过 MCP（Model Context Protocol）协议对外暴露标准工具接口，支持 GitHub Copilot、Claude Desktop、Claude Code 等 AI 助手与 Agent 直接调用私有知识库，实现"知识检索 → 精准召回 → 生成回答"的完整闭环。

---

## 目录

- [项目背景](#项目背景)
- [核心特性](#核心特性)
- [系统架构](#系统架构)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [使用方式](#使用方式)
- [配置说明](#配置说明)
- [模块详解](#模块详解)
- [测试](#测试)
- [目录结构](#目录结构)
- [Roadmap](#roadmap)

---

## 项目背景

企业知识库场景中的典型痛点：

- **文档分散**：知识散落在 Wiki、PDF、内部系统中，缺少统一的检索入口
- **语义缺失**：传统关键词搜索无法理解近义表达，如"反洗钱"与"AML"
- **接入困难**：AI 应用难以安全、标准地接入私有知识

本项目将 RAG 链路的完整环节——**检索（Hybrid Search + Rerank）**、**多模态视觉处理（Image Captioning）**、**评估（Ragas + Custom）**、**生成（LLM Response）**——与 **MCP（Model Context Protocol）** 串接为一个可运行的工程系统，作为 Agent / AI 助手的知识底座。

---

## 核心特性

### 🔌 全链路可插拔架构
LLM / Embedding / Reranker / Splitter / VectorStore / Evaluator 均定义抽象接口，基于工厂模式 + 配置文件一键切换后端（OpenAI / Azure / DeepSeek / Ollama），零代码修改即可适配不同环境。

### 🔍 混合检索 + 重排
BM25 稀疏检索（内置 jieba 中文分词）解决专有名词精确匹配，Dense Embedding 解决同义词语义匹配，RRF 融合排序后再经 Cross-Encoder / LLM 重排精排，平衡查全率与查准率。

### 🖼️ 多模态图像处理
采用 Image-to-Text 策略，利用 Vision LLM 自动生成图片描述并缝合进 Chunk，复用纯文本 RAG 链路即可实现"搜文字出图"。

### 📡 MCP 生态集成
遵循 Model Context Protocol 标准，暴露 `query_knowledge_hub` / `list_collections` / `get_document_summary` 三个工具，可直接接入支持 MCP 协议的 AI 客户端与 Agent，一次开发、多端调用。

### 📊 全链路可观测
Ingestion 与 Query 两条链路的状态全程白盒追踪，Streamlit Dashboard 提供数据管理与链路可视化，拒绝"凭感觉"调优。

### 📈 自动化评估
集成 Ragas 评估框架与自定义 Evaluator，支持 Golden Test Set 回归测试，从数据层面度量检索质量（Hit Rate / MRR / Faithfulness 等）。

### 🧪 三层测试体系
Unit / Integration / E2E 分层测试，覆盖独立模块逻辑、模块间交互与完整链路（MCP Client / Dashboard）。

---

## 系统架构

```
┌──────────────────────────── 数据摄取（Ingestion）────────────────────────────┐
│  PDF/文档 ──▶ markitdown ──▶ Markdown ──▶ Splitter ──▶ Chunk                │
│       └──▶ Vision LLM 图像描述 ──┐      └──▶ Chunk Refiner / Metadata Enricher
│                                  ▼                                          │
│                          Embedding ──▶ ChromaDB (Upsert)                   │
└──────────────────────────────────────────────────────────────────────────────┘

┌───────────────────────────── 查询（Query）─────────────────────────────────┐
│   Query ──▶ Dense Embedding ──┐                                            │
│            ──▶ BM25 (jieba) ──┴──▶ RRF Fusion ──▶ Rerank ──▶ Top-K 结果    │
│                                          (Cross-Encoder / LLM)             │
└──────────────────────────────────────────────────────────────────────────────┘

┌───────────────────────────── 对外暴露（MCP）────────────────────────────────┐
│   MCP Server: query_knowledge_hub / list_collections / get_document_summary │
│   ◀── Copilot / Claude Desktop / Claude Code / Agent 等 MCP Client          │
└──────────────────────────────────────────────────────────────────────────────┘

┌───────────────────────── 管理与观测（Dashboard / Evaluation）───────────────┐
│   Streamlit Dashboard（总览/数据/Ingestion/摄取追踪/查询追踪/评估）          │
│   Ragas + Custom Evaluator（Golden Test Set 回归）                           │
└──────────────────────────────────────────────────────────────────────────────┘
```

所有核心组件均通过统一的 `config/settings.yaml` 配置驱动。

---

## 技术栈

| 类别 | 技术 |
|------|------|
| 语言 | Python 3.10+ |
| 协议 | MCP（Model Context Protocol） |
| 文档解析 | markitdown（PDF → Markdown） |
| 文本分块 | LangChain Text Splitters（递归 / 语义 / 定长） |
| 向量检索 | ChromaDB + Embedding（OpenAI / Azure / Ollama） |
| 稀疏检索 | BM25（jieba 中文分词） |
| 重排 | Cross-Encoder / LLM Rerank（RRF 融合） |
| LLM | OpenAI / Azure OpenAI / DeepSeek / Ollama |
| 可视化 | Streamlit |
| 评估 | Ragas + Custom Evaluator |
| 测试 | pytest（Unit / Integration / E2E） |

---

## 快速开始

### 环境要求

- Python >= 3.10
- 一个 LLM API Key（OpenAI / Azure / DeepSeek / Ollama 任选）

### 1. 克隆与安装

```bash
git clone <repo-url>
cd MODULAR-RAG-MCP-SERVER
pip install -e .
```

### 2. 配置

编辑 `config/settings.yaml`，填写 LLM / Embedding 的 Provider 与 API Key：

```yaml
llm:
  provider: "openai"   # openai / azure / ollama / deepseek
  model: "gpt-4o"
  api_key: "YOUR_API_KEY"

embedding:
  provider: "openai"
  model: "text-embedding-ada-002"
  api_key: "YOUR_API_KEY"
```

### 3. 摄取文档

```bash
# 摄取单个 PDF 或整个目录（递归处理所有 PDF）
python scripts/ingest.py --path ./docs --collection my_knowledge
```

### 4. 查询

```bash
python scripts/query.py --query "什么是混合检索" --collection my_knowledge --top-k 10
```

`--verbose` 可查看 Dense / Sparse / Fusion / Rerank 各阶段中间结果。

### 5. 启动 Dashboard

```bash
python scripts/start_dashboard.py --port 8501
```

浏览器访问 `http://localhost:8501`。

---

## 使用方式

系统提供三种接入方式：

### 1. MCP Server（推荐，供 Agent / AI 助手调用）

将 MCP Server 注册到任意支持 MCP 协议的客户端：

```json
{
  "mcpServers": {
    "knowledge-hub": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "<项目路径>"
    }
  }
}
```

配置完成后，Copilot / Claude Desktop / Claude Code 等即可直接调用 `query_knowledge_hub` 等工具检索知识库。

### 2. CLI 命令行

适用于脚本化 / 自动化场景：`scripts/ingest.py`、`scripts/query.py`、`scripts/evaluate.py`。

### 3. Streamlit Dashboard

提供完整的管理界面：系统总览 / 数据浏览 / Ingestion 管理 / 摄取追踪 / 查询追踪 / 评估面板。

---

## 配置说明

所有配置集中在 `config/settings.yaml`：

| 配置项 | 说明 |
|--------|------|
| `llm` | 生成模型 Provider / Model / API Key / 参数 |
| `embedding` | Embedding 模型配置 |
| `vision_llm` | 图像描述模型（Image Captioning） |
| `vector_store` | 向量库类型与持久化目录 |
| `retrieval` | Dense / Sparse Top-K、RRF 融合参数 |
| `rerank` | 重排开关与模型 |
| `ingestion` | 分块大小 / 重叠 / 切分策略 |
| `evaluation` | 评估开关与指标 |
| `observability` | 日志级别 / 链路追踪 |

### 切换 Provider

得益于工厂模式，切换 Provider 只需改配置：

```yaml
llm:
  provider: "deepseek"          # 切换为 DeepSeek
  model: "deepseek-chat"
  api_key: "..."
```

新增 Provider 的扩展路径：① 在 `src/libs/llm/` 新增 Provider 类 → ② 在工厂注册 → ③ 更新配置。Embedding / Reranker 同理。

---

## 模块详解

### Ingestion Pipeline

全链路数据摄取：`PDF → Markdown → Chunk → Transform → Embedding → Upsert`

- 基于 `markitdown` 将 PDF 转为 Markdown
- 支持递归 / 语义 / 定长三种分块策略
- Vision LLM 自动为图片生成描述并缝合进 Chunk，实现多模态检索
- Chunk Refiner 与 Metadata Enricher 增强块质量与元数据
- DocumentManager 幂等管理，避免重复摄取

### Hybrid Search

两段式检索架构：

1. **召回**：Dense Embedding 语义检索 + BM25 稀疏检索（jieba 中文分词）并行召回
2. **融合**：RRF（Reciprocal Rank Fusion）合并两个结果集
3. **精排**：可选 Cross-Encoder / LLM 重排，提升 Top-K 精准度

### MCP Server

`src/mcp_server/` 暴露三个标准 MCP 工具：

| 工具 | 功能 |
|------|------|
| `query_knowledge_hub` | 语义检索知识库，返回召回结果 |
| `list_collections` | 列出所有知识集合 |
| `get_document_summary` | 获取指定文档摘要 |

### Dashboard

Streamlit 六页面管理平台：系统总览 / 数据浏览 / Ingestion 管理 / 摄取追踪 / 查询追踪 / 评估面板。

### Observability

Ingestion 与 Query 两条链路的关键中间状态全部落盘为结构化日志与 Trace，便于定位检索质量问题。

### Evaluation

集成 Ragas 与自定义 Evaluator，支持 Golden Test Set 回归测试，覆盖 Hit Rate / MRR / Faithfulness / Relevancy 等指标。

### 模块实现状态

| 模块 | 状态 |
|------|------|
| Ingestion / Hybrid Search / MCP Server / Dashboard / Observability | ✅ 已实现 |
| Custom Evaluator | 🚧 框架已搭建，待完善 |
| Cross-Encoder Reranker | 🚧 框架已搭建，需下载本地模型 |

---

## 测试

```bash
# 单元测试（快速，无外部依赖）
pytest tests/unit -m "not llm and not slow"

# 集成测试
pytest tests/integration

# 端到端测试（完整链路，含 MCP Client / Dashboard）
pytest tests/e2e

# 全量测试
pytest
```

三层测试体系：

- **Unit**：独立模块逻辑（分块、召回、融合、配置加载等）
- **Integration**：模块间交互（Ingestion → VectorStore、Retrieval → Rerank 等）
- **E2E**：完整链路（MCP 协议调用、Dashboard 渲染）

---

## 目录结构

```
├── main.py                     # 主入口（配置加载 + 日志初始化）
├── pyproject.toml              # 项目元数据与依赖
├── config/
│   ├── settings.yaml           # 主配置文件
│   └── prompts/                # Prompt 模板
├── src/
│   ├── core/                   # 配置加载、查询引擎、响应、Trace
│   ├── ingestion/              # 摄取链路（chunking / embedding / storage / transform）
│   ├── libs/                   # 抽象接口与实现（llm / embedding / loader / reranker / splitter / vector_store / evaluator）
│   ├── mcp_server/             # MCP Server 与 Tools
│   └── observability/          # 日志、Trace、Dashboard、Evaluation
├── scripts/
│   ├── ingest.py               # 文档摄取 CLI
│   ├── query.py                # 查询 CLI
│   ├── evaluate.py             # 评估 CLI
│   └── start_dashboard.py      # Dashboard 启动
└── tests/
    ├── unit/
    ├── integration/
    └── e2e/
```

---

## Roadmap

- [ ] 完善 Custom Evaluator 与 Cross-Encoder Reranker
- [ ] 支持 Word / Markdown / HTML 等更多文档格式（扩展 Loader）
- [ ] Docker 化部署与 CI/CD 流水线
- [ ] 扩展 Agentic RAG / Graph RAG 形态
- [ ] 支持更多 VectorStore 后端（Qdrant / Pinecone）