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 を公開します。

Related MCP server: dongguk-rule-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

Server を起動：

python university_rules_mcp_server.py

MCP Inspector で検証：

npx @modelcontextprotocol/inspector python university_rules_mcp_server.py

コア検索ツール：

search_university_rules(question)

このツールは DeepSeek を呼び出さず、RAG 検索と Reranker による再ランキング後の 3 件の出典を返します。これらは MCP Client や Agent がそのまま利用できます。

テスト

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

データとセキュリティ

• knowledge_base/ 内の管理規定は、このプロジェクトの学習資料として一緒に保存されます。

• API Key をコード、README、または .env に書き込んだ状態でコミットしないでください。.env は Git で無視されています。

• index/ はローカルで生成されたデータであり、Git で無視されています。