Docsplorer统一
一个生产就绪的开源堆栈 语义文档搜索.
Docsplorer Unified结合了：
- 搜索API –由Qdrant支持的FastAPI服务，用于对文档进行矢量搜索。
- Docsplorer MCP服务器 –模型上下文协议（MCP）服务器，向基于LLM的代理、IDE和工作流引擎提供强大的搜索工具。
此存储库专为希望对其技术文档（发行说明、指南、PDF等）进行索引并使用现代嵌入和矢量搜索进行查询的团队而设计。
______________________________________________________________________
特性
- 矢量搜索API 用于对文档进行丰富的语义查询。
- 配备多种工具的MCP服务器 用于文件名发现、单文档搜索、多文档比较和批量查询。
- 通过Olama或Gemini嵌入 （可通过环境变量配置）。
- 统一配置 使用单个
.envrepo根目录下的文件。 - Docker编写设置 只需一个命令即可运行整个堆栈。
- HTTP和stdio传输 适用于MCP服务器，适用于IDE和基于HTTP的工具。
- 麻省理工学院许可和公开，非常适合作为您自己的文档搜索堆栈的模板或起点。
______________________________________________________________________
架构概述
Docsplorer Unified由两个服务组成：
- 搜索API（FastAPI+Qdrant）
- 公开语义内容搜索和模糊文件名搜索的端点。 - 使用矢量数据库（Qdrant）来存储和查询文档嵌入。 - 通过抽象层支持多个嵌入后端（例如Ollama、Gemini）。
- Docsplorer MCP服务器（FastMCP）
- 实现模型上下文协议（MCP），以便LLM客户端可以调用工具。 - 通过HTTP与搜索API通信。 - 提供以下工具： - search_filenames_fuzzy –按文件名查找候选文档。 - search_with_filename_filter -在特定文档中搜索。 - search_multi_query_with_filter –在一个文档中运行多个查询。 - search_across_multiple_files –在多个文档中搜索主题。 - compare_versions –比较两个版本之间主题的变化情况。
这两项服务都是通过 docker-compose.yml 并共享一个 .env 配置文件。
______________________________________________________________________
仓库布局
docsplorer-unified/
├── .env # Your environment configuration (not committed)
├── .env.example # Example env file with all variables and explanations
├── docker-compose.yml # Orchestrates Search API + MCP server
├── Makefile # Optional developer convenience commands
├── services/
│ ├── search-api/ # FastAPI-based semantic search API
│ └── mcp-server/ # Docsplorer MCP server
└── docs/ # (Optional) documentation for your deployment注： .env.example 该文件记录了所有配置变量，是设置堆栈时的最佳起点。______________________________________________________________________
入门指南
1.先决条件
- 码头工人 和 Docker Compose 安装。
- 跑步 Qdrant 实例（本地Docker或托管服务）。
- 一 奥拉玛 实例（用于本地嵌入）或 双子座 API密钥。
2.克隆存储库
git clone https://github.com/Crypto-Gi/docsplorer-unified.git
cd docsplorer-unified3.配置环境变量
复制示例env文件：
cp .env.example .env打开 .env 并根据您的环境调整值。您至少需要设置：
QDRANT_DEV_URL–您的dev Qdrant实例的URL（例如。，http://localhost:6333或您的实验室服务器）。EMBEDDING_PROVIDER–ollama或gemini.- 对于 奥拉玛:
- OLLAMA_HOST –Ollama服务器的URL。 - OLLAMA_EMBEDDING_MODEL -嵌入模型名称（例如。， bge-m3).
- 对于 双子座:
- GEMINI_API_KEY –您的Gemini API密钥。
这 .env.example 该文件包括解释每个变量的详细注释。
4.使用Docker Compose启动堆栈
从repo根目录：
docker compose up --build这将：
- 构建并启动 搜索API （FastAPI+Qdrant客户端）。
- 构建并启动 Docsplorer MCP服务器 （端口8505上的HTTP模式）。
健康检查将验证这两个服务是否都在运行。
______________________________________________________________________
服务和港口
默认情况下：
- 搜索API:
http://localhost:8001
- 内部集装箱端口： 8000 - 通过Docker Compose公开 SEARCH_API_PORT 在 .env.
- MCP HTTP服务器:
http://localhost:8505
- 提供 /mcp MCP客户端的端点。 - 提供 /health 进行健康检查。
您可以通过以下方式自定义端口 .env （例如。， SEARCH_API_PORT, MCP_HTTP_PORT).
______________________________________________________________________
使用MCP服务器
Docsplorer MCP服务器设计用于：
- IDE和MCP感知客户端 使用stdio传输。
- HTTP客户端/工作流引擎 （例如，自定义脚本、自动化平台）通过HTTP。
HTTP模式
在Docker Compose下运行时，MCP服务器以HTTP模式启动，可以在以下位置访问：
http://localhost:8505/mcp您的MCP客户端或集成应配置为向此URL发送符合MCP的HTTP请求。
标准模式（地方发展）
对于没有Docker的本地开发，您可以直接运行MCP服务器（从 services/mcp-server):
python server.py # defaults to stdio transport这在与通过stdio传输MCP的IDE集成时非常有用。
______________________________________________________________________
搜索API概述
搜索API（FastAPI）负责：
- 为查询生成嵌入。
- 查询Qdrant以查找最近的邻居。
- 应用过滤器（例如，按文件名或元数据）。
- 返回匹配页面周围的排名结果和可选上下文窗口。
典型流程包括：
- 通过模糊文件名搜索发现相关文档。
- 选择一个或多个文件名并执行语义内容搜索。
- 检索上下文（前后页面）以获得更好的LLM提示。
所有请求都是基于JSON的，MCP服务器为您处理有效载荷构造。
______________________________________________________________________
配置亮点
关键环境组（见 .env.example 详细信息）：
- 全局设置:
ENVIRONMENT,DEBUG,REQUEST_TIMEOUT - Qdrant开发/产品配置:
QDRANT_DEV_URL,QDRANT_PROD_URL,QDRANT_DEV_API_KEY,QDRANT_PROD_API_KEY - 嵌入提供者:
EMBEDDING_PROVIDER,OLLAMA_*,GEMINI_* - 搜索默认值:
CONTEXT_WINDOW_SIZE,DEFAULT_RESULT_LIMIT,USE_PRODUCTION - MCP服务器:
SEARCH_API_URL,MCP_TRANSPORT,MCP_HTTP_HOST,MCP_HTTP_PORT
目标是有一个 单一事实来源 用于两个服务都使用的配置。
______________________________________________________________________
生产部署
对于生产部署，您可以：
您有两个选择：
- 使用GitHub容器注册表（GHCR）中的预构建映像
- 构建并推广您自己的图像
选项1：使用预构建图像（推荐）
预构建图像发布在：
- 搜索API：
ghcr.io/crypto-gi/docsplorer-search-api:v0.1.1和:latest - MCP服务器：
ghcr.io/crypto-gi/docsplorer-mcp-server:v0.1.1和:latest
示例 docker-compose.yml 片段使用 latest:
services:
search-api:
image: ghcr.io/crypto-gi/docsplorer-search-api:latest
# ... rest of config (env, ports, healthchecks)
mcp-server:
image: ghcr.io/crypto-gi/docsplorer-mcp-server:latest
# ... rest of config (env, ports, healthchecks)然后在任何可以访问GHCR的主机上：
docker compose pull
docker compose up -d选项2：构建和推送自己的图像
您可以从您的fork或此仓库的自定义版本构建映像：
# From repo root
docker build -t ghcr.io//docsplorer-search-api:v0.1.1 services/search-api
docker build -t ghcr.io//docsplorer-mcp-server:v0.1.1 services/mcp-server
docker push ghcr.io//docsplorer-search-api:v0.1.1
docker push ghcr.io//docsplorer-mcp-server:v0.1.1然后在中引用您自己的图像名称和标签 docker-compose.yml 或Kubernetes清单。
环境与安全
- 配置
ENVIRONMENT=production并使用QDRANT_PROD_*生产Qdrant集群的变量。 - 如果需要，在MCP服务器和搜索API之间启用API密钥验证。
- 确保TLS/HTTPS用于生产Qdrant和任何外部端点。
部署后，将MCP客户端或工作流引擎指向MCP HTTP端点（例如 http://your-host:8505/mcp).
______________________________________________________________________
贡献
欢迎捐款。如果您愿意：
- 添加对新嵌入提供程序的支持。
- 集成其他MCP工具。
- 改进文档或示例。
请随时打开问题或提交拉取请求。
请遵循标准最佳实践：
- 分叉仓库并创建一个功能分支。
- 在适当的情况下添加或更新测试。
- 保持变更的重点并做好记录。
______________________________________________________________________
许可证
该项目根据 MIT许可证。请参阅 许可证 文件以获取详细信息。
______________________________________________________________________
关键词（SEO）
语义搜索、向量搜索、Qdrant、Ollama、Gemini、MCP服务器、模型上下文协议、文档搜索、发行说明搜索、FastAPI、Python、Docker、Docker Compose、LLM工具、IDE集成、HTTP MCP、stdio MCP、AI驱动的文档搜索、语义文档浏览器。