University Rules RAG MCP Agent

Ein Python-Projekt, das RAG, Reranker, persistente Indizes, die DeepSeek-API und MCP von Grund auf lernt. Es verwendet die „中山大学-Ordnung zur Verwaltung des Studierendenstatus von Bachelorstudierenden“ als Wissensbasis, ruft relevante Bestimmungen ab und erzeugt Antworten mit Quellenangaben; dieselbe Suchfunktion steht auch als MCP-Tool für Agenten zur Verfügung.

Dieses Projekt dient dem technischen Lernen. Bei tatsächlichen Angelegenheiten des Studierendenstatus gelten die neuesten offiziellen Bestimmungen der Universität und die Auskünfte der Studienabteilung als maßgeblich.

Funktionen

• Segmentierung des lokalen Texts der Verwaltungsordnung nach „Artikel“.

• Semantische Suche mit BGE Embedding.

• Hybrid Search aus Stichwortsuche und semantischer Suche.

• Feinrangierung der Kandidatenartikel mit BGE Reranker.

• Lokale Speicherung von Dokumentvektoren und Artikel-Metadaten, um das erneute Erzeugen von Document Embeddings zu vermeiden.

• Erzeugung von Antworten mit Quellenangaben auf Grundlage der finalen Artikel mithilfe von DeepSeek.

• Bereitstellung des MCP-Tools search_university_rules(question).

Related MCP server: byrdocs-search-mcp

Architektur

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

Projektstruktur

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                       # 单元测试

Installation

Es wird empfohlen, Python 3.10 oder höher zu verwenden:

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

Beim ersten Ausführen von Embedding oder Reranker werden die Modelle in den lokalen Hugging-Face-Cache heruntergeladen; bei späteren Läufen wird der Cache direkt wiederverwendet.

Ausführung

Basis-Retrieval:

python rag_search.py

Vollständige RAG-Frage-Antwort-Variante:

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

Ablauf von final_rag_chat.py:

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

Das Verzeichnis index/ wird beim ersten Lauf automatisch erzeugt und speichert Dokumentvektoren und Metadaten; es wird von Git ignoriert, da es aus der Wissensbasis neu aufgebaut werden kann.

MCP-Server

Server starten:

python university_rules_mcp_server.py

Mit MCP Inspector überprüfen:

npx @modelcontextprotocol/inspector python university_rules_mcp_server.py

Zentrales Retrieval-Werkzeug:

search_university_rules(question)

Das Werkzeug ruft DeepSeek nicht auf, sondern gibt die 3 nach RAG-Retrieval und Reranker-Feinrangierung ermittelten Quellen zurück, damit der MCP-Client oder Agent sie weiterverwenden kann.

Tests

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

Daten und Sicherheit

• Die Verwaltungsvorschriften in knowledge_base/ werden als Lernmaterial dieses Projekts mitgespeichert.

• Schreibe keinen API-Key in Code, README oder .env und committe ihn nicht; .env wird von Git ignoriert.

• index/ enthält lokal erzeugte Daten und wird von Git ignoriert.