PDF检索增强生成服务

PDF RAG MCP服务器

使用队列感知的FastAPI后端、LanceDB矢量搜索、SQLite元数据和Chakra UI仪表板将大量PDF处理到检索增强生成（RAG）知识库中。模型上下文协议（MCP）层将相同的语料库呈现给代理和IDE，因此搜索结果在客户端之间保持一致。

特性

• 可配置的摄取管道，带有PyMuPDF或Docling解析和本地/OpenAI嵌入。
• 具有进度回调、SHA-256重复数据删除和元数据丰富功能的有界工作队列。
• REST、MCP和观察者共享的线程安全SQLite markdown存储库和LanceDB向量存储。
• 递归目录观察器，用于下一步的删除和进程摄取 <DATA_DIR>/pdfs.
• 提供REST端点、MCP传输和静态前端资产的统一FastAPI服务器。
• React+Chakra UI仪表板，用于队列监控和语义搜索。

建筑

src/
  backend/
    api.py           # REST + MCP endpoints and job manager
    processor.py     # Queue, workers, parsing + embedding pipeline
    config.py        # Environment-driven settings
    storage/         # SQLite MarkdownRepository + LanceDB VectorStore
    parsers/         # PyMuPDF and Docling adapters
    embeddings/      # EmbeddingManager (local / OpenAI)
  frontend/
    src/             # React + Chakra UI SPA
    package.json

快速启动

1. 安装必备组件 –Python 3.11+、Node.js 20+、Docker（可选）、用于GPU摄取的NVIDIA容器工具包。
2. Bootstrap后端
   复制

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

3. 构建前端
   复制

   cd src/frontend
   npm install
   npm run build
   

4. 在本地运行
   复制

   uvicorn src.backend.api:app --host 0.0.0.0 --port 8000 --reload
   

   对于热重载UI开发，请运行 npm run dev 在 src/frontend （服务http://localhost:5173).否则，FastAPI将服务于 frontend/dist 直接捆绑。

配置

所有设置都是环境驱动的（请参见 .env.sample).

存储凭据，例如 OPENAI_API_KEY 在 .env （被git忽略）或平台秘密存储。

处理管道

1. 排队——上传、观察者发现和同步请求成为 ProcessingTasks在一个有界的队列中。
2. 工作池——可配置的守护进程线程将任务排成队列，发出生命周期回调，并隔离故障。
3. 元数据丰富——文件系统统计数据与调用者提供的元数据合并。
4. 解析-PyMuPDF或Docling生成markdown。
5. 重复数据消除-SHA-256哈希查找跳过重新摄取相同内容。
6. 持久性-标记保存到SQLite；嵌入块被分块并添加到具有余弦索引的LanceDB中。

REST端点、MCP工具和观察器都流经此管道，以实现一致的行为。

目录监视器

• 默认启用(WATCH_ENABLED=true).
• 递归扫描 WATCH_DIR 为了 *.pdf 文件夹。
• 在多次故障后跳过已存储或列入黑名单的路径。
• 将任务添加到共享队列中，以便观察程序处理尊重背压并发出进度事件。
• 通过设置禁用 WATCH_ENABLED=false 或者通过环境变量调整轮询间隔/重试阈值。

REST+MCP接口

Claude桌面配置：

{
  "mcpServers": {
    "pdf-rag": {
      "type": "http",
      "url": "http://localhost:8000"
    }
  }
}

前端仪表板

• npm run dev –Vite开发服务器，热重载。
• npm run build –FastAPI提供的生产捆绑包。
• npm run ci:build –TypeScript类型检查+构建（匹配CI）。

UI公开了一个处理队列选项卡（实时进度、重试、失败）和一个搜索选项卡，用于具有元数据预览的语义查询。

Docker工作流程

# Pull published image (recommended)
docker run --rm -p 8000:8000 ghcr.io/tekgnosis-net/pdf-rag-mcp:latest

# Build locally
docker build -t pdf-rag-mcp .
docker run --rm -p 8000:8000 pdf-rag-mcp

# Docker Compose (uses GHCR image by default)
docker compose up --build

GPU加速：

docker run --rm -p 8000:8000 --gpus all \
  -e EMBEDDING_DEVICE=cuda \
  ghcr.io/tekgnosis-net/pdf-rag-mcp:latest

安装 ./data 到 /app/data 用于持久SQLite/LanceDB存储，并将主机文件夹映射到 /app/data/pdfs 给观察者喂食。

开发工作流程和CI奇偶校验

在推送之前，运行GitHub Actions强制执行的相同检查：

.venv/bin/ruff check .
.venv/bin/pytest -q
(cd src/frontend && npm ci && npm run ci:build)
docker build -t pdf-rag-mcp-local .

这些步骤反映了 Test, Build and Publish 工作流（lint、pytest、前端类型检查/构建、Docker构建）。

故障排除

许可证

麻省理工学院许可证©2025项目贡献者