# University Rules RAG MCP Agent

一个从零学习 RAG、Reranker、持久化索引、DeepSeek API 和 MCP 的 Python 项目。它以《中山大学本科生学籍管理规定》为知识库，检索相关条款后生成带来源的回答；同一套检索能力也可作为 MCP Tool 供 Agent 调用。

> 本项目用于技术学习。涉及真实学籍事务时，请以学校最新官方规定和教务部门答复为准。

## 功能

- 按“第几条”切分本地管理规定文本。
- BGE Embedding 语义检索。
- 关键词 + 语义的 Hybrid Search。
- BGE Reranker 对候选条款精排。
- 将文档向量、条款元数据保存到本地，避免重复生成 Document Embedding。
- 使用 DeepSeek 根据最终条款生成带来源的回答。
- 暴露 `search_university_rules(question)` MCP Tool。

## 架构

```text
用户问题
  ↓
持久化向量索引
  ↓
Hybrid Search：Top 10 候选条款
  ↓
Reranker：Top 3 最相关条款
  ├─→ DeepSeek：生成带来源的自然语言回答
  └─→ MCP Tool：将条款 JSON 返回给 Agent
```

## 项目结构

```text
knowledge_base/                 # 学习用管理规定文本
rag_search.py                   # 基础关键词检索
semantic_search.py              # Embedding 语义检索
hybrid_search.py                # 混合检索
rerank_search.py                # Reranker 精排
index_store.py                  # 本地索引读写和有效性判断
final_rag_chat.py               # 完整 RAG + DeepSeek 问答
university_rules_mcp_server.py  # RAG MCP Server
test_*.py                       # 单元测试
```

## 安装

建议使用 Python 3.10 或更高版本：

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

首次运行 Embedding 或 Reranker 时，会将模型下载到本机 Hugging Face 缓存；后续会直接复用缓存。

## 运行

基础检索：

```powershell
python rag_search.py
```

完整 RAG 问答版：

```powershell
$env:DEEPSEEK_API_KEY="你的 DeepSeek API Key"
python final_rag_chat.py
```

`final_rag_chat.py` 的流程：

```text
本地索引 → Hybrid Top 10 → Reranker Top 3 → DeepSeek 回答
```

其中 `index/` 会在首次运行时自动生成，保存文档向量和元数据；该目录已被 Git 忽略，因为它可以从知识库重新建立。

## MCP Server

启动 Server：

```powershell
python university_rules_mcp_server.py
```

使用 MCP Inspector 验证：

```powershell
npx @modelcontextprotocol/inspector python university_rules_mcp_server.py
```

核心检索工具：

```text
search_university_rules(question)
```

工具不调用 DeepSeek，而是返回 RAG 检索与 Reranker 精排后的 3 条来源，供 MCP Client 或 Agent 继续使用。

## 测试

```powershell
python -m unittest discover -p "test_*.py" -v
```

## 数据与安全

- `knowledge_base/` 内的管理规定作为本项目学习资料一并保存。
- 不要把 API Key 写入代码、README 或 `.env` 后再提交；`.env` 已被 Git 忽略。
- `index/` 是本地生成的数据，已被 Git 忽略。