University Rules RAG MCP Agent

Учебный проект на Python для изучения с нуля RAG, Reranker, персистентных индексов, DeepSeek API и MCP. Он использует «Правила управления учебным статусом студентов бакалавриата Университета Сунь Ятсена» в качестве базы знаний: извлекает соответствующие статьи и генерирует ответы с указанием источников. Та же возможность поиска также доступна как MCP Tool для вызова агентом.

Данный проект предназначен для изучения технологий. При решении реальных вопросов, связанных с учебным статусом, руководствуйтесь последними официальными правилами университета и ответами учебного отдела.

Функции

• Разбивает локальный текст правил по «номеру статьи».

• Семантический поиск с помощью BGE Embedding.

• Гибридный поиск по ключевым словам + семантике (Hybrid Search).

• BGE Reranker для точного ранжирования статей-кандидатов.

• Локальное сохранение векторов документов и метаданных статей, чтобы избежать повторной генерации Document Embedding.

• Использование DeepSeek для генерации ответа с источниками на основе итоговых статей.

• Предоставление MCP Tool search_university_rules(question).

Related MCP server: byrdocs-search-mcp

Архитектура

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

Структура проекта

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 или выше:

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

При первом запуске Embedding или Reranker модель будет загружена в локальный кэш Hugging Face; в дальнейшем кэш будет использоваться повторно.

Запуск

Базовый поиск:

python rag_search.py

Полная RAG-версия с вопросами и ответами:

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

Процесс final_rag_chat.py:

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

Директория index/ автоматически создаётся при первом запуске и сохраняет векторы документов и метаданные; эта директория игнорируется Git, так как может быть пересоздана из базы знаний.

MCP Server

Запуск сервера:

python university_rules_mcp_server.py

Проверка с помощью MCP Inspector:

npx @modelcontextprotocol/inspector python university_rules_mcp_server.py

Основной инструмент поиска:

search_university_rules(question)

Инструмент не вызывает DeepSeek, а возвращает 3 источника, полученных с помощью RAG-поиска и точного ранжирования Reranker, которые MCP Client или агент может использовать дальше.

Тестирование

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

Данные и безопасность

• Правила внутри knowledge_base/ сохраняются в качестве учебных материалов проекта.

• Не записывайте API Key в код, README или .env перед коммитом; .env игнорируется Git.

• index/ — локально сгенерированные данные, игнорируются Git.