rag-mcp-server

基于 PyTorch 官方文档的 RAG 知识检索 MCP Server：双向量库（FAISS + Chroma）混合检索，DeepSeek 生成带引用的回答，能力通过 FastMCP 暴露为标准工具，可被 Claude 等 MCP 客户端直接调用。

功能特性

• 双向量库：FAISS（IndexFlatIP 精确余弦，主检索）+ Chroma（持久化 / where 过滤 / 备份对照），统一 md5(chunk_id) 对齐，构建后自动校验双库 top-5 重合率 ≥ 90%
• 章节感知分块：按 API entry 语义切分，超长块递归切分 + overlap，保证代码签名不被拦腰截断
• 混合检索：向量（BGE）+ 关键词（BM25）双路，RRF(k=60) 融合，规避两路分数量纲不可比
• 带引用回答：DeepSeek 基于检索上下文生成，强制 [n] 引用 + Sources，越界引用后校验剔除；资料不足正确降级拒绝，不编造
• MCP Server：search / ask / list_topics / stats 四个标准工具，lifespan 只加载一次模型

架构

PyTorch 官方文档 (HTML)
        │  loader.py  解析 <dl> 签名+描述
        ▼
      Document ──► chunker.py  章节感知分块 (447 chunks / 96 API topics)
        │  embedder.py  BGE 文档编码 (无 instruction, 384 维)
        ▼
┌────────────────────────── 建库 ──────────────────────────┐
│   FAISS (IndexFlatIP) 主检索       Chroma 持久化/过滤      │
│   同批 chunk，md5 chunk_id 对齐，双库重合率 ≥90% 校验      │
└───────────────────────────────────────────────────────────┘
        ▲
        │  embed_query (查询加检索前缀)
        │
问题 ──► HybridRetriever = 向量 top-k + BM25 top-k ──► RRF 融合 ──► top-k Chunk
        │
        ▼
 Generator.generate: 编号[1]..[n] 组装 context ──► DeepSeek ──► 回答 + [n] 引用
        │                        ▲
        │               引用校验 _extract_citations (越界/非数字剔除)
        ▼
 FastMCP tools: search / ask / list_topics / stats   (lifespan 单次加载)

技术栈

Python 3.13 · FAISS · Chroma · sentence-transformers (BGE) · rank_bm25 · LangChain · DeepSeek · FastMCP

快速开始

1. 环境

python -m venv .venv
# Windows: .venv\Scripts\activate    Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt

BGE 模型需从 HuggingFace 下载，国内可设镜像（config.py 已默认写入 HF_ENDPOINT=https://hf-mirror.com）。

2. 配置密钥

复制 .env.example 为 .env，填入 DeepSeek API Key：

cp .env.example .env   # 填入 DEEPSEEK_API_KEY

也可直接用环境变量 DEEPSEEK_API_KEY，不需要 .env 文件。

3. 构建索引

PYTHONPATH=src python scripts/build_index.py

输出示例：n_chunks=447, dim=384, dual_store_overlap=0.93+。

索引数据在 data/（已被 .gitignore 排除，可随时重建，幂等）。

4. 命令行问答

# 单次提问
PYTHONPATH=src python -m ragmcp.cli.demo "How to create a Linear layer in PyTorch?"

# 交互式（输入 exit 退出）
PYTHONPATH=src python -m ragmcp.cli.demo

5. 启动 MCP Server

PYTHONPATH=src python -m ragmcp.server.mcp_server    # stdio transport

注册进 Claude Code / Cursor 等客户端后，即可通过标准工具调用：

工具	说明
search	混合检索（向量 + BM25），返回 top-k 来源片段与分数
ask	端到端问答，返回带 [n] 引用的回答 + Sources
list_topics	知识库覆盖的 API 主题列表
stats	知识库统计（分块数 / 文档数 / 主题数 / 维度）

客户端验收脚本：

PYTHONPATH=src python scripts/test_mcp_client.py

6. 测试

PYTHONPATH=src python -m pytest tests/ -v

目录结构

rag-mcp-server/
├── scripts/
│   ├── download_docs.py    # 下载 PyTorch 文档页
│   ├── build_index.py      # 全量构建双向量库（幂等）
│   └── test_mcp_client.py  # MCP stdio 客户端验收
├── src/ragmcp/
│   ├── config.py           # pydantic-settings 配置
│   ├── ingestion/          # loader(HTML/PDF) chunker(章节感知) embedder(BGE)
│   ├── storage/            # faiss_store chroma_store indexer(双写+对齐校验)
│   ├── retrieval/          # keyword(BM25) hybrid(RRF+加权融合)
│   ├── generation/         # generator(DeepSeek + [n]引用 + 降级)
│   ├── service/            # rag_service(编排 search/ask/list_topics/stats)
│   ├── server/             # mcp_server(FastMCP 4 工具) lifespan(单次加载)
│   └── cli/                # demo(命令行问答)
├── tests/                  # chunker / keyword / hybrid / generator
├── data/                   # gitignore：raw / chroma / faiss
├── requirements.txt
└── .env.example

关键设计（面试可讲）

1. 双向量库分工：FAISS 快、精确余弦、无持久化；Chroma 落盘、where 过滤、备份对照。统一 md5(source|index) 的 chunk_id 对齐，构建后双库 top-5 重合率校验，证明双库结果一致。
2. BGE 检索姿势：文档编码不加 instruction、查询编码加前缀 "Represent this sentence for searching relevant passages: "，配合 normalize_embeddings=True 使 IndexFlatIP 内积 = 余弦。
3. RRF 融合：向量分（-1~1）与 BM25 分（0~几十）量纲不可比，直接加权无意义；RRF 只看排名（k=60，Cormack 2009），跨打分器鲁棒。
4. 引用后校验：LLM 会幻觉出 context 里不存在的编号，_extract_citations 只保留 1<=n<=total 的合法引用，Sources 才可信。
5. 无答案降级：_low_confidence 阈值（0.02，实测校准）+ SYSTEM_PROMPT 规则 3 双保险，资料不足明确拒绝，不编造。
6. lifespan 单次加载：BGE 模型（~130MB）+ FAISS 索引在服务启动时加载一次，所有工具调用复用，stdio 会话不重载。