University Rules RAG MCP Agent

Un proyecto de Python para aprender desde cero RAG, Reranker, indexación persistente, API de DeepSeek y MCP. Utiliza el «Reglamento de gestión del estatus académico de los estudiantes de pregrado de la Universidad Sun Yat-sen» como base de conocimiento; tras recuperar los artículos relevantes, genera respuestas con fuentes; la misma capacidad de recuperación también se puede exponer como herramienta MCP para que los agentes la invoquen.

Este proyecto es para aprendizaje técnico. En asuntos reales de estatus académico, consulte la normativa oficial más reciente de la universidad y la respuesta del departamento de asuntos académicos.

Funciones

• Divide el texto de la normativa local según «el número de artículo».

• Búsqueda semántica con BGE Embedding.

• Hybrid Search de palabras clave + semántica.

• BGE Reranker realiza el reordenamiento fino de los artículos candidatos.

• Guarda los vectores de los documentos y los metadatos de los artículos en local, evitando regenerar los Document Embeddings.

• Usa DeepSeek para generar respuestas con fuentes a partir de los artículos finales.

• Expone la herramienta MCP search_university_rules(question).

Related MCP server: byrdocs-search-mcp

Arquitectura

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

Estructura del proyecto

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

Instalación

Se recomienda usar Python 3.10 o una versión superior:

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

La primera vez que se ejecute el Embedding o el Reranker, los modelos se descargarán a la caché local de Hugging Face; en las siguientes ejecuciones se reutilizará la caché directamente.

Ejecución

Búsqueda básica:

python rag_search.py

Versión completa de preguntas y respuestas con RAG:

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

Flujo de final_rag_chat.py:

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

El directorio index/ se genera automáticamente en la primera ejecución y guarda los vectores de los documentos y los metadatos; este directorio está ignorado por Git porque puede reconstruirse a partir de la base de conocimiento.

Servidor MCP

Iniciar el servidor:

python university_rules_mcp_server.py

Verificar con MCP Inspector:

npx @modelcontextprotocol/inspector python university_rules_mcp_server.py

Herramienta de búsqueda principal:

search_university_rules(question)

La herramienta no llama a DeepSeek, sino que devuelve las 3 fuentes obtenidas tras la recuperación RAG y el reordenamiento fino con Reranker, para que el MCP Client o el Agent las utilicen.

Pruebas

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

Datos y seguridad

• Las normativas dentro de knowledge_base/ se guardan junto con este proyecto como material de aprendizaje.

• No pongas la API Key en el código, el README o .env y luego hagas commit; .env ya está ignorado por Git.

• El directorio index/ contiene datos generados localmente y ya está ignorado por Git.