Modular RAG MCP Server

Modular RAG MCP Server 是一个面向私有知识库的模块化 RAG（Retrieval-Augmented Generation，检索增强生成）服务框架。项目支持文档摄取、稠密/稀疏混合检索、可选重排、链路追踪、评估面板，并通过 MCP（Model Context Protocol）协议向外暴露知识库查询能力。

该项目适合作为企业内部知识库、团队文档问答、AI 助手工具接入、RAG 原型验证和检索质量分析的工程基础。

更多架构细节可参考 系统架构说明。

核心功能

模块	能力
文档摄取	文件完整性检查、PDF 解析、分块、元数据增强、图片描述、向量化和存储
混合检索	Dense 向量检索 + BM25 稀疏检索 + RRF 融合排序
重排	支持关闭、Cross-Encoder 重排或 LLM 重排
MCP 服务	通过标准 MCP tools 对外提供知识库查询能力
Dashboard	基于 Streamlit 的系统总览、数据浏览、摄取管理、链路追踪和评估面板
可观测性	记录 Ingestion 和 Query 两条链路的结构化 trace
评估	支持自定义指标和 Ragas 评估扩展
可插拔架构	LLM、Embedding、Reranker、Splitter、VectorStore、Evaluator 均通过接口和工厂模式组织

适用场景

• 企业内部知识库：技术文档、产品手册、制度文档、客服资料、研究报告等。
• 团队文档问答：帮助研发、产品、运营或支持团队快速定位内部资料。
• AI 助手接入：通过 MCP 让兼容客户端调用私有知识库查询工具。
• RAG 原型验证：快速验证不同分块、检索、融合、重排和评估策略。
• 检索质量分析：通过 trace、评估集和 Dashboard 检查召回与排序效果。
• 行业知识问答：在法律、医疗、金融、制造、教育等领域接入专有文档。

系统架构

文档
  -> Ingestion Pipeline
     -> Loader
     -> Chunker
     -> Transform
     -> Dense + Sparse Encoding
     -> ChromaDB + BM25 Index + Image Index
  -> Query Pipeline
     -> Query Processing
     -> Dense Retrieval
     -> Sparse Retrieval
     -> RRF Fusion
     -> Optional Rerank
     -> Response + Citations
  -> MCP Tools / CLI / Dashboard

主要目录：

• src/ingestion/：文档摄取流水线、分块、编码和存储协调。
• src/core/query_engine/：查询处理、混合检索、融合排序和重排编排。
• src/mcp_server/：MCP 服务、协议处理和工具注册。
• src/observability/：日志、trace、Dashboard 和评估相关能力。
• src/libs/：LLM、Embedding、Loader、Splitter、Reranker、VectorStore 等 provider 抽象和实现。
• scripts/：摄取、查询、评估和 Dashboard 启动脚本。

MCP 工具

当前 MCP Server 注册了以下工具：

• query_knowledge_hub：对指定 collection 执行混合检索并返回带引用的结果。
• list_collections：列出当前向量库中的 collection，可选返回统计信息。
• get_document_summary：根据文档 ID 查询文档标题、摘要、来源、标签和 chunk 数量。

环境要求

• Python 3.10+
• 一个可用的 LLM provider，用于生成、元数据增强、图片描述或可选重排
• 一个可用的 Embedding provider，用于稠密向量检索
• ChromaDB，用于本地向量存储

Provider 配置位于 config/settings.yaml。

当前代码支持的 provider 类型包括：

• LLM：OpenAI、Azure OpenAI、Ollama、DeepSeek
• Embedding：OpenAI、Azure OpenAI、Ollama
• Vision LLM：OpenAI、Azure OpenAI、Ollama
• Vector Store：ChromaDB
• Rerank：关闭、Cross-Encoder、LLM Reranker

安装

python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

macOS 或 Linux：

source .venv/bin/activate

配置

编辑 config/settings.yaml，配置实际使用的模型和存储参数。

至少需要关注：

• llm.provider
• llm.model
• llm.api_key 或 provider 对应 endpoint 配置
• embedding.provider
• embedding.model
• embedding.api_key 或 provider 对应 endpoint 配置
• vector_store.persist_directory
• vector_store.collection_name

默认运行数据目录：

• data/db/chroma：ChromaDB 持久化目录
• data/db/bm25：BM25 稀疏索引
• data/db/ingestion_history.db：摄取历史与文件完整性记录
• data/db/image_index.db：图片索引
• data/images：提取出的图片资源

这些运行时目录默认不会提交到 git。

使用方式

摄取文档

摄取单个 PDF：

python scripts/ingest.py --path documents/report.pdf --collection default

摄取目录下的所有 PDF：

python scripts/ingest.py --path documents/ --collection default

强制重新处理已摄取文件：

python scripts/ingest.py --path documents/report.pdf --collection default --force

查询知识库

python scripts/query.py --query "Azure OpenAI 如何配置？" --collection default

查看 dense、sparse、fusion、rerank 等中间结果：

python scripts/query.py --query "RRF 融合策略是什么？" --collection default --verbose

关闭重排：

python scripts/query.py --query "RRF 融合策略是什么？" --collection default --no-rerank

启动 Dashboard

python scripts/start_dashboard.py

指定 host 和 port：

python scripts/start_dashboard.py --host localhost --port 8502

启动 MCP Server

python -m src.mcp_server.server

服务使用 stdio transport。接入 MCP 兼容客户端时，将客户端命令指向该 Python 模块即可。

示例命令结构：

{
  "command": "python",
  "args": ["-m", "src.mcp_server.server"]
}

项目结构

config/
  settings.yaml                 主配置文件
  prompts/                      Transform 和 Rerank 使用的提示词模板
scripts/
  ingest.py                     文档摄取命令行入口
  query.py                      查询命令行入口
  evaluate.py                   评估命令行入口
  start_dashboard.py            Dashboard 启动入口
src/
  core/                         共享类型、配置、trace、查询引擎、响应构建
  ingestion/                    摄取流水线和文档生命周期管理
  libs/                         provider 抽象和适配器
  mcp_server/                   MCP server 和 tools
  observability/                日志、trace、Dashboard、评估
tests/
  unit/                         单元测试
  integration/                  集成测试
  e2e/                          端到端测试
  fixtures/                     测试数据和样例文档

测试

运行单元测试：

pytest tests/unit -v

运行全部测试：

pytest

部分 integration/e2e 测试依赖真实 provider 凭证或本地服务。只运行快速测试时可使用 pytest markers：

pytest -m "unit and not llm"

扩展方式

项目通过接口和工厂模式组织 provider。新增或替换组件时，建议保持配置驱动的方式：

• 新增 LLM provider：src/libs/llm/
• 新增 Embedding provider：src/libs/embedding/
• 新增 Vector Store：src/libs/vector_store/
• 新增 Splitter：src/libs/splitter/
• 新增 Reranker：src/libs/reranker/
• 新增 Evaluator：src/libs/evaluator/ 或 src/observability/evaluation/

新增组件时应完成：

1. 实现对应 base interface。
2. 在 factory 中注册 provider。
3. 在 config/settings.yaml 中补充配置项。
4. 添加单元测试和必要的集成测试。
5. 更新 README 或 DEV_SPEC 中的配置说明。

运行说明

• MCP stdio server 的 stdout 只用于协议消息，日志应写入 stderr。
• 摄取默认通过 SHA256 做幂等跳过，避免重复处理未变化文件。
• 查询和摄取 trace 以 JSONL 形式写入本地文件。
• 当前版本实际实现的向量库后端是 ChromaDB。
• API Key、运行数据、日志和索引文件不应提交到仓库。

License

MIT