University Rules RAG MCP Agent

RAG, Reranker, 영구 인덱스, DeepSeek API, MCP를 처음부터 배우는 Python 프로젝트입니다. 《중산대학교 학부생 학적 관리 규정》을 지식 베이스로 사용하여 관련 조항을 검색한 뒤 출처가 포함된 답변을 생성합니다. 동일한 검색 기능을 MCP 도구로 제공하여 Agent가 호출할 수 있습니다.

이 프로젝트는 기술 학습용입니다. 실제 학적 업무와 관련된 경우에는 학교의 최신 공식 규정과 교무 부서의 답변을 기준으로 하시기 바랍니다.

기능

• 로컬 관리 규정 텍스트를 "제N조" 단위로 분할합니다.

• BGE Embedding 의미 검색.

• 키워드 + 의미 기반 Hybrid Search.

• BGE Reranker로 후보 조항 정밀 재정렬.

• 문서 벡터와 조항 메타데이터를 로컬에 저장하여 Document Embedding 중복 생성을 방지합니다.

• DeepSeek를 사용하여 최종 조항을 바탕으로 출처가 포함된 답변을 생성합니다.

• search_university_rules(question) MCP 도구를 노출합니다.

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 서버

서버 시작:

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/ 안의 관리 규정은 이 프로젝트의 학습 자료로 함께 저장됩니다.

• 코드, README 또는 .env에 API Key를 작성한 뒤 커밋하지 마세요. .env는 Git에서 무시됩니다.

• index/는 로컬에서 생성된 데이터이며 Git에서 무시됩니다.