使用说明
Modular RAG MCP Server
一个可插拔、可观测的**模块化 RAG（检索增强生成）**服务框架，通过 MCP（Model Context Protocol） 对外暴露工具接口，支持 Copilot、Claude 等 AI 助手直接调用知识库检索与问答。
功能概览
| 能力 | 说明 |
|---|---|
| 数据摄取 | PDF → Markdown → 分块 → 增强（元数据/图片描述）→ 双路向量化 → 写入向量库，支持增量更新与多模态 |
| 混合检索 | Dense（向量）+ Sparse（BM25）+ RRF 融合，可选 Rerank（Cross-Encoder / LLM / 云 API） |
| MCP 服务 | 标准 MCP 协议，stdio 传输，暴露 query_knowledge_hub、list_collections、get_document_summary 等工具 |
| 管理面板 | Streamlit 六页：总览、数据浏览、摄取管理、摄取追踪、查询追踪、评估面板 |
| 评估体系 | Ragas |
安装
# 克隆仓库
git clone <your-repo-url>
cd MODULAR-RAG-MCP-SERVER
# 创建虚拟环境（推荐）
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # Linux/macOS
# 核心依赖
pip install -e .
# 可选：PDF、Dashboard、Rerank、评估
pip install -e ".[pdf,dashboard,rerank,eval]"
配置
主配置：config/settings.yaml。需根据所用服务填写 API Key 等，也可通过环境变量覆盖（如 OPENAI_API_KEY、DASHSCOPE_API_KEY）。
主要配置项：
- llm：推理模型（如
openai/dashscope/ollama） - embedding：向量模型（如
openai/dashscope/ollama） - vision_llm：多模态图片描述（可选）
- vector_store：向量库（默认 Chroma，
persist_directory、collection_name） - retrieval：
dense_top_k、sparse_top_k、fusion_top_k、rrf_k - rerank：是否启用、后端（
dashscope/cross_encoder/llm等）
使用前请复制或修改 config/settings.yaml，并确保不将真实 API Key 提交到仓库。
使用方式
1. 摄取文档
# 单文件
python scripts/ingest.py --path documents/report.pdf --collection my_docs
# 目录
python scripts/ingest.py --path documents/ --collection my_docs
# 强制重新处理（忽略历史）
python scripts/ingest.py --path documents/report.pdf --collection my_docs --force
# 自定义配置
python scripts/ingest.py --path documents/ --collection my_docs --config config/settings_financial.yaml
2. 命令行查询
python scripts/query.py --query "你的问题" --collection my_docs
python scripts/query.py --query "你的问题" --verbose # 显示召回与重排细节
python scripts/query.py --query "你的问题" --no-rerank # 关闭 Rerank
3. 启动 MCP 服务（供 Copilot / Claude 等连接）
# 在项目根目录执行
python -m src.mcp_server.server
MCP 使用 stdio 传输，由 Cursor、Claude Desktop 等通过配置的 MCP Server 命令调用，无需单独开端口。
4. 启动管理面板
python scripts/start_dashboard.py
# 或指定端口
python scripts/start_dashboard.py --port 8502
浏览器访问 http://localhost:8501，可进行总览、数据浏览、摄取管理、追踪查看、评估任务等操作。
5. 运行评估
python scripts/evaluate.py
# 具体参数见脚本帮助与 Golden Test Set 配置
MCP 暴露的工具
| 工具 | 说明 |
|---|---|
| query_knowledge_hub | 对指定集合进行混合检索（Dense + Sparse + RRF + 可选 Rerank），返回答案与引用片段 |
| list_collections | 列出当前向量库中的集合名称及简要统计 |
| get_document_summary | 根据文档标识获取文档摘要或概要信息 |
项目结构（简要）
├── config/
│ └── settings.yaml # 主配置
├── main.py # 占位入口（实际 MCP 入口为 src.mcp_server.server）
├── scripts/
│ ├── ingest.py # 摄取 CLI
│ ├── query.py # 查询 CLI
│ ├── evaluate.py # 评估运行
│ └── start_dashboard.py # 面板启动
├── src/
│ ├── core/ # 配置、类型、检索、响应、追踪
│ ├── ingestion/ # 摄取流水线、存储、Transform
│ ├── libs/ # Embedding / LLM / Loader / Splitter / VectorStore / Reranker 等可插拔实现
│ ├── mcp_server/ # MCP 协议与工具实现
│ └── observability/ # 日志、Dashboard、评估
└── tests/
测试
# 单元测试
pytest tests/ -v
# 排除需外部服务的测试
pytest tests/ -v -m "not llm"
更多说明
- 本项目采用可插拔设计：LLM、Embedding、Rerank、Loader、Splitter、VectorStore 等均可通过配置或实现抽象接口替换，便于扩展与二次开发。
License
MIT
