AI导哈

PDF语义搜索服务

基于CrewAI的PDFSearchTool构建的轻量级模型上下文协议(MCP)服务器和CLI工具，支持通过自定义嵌入/Qdrant堆栈对PDF进行索引和语义搜索。

  • by DRanger666
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 DRanger666/pdf-search-mcp

使用说明

PDF搜索MCP服务器

封装CrewAI的轻量级模型上下文协议（MCP）服务器和CLI工具 PDFSearchTool 因此，您可以使用自己的嵌入/Qdrant堆栈对PDF进行索引和语义搜索。

组件

  • MCP服务器 (pdfsearch.mcp_pdfsearch)：暴露a search_pdf 该工具验证输入的PDF，确保配置的Qdrant集合存在，并运行CrewAI搜索。
  • CLI线束 (scripts/test_pdfsearch_tool.py)：面向开发人员的脚本，可以对PDF进行指纹识别，记录缓存元数据，跳过缓存命中的重新摄取，并允许您在没有使用MCP的客户端的情况下运行即席查询。
  • 缓存助手 (src/pdfsearch/cache.py)：计算SHA-256哈希值的共享实用程序，按PDF集合名称导出(pdf_<hash[:12]>)，将元数据持久化 ~/.cache/pdf_search_mcp/cache.json，并跟踪PDF是否已被索引（步骤 1–3 缓存卷展栏）。

需求

  • Python 3.8+
  • 访问CrewAI支持的嵌入服务提供商（推荐VoyageAI）
  • 可访问的Qdrant实例（云或自托管）

安装

pip install -e .
cp .env.example .env
# populate .env with your real credentials

配置

Config (src/pdfsearch/config.py)读取以下环境变量：

变量 必填 备注
EMBEDDER_PROVIDER 必填 例如。 voyageai, openai等等。
EMBEDDER_MODEL 必需 特定于提供商的型号ID（例如。 voyage-code-3).
EMBEDDER_API_KEY 有条件的
EMBEDDINGS_VOYAGEAI_API_KEY 有条件的* 需要时 EMBEDDER_PROVIDER=voyageai；自动覆盖 EMBEDDER_API_KEY.
QDRANT_URL 必需 Qdrant服务的HTTPS URL或本地终结点。
QDRANT_API_KEY 可选 托管Qdrant部署需要。
VECTOR_SIZE 必需 嵌入的整数维度。
VECTOR_DISTANCE 必填 其中之一 Cosine, Euclid, Dot等等。（比赛 qdrant_client.models.Distance).
LOG_LEVEL 可选 默认为 INFO.

提示： .env.example 枚举服务器期望的每个变量。复制到 .env，填写您的值，CLI/MCP服务器将通过以下方式加载它 python-dotenv.

运行CLI线束

python scripts/test_pdfsearch_tool.py \
  --pdf sample_pdfs/manual.pdf \
  --query "explain the architecture" \
  --limit 5 \
  --similarity-threshold 0.6 \
  --format pretty

它的作用：

  1. 负载 .env，验证PDF（扩展名+ %PDF- 头球
  2. 计算PDF哈希值并导出Qdrant集合名称(pdf_<hash>).
  3. 在中记录缓存元数据（路径、哈希、集合、摄取标志） ~/.cache/pdf_search_mcp/cache.json.
  4. 初始化 PDFSearchTool 使用embeddings+Qdrant配置，并强制适配器使用派生集合。
  5. 在第一次运行时，将PDF摄取到Qdrant中，并将缓存条目标记为索引；当缓存显示PDF已被索引时，后续运行跳过摄取并重用现有向量。
  6. 使用适配器的低级发出相似性搜索 client.search() 用于结构化结果的API（包括 chunk_index、标准化得分和Qdrant point_id).

重置集合：如果需要重新摄取（例如，在删除Qdrant集合后），请从中删除哈希条目 ~/.cache/pdf_search_mcp/cache.json 或切换其 "indexed" 旗帜到 false 在重新运行CLI之前。

运行MCP服务器

pdf-search-mcp
# or
python -m pdfsearch.mcp_pdfsearch

服务器注册了一个MCP工具：

工具 描述 Args
search_pdf 通过CrewAI验证/摄取PDF并运行语义搜索 pdf_path （字符串，必填）， query （字符串，必填）

在内部，服务器引导共享 PDFSearchTool 反对 pdf_search_bootstrap 收集以在启动时验证配置，然后将其重新用于传入的工具调用。

缓存推出

看 docs/caching_rollout_plan.md 对于从简单的指纹识别（已实现）到每个PDF集合、摄取跳过、CLI缓存检查、并发保护，并最终与MCP服务器共享缓存逻辑的分阶段计划。

当前状态：

  • Step 1 complete：哈希+JSON缓存助手(src/pdfsearch/cache.py).
  • Step 2 完整：确定性集合名称+适配器重定向。
  • Step 3 complete：CLI中的缓存感知摄取跳过（除非重置缓存，否则每个PDF集合只填充一次）。
  • Step 4 除此之外（CLI缓存检查/清除标志、锁定、MCP重用）仍在路线图上。

开发说明

  • 传统的pytest脚手架现在存在 legacy_tests/；它是 不 已连接到活动测试套件，但保留以供参考。看 docs/notes/legacy_testing_strategy.md 用于原始测试视觉。
  • docs/notes/gpt_codex_debugging.md 捕获CrewAI vectordb配置期望的调试研究。
  • 默认情况下忽略示例PDF(sample_pdfs/ 在 .gitignore)；添加您自己的用于本地测试。

故障排除

  • ValueError: EMBEDDER_PROVIDER environment variable is required –确保 .env 已加载（CLI使用 python-dotenv)并且设置变量。
  • File does not appear to be a valid PDF –验证器检查 %PDF- 头球如果生成的PDF不正确，请再次导出/下载。
  • Qdrant收集错误 –配置层调用 client.get_or_create_collection(...).验证 VECTOR_SIZE, VECTOR_DISTANCE，以及 QDRANT_URL/API key 匹配您的部署。
  • 多次运行后重复块 –删除Qdrant中的每个PDF集合（例如。， curl -X DELETE http://<qdrant-host>/collections/pdf_<hash>) 和 删除或编辑中的匹配条目 ~/.cache/pdf_search_mcp/cache.json 所以 "indexed" 成为 false 在重新运行CLI之前。

相关 MCP