MCP-Doc-Retriever — 毫秒级智能文档检索系统

A/B/C 三段式架构 | C++ 高性能引擎 | Python 服务端 | Streamlit 前端 | 完整文档工作流

🚀 核心亮点 ①：毫秒级检索，端到端平均 2.56ms

这是本项目最有竞争力的部分。并非”理论设计”或”预期目标”，而是当前本地运行态实测数据（基准脚本：scripts/benchmark_readme_metrics.py）：

指标	数值
HTTP 端到端平均延迟	2.56 ms
HTTP 端到端中位数	2.51 ms
HTTP 端到端 P95	2.89 ms
服务内核平均延迟	1.41 ms
服务内核 P95	1.72 ms
HTTP 额外封装开销	~1.15 ms

  用户输入查询词
       │
       ▼
  Streamlit 前端 ──HTTP──▶ FastAPI 兼容层 ──▶ tools_core.search_docs()
       │                                            │
       │                                     ┌──────▼──────┐
       │                                     │ 向量召回     │  (1.41ms 内核)
       │                                     │ 词面重排     │
       │                                     │ 阈值过滤     │
       │                                     │ 同源去重     │
       │                                     └──────┬──────┘
       │                                            │
       ◀──────────── JSON 结果 ◀────────────────────┘
       │
       ▼
  标题 / 得分 / 摘要 / 来源路径  +  展开 / 总结 / 导出 / 记忆
                        (HTTP 端到端 2.56ms)

答辩时可表述为：

“当前本地端到端检索平均延迟压到 3ms 以内，属于毫秒级响应。”
“服务内核平均检索耗时约 1.4ms，核心链路本身非常轻量。”
“HTTP 封装额外开销仅约 1.1ms，接口层没有拖慢整体性能。”

架构预留：当前演示使用 numpy-fallback 模式。RetrieverManager 已预留 fast_retriever.pyd（C++ Faiss 引擎）接入位，切回后可在不改前端接口的前提下继续放大检索速度。

📋 核心亮点 ②：完整文档工作流，不只是”搜一下”

本项目不止于检索——围绕文档的完整生命周期，在前后端都做了闭环：

功能	后端接口	前端交互	状态
🔍 语义检索	`POST /mcp/v1/tools/call` (search_docs)	搜索框 → 结果卡（得分/摘要/来源/高亮）	✅
➕ 增删文档	`POST /docs` / `POST /docs/delete`	表单新增 + 文档库选择删除，自动重建索引	✅
📖 展开全文	`GET /docs/content?source=...`	检索结果内展开 + 文档库展开，支持全文高亮	✅
🎯 关键词高亮	前端 `_highlight_text()`	`<mark>` 标签渲染，中英文混合匹配	✅
🤖 文档总结	`GET /docs/summary?source=...`	基于 TF-IDF 的抽取式摘要，展开面板内展示	✅
📥 文档导出	前端 `st.download_button`	全文 Markdown 下载（title + summary + content）	✅
⭐ 记忆文档	`POST /memory/docs` / `GET /memory/docs`	跨会话持久化收藏，JSON 存储，支持展开/总结	✅
📊 健康检查	`GET /health`	实时展示后端/索引/缓存/embedding 状态	✅
📈 历史统计	session_state 记录	请求次数、耗时、调用历史 DataFrame	✅

前端三栏布局：

检索结果 Tab：搜索 → 结果卡（展开/总结/记忆按钮） → 全文面板
文档库 Tab：刷新 → 表格浏览 → 选择 → 展开/总结/记忆/删除 → 新增表单
记忆文档 Tab：收藏夹持久化 → 展开/总结

🏗️ 系统架构

┌─────────────────────────────────────────────────────────┐
│                   C 端 · Streamlit 前端                    │
│         frontend/app.py   │   自定义 CSS 视觉系统          │
│   检索结果 / 文档库 / 记忆文档  三 Tab 布局                  │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTP (requests)
┌──────────────────────▼──────────────────────────────────┐
│              B 端 · Python FastAPI 服务端                   │
│         compat_http_server.py  (兼容 HTTP 接口)           │
│         mcp_server.py          (FastMCP 接口)            │
│  ┌───────────────────────────────────────────────────┐  │
│  │              tools_core.py (业务核心)               │  │
│  │  search_docs · add_document · delete_document      │  │
│  │  get_document · summarize_document                  │  │
│  │  remember_document · list_memory_documents         │  │
│  │  list_files · analyze_topic · get_index_status     │  │
│  └──────┬────────────────────────────────┬───────────┘  │
│         │                                │               │
│  ┌──────▼──────────┐   ┌────────────────▼────────────┐  │
│  │ retriever_mgr   │   │ embedding.py                │  │
│  │ (检索器管理)     │   │ sentence-transformers / hash │  │
│  │ NumPy fallback  │   │ 384维文本向量化              │  │
│  │ + .pyd 预留位   │   └─────────────────────────────┘  │
│  └─────────────────┘                                     │
│  ┌──────────────────────────────────────────────────┐   │
│  │ data_loader.py · 文档加载/分块/PDF解析               │   │
│  │ error_handler.py · 统一异常 → JSON 错误响应          │   │
│  └──────────────────────────────────────────────────┘   │
└──────────────────────┬──────────────────────────────────┘
                       │ pybind11 (预留)
┌──────────────────────▼──────────────────────────────────┐
│              A 端 · C++ Faiss 高性能引擎                    │
│         RapidRetrieverProject/                           │
│         RapidRetriever.h/.cpp · bindings.cpp             │
│         IndexFlatIP · save/load · fast_retriever.pyd     │
└─────────────────────────────────────────────────────────┘

📂 目录说明

Project_CCP/
├── frontend/                          # C 端 —— Streamlit 前端
│   ├── app.py                         #   主入口（1400+ 行完整交互系统）
│   └── requirements.txt
│
├── mcp_server_B_implementation/
│   └── mcp_server_B_implementation/   # B 端 —— Python 服务端
│       ├── compat_http_server.py      #   FastAPI 兼容 HTTP 服务（主入口）
│       ├── mcp_server.py              #   FastMCP 服务（备选入口）
│       ├── tools_core.py              #   ★ 核心业务逻辑（10+ 工具函数）
│       ├── retriever_manager.py       #   检索器管理器（双后端模式）
│       ├── data_loader.py             #   文档加载 / 分块 / PDF解析
│       ├── embedding.py               #   文本向量化（sentence / hash）
│       ├── error_handler.py           #   统一异常处理装饰器
│       ├── requirements.txt
│       ├── start_compat.bat           #   Windows 一键启动脚本
│       ├── start_fastmcp.bat
│       ├── sample_data/docs/          #   多语言语料库（中英法西日）
│       ├── tests/                     #   测试用例
│       ├── .docsearch_cache/          #   磁盘缓存（重启秒开）
│       └── .doc_memory.json           #   记忆文档持久化存储
│
├── RapidRetrieverProject/             # A 端 —— C++ Faiss 检索工程
│   ├── CMakeLists.txt
│   ├── include/
│   │   ├── RapidRetriever.h
│   │   ├── faiss/                     #   Faiss 头文件
│   │   └── pybind11/                  #   pybind11 头文件
│   ├── src/
│   │   ├── RapidRetriever.cpp         #   检索核心实现
│   │   ├── bindings.cpp               #   pybind11 Python 绑定
│   │   ├── buildIndex_detail.cpp      #   构建索引详细注解
│   │   └── search_detail.cpp          #   搜索流程详细注解
│   ├── tests/
│   │   ├── test_native.cpp            #   C++ 原生测试
│   │   └── test_python.py             #   Python 端测试
│   └── README.md
│
├── scripts/
│   └── benchmark_readme_metrics.py    # 性能基准测试脚本
│
├── archive_snapshots/                 # 前端阶段性存档
│   └── frontend_archive_20260709_023021.zip
│
├── fast_retriever.pyd                 # A 端编译产物（Python 直接 import）
└── README.md                          # 本文档

🔧 性能优化策略

策略	说明	收益
磁盘缓存	`.docsearch_cache/` 向量+元信息落盘，重启命中缓存	启动从”全量重建”变为”秒开即用”
分块检索	chunk_size=1100 / overlap=160，段落级+滑窗切片	长文局部命中能力更强
词面重排	向量召回后对标题/正文做 token overlap + 短语 bonus	弱化 fallback embedding 噪声
阈值过滤	hash 模式 min_score=0.18，自动拒绝低相关结果	无关查询不强行返回
同源去重	同一文档多个 chunk 只保留首条命中	结果多样性提升
双后端模式	NumPy fallback + .pyd 预留位，自动检测切换	降级可运行，升级可扩展

⚡ 快速启动

环境要求

Python 3.9+
依赖：pip install fastapi uvicorn pydantic numpy pypdf pandas

1. 启动后端

cd mcp_server_B_implementation/mcp_server_B_implementation
export DOCSEARCH_EMBED_BACKEND=hash
python compat_http_server.py --host 127.0.0.1 --port 8001

Windows 可直接双击 start_compat.bat。

2. 启动前端

cd ../..
streamlit run frontend/app.py

3. 健康检查

curl http://127.0.0.1:8001/health

📡 接口说明

检索接口

POST /mcp/v1/tools/call

{
  "name": "search_docs",
  "arguments": { "query": "什么是 MCP 协议", "top_k": 5 }
}

返回：rank · doc_id · title · score · raw_score · snippet · source

文档工作流接口

方法	路径	说明
GET	`/health`	服务健康状态 + 索引诊断信息
GET	`/docs`	文档库列表（聚合去重）
GET	`/docs/content?source=...`	获取文档全文
GET	`/docs/summary?source=...`	文档抽取式摘要
POST	`/docs`	新增文档（title + content）
POST	`/docs/delete`	删除文档（source）
GET	`/memory/docs`	记忆文档列表
POST	`/memory/docs`	添加记忆文档

🌍 当前语料库

语料目录：mcp_server_B_implementation/mcp_server_B_implementation/sample_data/docs/

覆盖主题：

MCP / Model Context Protocol
HTTP / API Basics
Faiss / Vector Search
Streamlit App Basics
中文 embedding / 向量检索 / RAG / 联调
西语信息检索 · 日语概念搜索 · 法语 HTTP 参考

当前运行态：

source_files = 13 · total_docs = 16 chunks · dim = 384
backend = numpy-fallback · embedding.backend = hash-forced
cache_loaded = true · min_score = 0.18
avg_chunk_length = 597.6 · chunk_size = 1100

🧪 推荐测试查询

查询	预期
`what is MCP`	命中 MCP 协议文档
`HTTP GET and POST methods`	命中 HTTP 参考
`Streamlit session state`	命中 Streamlit 文档
`embedding 相似度`	命中向量检索文档
`recuperación de información`	命中西语文档
`概念検索`	命中日语文档
`banana tractor quantum`	应返回空（阈值过滤）

⚠️ 当前局限

仍使用 hash-forced embedding，语义质量非最终上限
仍使用 numpy-fallback，性能非最终上限
fast_retriever.pyd 尚未稳定接回正式联调服务

📌 下一步优化方向

升级 Python 3.10+ 环境，恢复 sentence-transformers
正式接回 fast_retriever.pyd（C++ Faiss 引擎）
扩展语料规模，验证更大数据集上的重排/去重策略
接入 LLM API，将抽取式摘要升级为生成式摘要

👥 分工

角色	职责	技术栈	交付物
A 同学	C++ 高性能检索引擎	C++17 · Faiss · pybind11 · CMake	`fast_retriever.pyd` + 源码
B 同学	MCP 服务端 + 业务核心	Python · FastAPI · FastMCP · NumPy	`compat_http_server.py` + 10+ 工具函数
C 同学	前端交互 + 演示 + 文档	Streamlit · requests · pandas · CSS	`app.py` + PPT + 演示视频