Hybrid RAG MCP Server

<p align="center"> <a href="./README.en.md">English</a> </p>

一个可插拔、可观测、支持 MCP 集成的模块化 RAG（Retrieval-Augmented Generation）服务框架。

---

项目简介

Hybrid RAG MCP Server 是一个面向工程实践的 RAG 项目，目标是将文档摄取、切分、向量化、混合检索、重排、评测和可观测能力解耦成可组合模块，方便你按需替换模型、向量库和检索策略。

项目适合以下场景：

• 企业知识库检索
• 文档问答与内部搜索
• MCP 工具化知识增强
• RAG 流程实验与评测
• 可观测的检索系统原型开发

核心特性

• 模块化架构：LLM、Embedding、Vector Store、Reranker、Loader、Splitter 都可替换
• 混合检索：支持 Dense Retrieval + Sparse Retrieval + RRF Fusion
• 可选重排：支持关闭或启用 rerank 进行二阶段精排
• 文档摄取：支持 PDF、TXT、Markdown、DOCX 等常见文档格式
• 可观测性：内置 ingestion/query trace、评测历史与可视化 Dashboard
• MCP 集成：可以通过 MCP Tool 形式暴露知识检索能力
• 交互式调试：提供 Query Playground 页面查看 dense / sparse / fusion / rerank 结果

界面预览

Query Playground

用于直接发起查询，查看 dense / sparse / fusion / rerank 的召回效果。

Data Browser

用于浏览已导入文档、chunk 内容、图片与元数据。

系统组成

项目主要由以下部分组成：

• src/core/：查询编排、响应构建、追踪上下文等核心逻辑
• src/ingestion/：文档摄取、切分、编码、索引与存储
• src/libs/：模型、向量库、加载器、重排器等适配层
• src/mcp_server/：MCP Server 与工具定义
• src/observability/：日志、评测、Dashboard
• scripts/：常用命令行入口
• tests/：单元测试与集成测试

快速开始

1. 创建虚拟环境并安装依赖

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

2. 配置模型与服务

编辑 config/settings.yaml，填入你自己的配置：

• llm.api_key
• embedding.api_key
• 可选的 vision_llm.api_key
• 如果使用 OpenAI 兼容服务，请确认 base_url 正确

也可以优先使用环境变量，例如：

export OPENAI_API_KEY="your_api_key"

建议不要把真实密钥直接写入仓库并提交到 GitHub。

3. 导入文档

./.venv/bin/python scripts/ingest.py --file path/to/your.pdf --collection default

4. 运行查询

./.venv/bin/python scripts/query.py \
  --query "纳瓦尔 财富 幸福" \
  --collection default \
  --verbose

5. 启动可视化 Dashboard

./.venv/bin/python scripts/start_dashboard.py --host 127.0.0.1 --port 8501

浏览器打开：http://127.0.0.1:8501

可使用页面包括：

• Overview
• Data Browser
• Ingestion Manager
• Ingestion Traces
• Query Playground
• Query Traces
• Evaluation Panel

配置说明

关键配置位于 config/settings.yaml：

• llm：大语言模型配置
• embedding：向量模型配置
• vector_store：向量数据库配置
• retrieval：Dense / Sparse / Fusion 参数
• rerank：重排配置
• evaluation：评测配置
• observability：日志与 trace 配置
• ingestion：切分、批处理等摄取参数

常见说明

• 当前中文查询的规则分词较简单，Sparse Retrieval 对“空格分隔关键词”更友好
• 如果你更重视中文稀疏召回，建议后续接入更好的中文分词方案
• 默认不提交 data/、logs/、虚拟环境与本地 IDE 配置

测试

运行全部测试：

./.venv/bin/python -m pytest

运行部分测试：

./.venv/bin/python -m pytest tests/unit -q