Rag Duckdb With MCP

🚀 基于DuckDB的Python RAG服务器

本项目是一个基于Python的服务器，专为文档处理和检索增强生成（RAG）而设计。它提供了一个简单的Web界面和JSON API，用于上传文档、将文档处理成块、生成嵌入向量，并将其存储在DuckDB数据库中，以便进行高效的相似性搜索。

整个应用程序使用Docker进行容器化，并使用uv进行快速、优化的依赖管理。此外，它还包含一个mcp-rag-service，用于与MCP（机器理解平台）集成。

✨ 主要特性

• Web界面：简约的用户界面，可用于上传文件、启动处理和执行搜索。
• JSON API：提供/api/search、/api/stats和/health端点，便于进行程序化集成。
• 广泛的文件支持：支持处理多种文件类型，包括.txt、.md、.pdf以及多种编程语言的源文件（如.py、.js、.java等）。
• 高级分块策略：根据文件类型采用不同的分块策略（例如，对源代码使用CodeSplitter，对文本使用RecursiveCharacterTextSplitter）。
• 高质量嵌入向量：使用sentence-transformers/paraphrase-multilingual-mpnet-base-v2（主要，768维）或sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2（备用，384维）。
• 向量数据库：利用带有VSS（向量相似性搜索）扩展的DuckDB进行嵌入向量的高效存储和查询。
• 容器化与优化：
  • 可使用Docker轻松构建和运行。
  • 使用uv实现超快速的依赖安装。
  • 采用多阶段Dockerfile，使最终镜像体积更小。
  • 支持在无GPU的环境中进行仅CPU构建。
• MCP集成：包含一个示例mcp-rag-service，用于演示与外部系统的集成。
• 目录上传：支持上传整个目录，并可进行文件扩展名过滤。
• 健康监控：内置健康检查端点，便于监控和负载均衡。

🔧 技术细节

• 后端：使用FastAPI的Python
• 嵌入向量：sentence-transformers、llama-index、langchain
• 数据库：DuckDB + VSS扩展
• 容器化：Docker
• 包管理：uv

📦 安装指南

前提条件

• 已在您的机器上安装并运行Docker。

构建并运行Docker容器

1. 克隆仓库：

git clone <repository-url>
cd <repository-name>

2. 构建Docker镜像： 构建过程使用多阶段Dockerfile和uv进行了优化。您可以选择标准构建（包含支持GPU的库）或仅CPU构建。

标准构建（适用于支持GPU的环境）：

docker build -t rag-duckdb-server .

仅CPU构建（推荐用于本地开发或仅使用CPU的服务器）： 此构建通过使用仅CPU版本的PyTorch，速度更快，且生成的镜像体积更小。

docker build --build-arg USE_CPU_ONLY=true -t rag-duckdb-server-cpu .

3. 运行Docker容器： 此命令将启动服务器，并将本地的uploads和data目录映射到容器中。这样，即使容器被移除，您上传的文件和数据库也会保留。

对于标准构建：

docker run -p 8000:8000 \
  -v "$(pwd)/uploads:/app/uploads" \
  -v "$(pwd)/data:/app/data" \
  --name rag-server \
  rag-duckdb-server

对于仅CPU构建：

docker run -p 8000:8000 \
  -v "$(pwd)/uploads:/app/uploads" \
  -v "$(pwd)/data:/app/data" \
  --name rag-server-cpu \
  rag-duckdb-server-cpu

Windows用户注意：在PowerShell中使用${pwd}代替$(pwd)。

4. 访问应用程序： 打开您的Web浏览器，导航到http://localhost:8000。

💻 使用示例

基础用法

1. 上传文件：使用Web界面选择并上传一个或多个受支持的文件。
2. 上传目录：或者，上传整个目录，并进行文件扩展名过滤，以仅处理特定类型的文件。
3. 处理文件：点击“开始处理”按钮。服务器将执行以下操作：
   • 提取文本内容。
   • 将文本分割成易于管理、具有上下文感知的块。
   • 为每个块生成向量嵌入。
   • 将块及其嵌入保存到data/rag.duckdb数据库中。
   • 从uploads文件夹中删除已处理的文件。
4. 搜索文档：文档处理完成后，使用语义搜索栏在所有索引块中查找相关内容。
5. 使用API：通过/api/*端点以编程方式与服务器进行交互。

高级用法

在使用API进行搜索时，可以通过调整参数来实现更高级的搜索功能，例如：

# 示例：进行语义搜索，返回前10个结果，并启用结果重排和查询扩展
curl -X POST "http://localhost:8000/api/search" -H "Content-Type: application/json" -d '{"query": "your_search_query", "top_k": 10, "search_type": "semantic", "use_reranker": true, "expand_query": true}'

支持的文件类型

服务器支持多种文件类型：

文本文档

• .txt - 纯文本文件
• .md - Markdown文件
• .pdf - PDF文档

编程语言

• .py - Python
• .js、.ts、.jsx、.tsx - JavaScript/TypeScript
• .java - Java
• .c、.cpp、.cc、.cxx - C/C++
• .cs - C#
• .go - Go
• .rs - Rust
• .php - PHP
• .rb - Ruby
• .scala - Scala
• .swift - Swift

Web技术

• .html、.htm - HTML
• .css、.scss、.sass - CSS及其预处理器

shell脚本

• .sh、.bash、.zsh、.fish - shell脚本

数据格式

• .json - JSON
• .yaml、.yml - YAML
• .xml - XML
• .sql - SQL
• .ini、.toml - 配置文件

注意：处理过程中，具有不受支持扩展名的文件将自动跳过。

📚 详细文档

API端点

Web界面

• GET / - 主Web界面
• POST /upload-files/ - 上传单个文件
• POST /upload-directory/ - 上传带有扩展名过滤的目录
• POST /process-files/ - 处理上传的文件
• POST /search/ - 搜索界面
• POST /delete-file/ - 删除上传的文件

JSON API

• POST /api/search - 程序化搜索端点
• GET /api/stats - 获取集合统计信息
• GET /health - 健康检查端点

搜索API参数

• query（必需）：搜索查询字符串
• top_k（可选，默认值：5）：返回的结果数量（1 - 50）
• search_type（可选，默认值："hybrid"）："hybrid"、"semantic"或"keyword"
• use_reranker（可选，默认值：true）：启用/禁用结果重排
• expand_query（可选，默认值：false）：启用/禁用查询扩展

MCP集成

项目中包含一个单独的MCP（机器理解平台）集成服务，位于mcp-rag-service/目录中。此服务提供以下功能：

• RAG客户端：用于与RAG服务器进行交互的Python客户端
• 向量分析：包括聚类、异常检测和相似性矩阵等高级分析功能
• MCP服务器：与兼容MCP的工具进行集成

MCP示例

mcp-rag-service/examples/目录中包含实际示例：

• upload_example.py - 演示文件上传功能
• search_example.py - 展示带有相似性阈值的语义搜索
• analysis_example.py - 全面的向量分析示例

要运行这些示例，请执行以下操作：

cd mcp-rag-service/examples
python upload_example.py
python search_example.py
python analysis_example.py

项目结构

.
├── app/
│   ├── main.py           # FastAPI应用程序、路由和API端点
│   └── services.py       # 业务逻辑（文件处理、分块、嵌入、数据库）
├── mcp-rag-service/      # MCP集成服务
│   ├── src/
│   │   ├── rag_client.py         # RAG服务器客户端
│   │   ├── rag_mcp_server.py     # MCP服务器实现
│   │   ├── vector_operations.py  # 高级向量分析
│   │   └── utils.py              # 实用函数
│   ├── examples/                 # 实际示例
│   └── pyproject.toml
├── templates/
│   └── index.html        # 用于UI的Jinja2模板
├── uploads/              # 文件上传目录（作为卷挂载）
├── data/                 # DuckDB数据库目录（作为卷挂载）
├── .dockerignore         # 指定Docker构建上下文中要忽略的文件
├── .gitignore            # 指定Git要忽略的文件
├── Dockerfile            # 使用uv和多阶段构建的Docker构建说明
├── requirements-base.txt # 基础Python依赖项
├── requirements-cpu.txt  # 仅CPU的ML依赖项
├── requirements-ml.txt   # 完整的ML依赖项（用于GPU）
└── README.md             # 本文件

配置

• 嵌入模型：主要和备用模型在app/services.py中作为常量定义。
• 分块：可以通过CHUNK_SIZE和CHUNK_OVERLAP环境变量调整分块大小和重叠。默认值分别为700和100。
• 数据库路径：DuckDB文件的路径在app/services.py中配置。
• 搜索功能：UI允许进行高级搜索配置：
  • 搜索类型：可以选择Hybrid（语义 + 关键字）、仅Semantic或仅Keyword（BM25）搜索。
  • 重排：可以使用交叉编码器模型对搜索结果进行重排，以提高准确性。可以在UI中切换此功能。
  • 查询扩展：自动使用从初始搜索中找到的相关术语扩展查询。可以在UI中切换此功能。
• 处理功能：
  • TF-IDF关键字：处理文件时，可以选择使用TF-IDF为每个块的元数据生成并附加相关关键字。这可以提高基于关键字的搜索效果。

错误处理

• 不支持的文件：上传和处理过程中，具有不受支持扩展名的文件将自动跳过。
• 空文件：空文件或无法读取的文件将自动从上传目录中删除。
• 处理错误：单个文件处理错误将被记录，但不会停止整个处理过程。
• API错误：所有API端点都会返回带有适当HTTP状态码的结构化错误响应。

已知限制

• 文件大小：非常大的文件在处理过程中可能会导致内存问题。
• 并发用户：当前实现仅适用于单用户场景。
• 文件格式：仅支持基于文本的文件。不支持二进制文件（如图像、视频等）。
• 语言支持：虽然嵌入模型是多语言的，但分块策略针对英语和常见编程语言进行了优化。

路线图和未来计划

计划功能

• GraphRAG集成：高级基于图的检索和推理功能
• 多用户支持：用户认证和隔离的文档集合
• 实时处理：支持WebSocket以实现实时处理更新
• 高级分析：更复杂的向量分析和可视化工具
• 插件系统：可扩展的架构，用于自定义处理器和分析器
• 性能优化：缓存、索引改进和分布式处理

GraphRAG实现

GraphRAG（基于图的检索增强生成）计划作为一项重大改进，将提供以下功能：

• 知识图构建：自动提取实体和关系
• 基于图的检索：使用图遍历和推理进行增强搜索
• 多跳推理：需要多个推理步骤的复杂查询
• 上下文理解：更好地理解文档之间的关系和层次结构

此功能目前处于规划阶段，将作为一个单独的模块实现，可选择启用。

故障排除

常见问题

1. Docker构建失败：尝试进行仅CPU构建，以获得更快、更可靠的构建结果：

docker build --build-arg USE_CPU_ONLY=true -t rag-duckdb-server-cpu .

2. 内存问题：对于大型文档集合，可以考虑以下方法：

   • 使用仅CPU构建（内存占用更小）
   • 分批处理文件
   • 增加Docker内存限制

3. 模型加载问题：如果主模型加载失败，系统将自动切换到较小的模型。

4. 数据库问题：DuckDB数据库在首次运行时会自动创建。如果遇到数据库错误，可以删除data/目录以重新开始。

健康检查

使用健康检查端点监控服务状态：

curl http://localhost:8000/health

此命令将返回服务状态、模型加载状态和数据库连接信息。

📄 许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。

⚠️ 重要提示

非常大的文件在处理过程中可能会导致内存问题，且当前实现仅适用于单用户场景。不支持二进制文件（如图像、视频等），虽然嵌入模型是多语言的，但分块策略针对英语和常见编程语言进行了优化。

💡 使用建议

在处理大型文档集合时，建议使用仅CPU构建以减少内存占用，并分批处理文件。在使用API进行搜索时，可以根据实际需求调整搜索参数，以获得更准确的结果。