QDrant Loader

QDrant Loader

📝 v1.0.4 更新日志 - 最新改进和错误修复

🎯 什么是 QDrant Loader？

QDrant Loader 是一个数据摄取和检索系统，可从多个来源收集内容，对其进行处理和向量化，然后通过 Model Context Protocol（MCP）服务为 AI 开发工具提供智能搜索功能。

适用于：

• 🤖 AI 驱动的开发，可搭配 Cursor、Windsurf 和其他兼容 MCP 的工具使用
• 📚 创建知识库，汇集技术文档
• 🔍 智能代码辅助，提供上下文信息
• 🏢 企业内容集成，整合多个数据源

📦 软件包

此单一代码库包含三个相辅相成的软件包：

🔄 QDrant Loader

数据摄取和处理引擎

从多个来源收集内容并将其向量化，存入 QDrant 向量数据库。

主要功能：

• 多源连接器：Git、Confluence（Cloud 和 Data Center）、JIRA（Cloud 和 Data Center）、公共文档、本地文件
• 文件转换：使用 MarkItDown 转换 PDF、Office 文档（Word、Excel、PowerPoint）、图像、音频、EPUB、ZIP 等
• 智能分块：采用模块化分块策略，智能处理文档并构建层级上下文
• 增量更新：检测变更并高效同步
• 多项目支持：将数据源整理到项目中，并共享集合
• 不依赖特定提供商的大模型：支持 OpenAI、Azure OpenAI、Ollama 和自定义端点，配置统一

⚙️ QDrant Loader Core

核心库和大模型抽象层

提供其他软件包使用的基础组件和不依赖特定提供商的大模型接口。

主要功能：

• 大模型提供商抽象：为 OpenAI、Azure OpenAI、Ollama 和自定义端点提供统一接口
• 配置管理：集中管理大模型提供商的设置和验证
• 速率限制：内置速率限制和请求管理
• 错误处理：完善的错误处理和重试机制
• 日志记录：结构化日志记录，支持配置级别

🔌 QDrant Loader MCP Server

AI 开发集成层

通过 Model Context Protocol 服务向 AI 开发工具提供搜索功能。

主要功能：

• MCP 协议 2025-06-18：符合最新协议规范，支持双传输方式（stdio + HTTP）
• 高级搜索工具：语义搜索、感知层级的搜索、附件发现和冲突检测
• 跨文档智能分析：文档相似度、聚类、关系分析和知识图谱
• 流式处理能力：通过服务器发送事件（SSE）实时返回搜索结果
• 可用于生产环境：HTTP 传输支持安全防护、会话管理和运行状况检查

🚀 快速开始

安装

# Install both packages
pip install qdrant-loader qdrant-loader-mcp-server

# Or install individually
pip install qdrant-loader          # Data ingestion only
pip install qdrant-loader-mcp-server  # MCP server only

5 分钟完成设置

1. 创建工作区

   mkdir my-workspace && cd my-workspace
   

2. 使用模板初始化工作区

   qdrant-loader init --workspace .
   

3. 配置环境（编辑 .env）

   # Qdrant connection
   QDRANT_URL=http://localhost:6333
   QDRANT_COLLECTION_NAME=my_docs
   
   # LLM provider (new unified configuration)
   OPENAI_API_KEY=your_openai_key
   LLM_PROVIDER=openai
   LLM_BASE_URL=https://api.openai.com/v1
   LLM_EMBEDDING_MODEL=text-embedding-3-small
   LLM_CHAT_MODEL=gpt-4o-mini
   

4. 配置数据源（编辑 config.yaml）

   global:
     qdrant:
       url: "http://localhost:6333"
       collection_name: "my_docs"
     llm:
       provider: "openai"
       base_url: "https://api.openai.com/v1"
       api_key: "${OPENAI_API_KEY}"
       models:
         embeddings: "text-embedding-3-small"
         chat: "gpt-4o-mini"
       embeddings:
         vector_size: 1536
   
   projects:
     my-project:
       project_id: "my-project"
       sources:
         git:
           docs-repo:
             base_url: "https://github.com/your-org/your-repo.git"
             branch: "main"
             file_types: ["*.md", "*.rst"]
   

5. 加载数据

   qdrant-loader ingest --workspace .
   

6. 启动 MCP 服务

   mcp-qdrant-loader --env /path/tp/your/.env
   

🔧 MCP 兼容的 IDE 设置

QDrant Loader 可与任何支持 MCP 的 IDE/工具配合使用，包括 Cursor、Windsurf 和 Claude Desktop。

最简 MCP 服务配置项（根据你的工具调整路径/格式）：

{
  "mcpServers": {
    "qdrant-loader": {
      "command": "/path/to/venv/bin/mcp-qdrant-loader",
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_COLLECTION_NAME": "my_docs",
        "OPENAI_API_KEY": "your_key"
      }
    }
  }
}

替代方案：使用配置文件（推荐用于复杂设置）：

{
  "mcpServers": {
    "qdrant-loader": {
      "command": "/path/to/venv/bin/mcp-qdrant-loader",
      "args": [
        "--config",
        "/path/to/your/config.yaml",
        "--env",
        "/path/to/your/.env"
      ]
    }
  }
}

针对特定工具的设置和准确的配置格式，请参阅：

• MCP 设置与集成 - 完整指南
• Cursor 设置
• Windsurf 设置
• Claude Desktop 设置

在 AI 工具中的查询示例：

• “查找有关我们 API 身份验证的文档”
• “给我看看错误处理模式的示例”
• “此服务有哪些部署要求？”
• “查找所有与数据库架构相关的附件”

📚 文档

入门

• 入门 - 快速入门和核心概念
• 安装指南 - 完整的设置说明
• 快速入门 - 分步教程
• 核心概念 - 了解核心架构：工作区模型、项目与数据源、数据摄取流水线以及 MCP 搜索流程

用户指南

• 用户指南 - 详细的使用说明
• 配置 - 完整的配置参考
• 数据源 - Git、Confluence、JIRA 设置
• 文件转换 - 文件处理功能
• MCP 服务 - AI 工具集成

🛠️ 开发者资源

• 开发者中心 - 关于架构、测试、部署和贡献工作流的开发者指南。
• 架构 - 系统设计概览
• 测试 - 测试指南和最佳实践

🆘 支持

• 问题反馈 - 错误报告和功能请求
• 讨论区 - 社区问答

🤝 参与贡献

欢迎贡献！请参阅我们的贡献指南，了解：

• 开发环境设置
• 代码风格和规范
• 拉取请求流程

快速开发环境设置

# Clone and setup
git clone https://github.com/martin-papy/qdrant-loader.git
cd qdrant-loader

# Sync workspace environment (recommended)
uv sync --all-packages --all-extras

# Add a new dependency during development
uv add fastapi
uv sync

📄 许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。

准备好开始了吗？ 请查看我们的快速入门指南，或浏览完整文档。