Rag Duckdb With MCP

带DuckDB的Python RAG服务器

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

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

特性

• web界面：用于上传文件、启动处理和执行搜索的极简主义UI。
• 应用程序接口：提供 /api/search, /api/stats，以及 /health 用于程序集成的端点。
• 广泛的文件支持：处理各种文件类型，包括 .txt, .md, .pdf，以及多种编程语言源文件(.py, .js, .java等等）。
• 高级分块：根据文件类型使用不同的策略（例如。， CodeSplitter 对于源代码， RecursiveCharacterTextSplitter 文本）。
• 高质量嵌入：用途 sentence-transformers/paraphrase-multilingual-mpnet-base-v2 （初级，768d）或 sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 （回退，384d）。
• 向量数据库：利用DuckDB和VSS（矢量相似性搜索）扩展实现嵌入的高效存储和查询。
• 码头化和优化:

- 易于使用Docker构建和运行。 - 用途 uv 用于超快速依赖安装。 - 用于小最终图像大小的多级Dockerfile。 - 支持无GPU环境下的仅CPU构建。

• MCP集成：包括一个样本 mcp-rag-service 展示与外部系统的集成。
• 目录上传：支持通过文件扩展名过滤上传整个目录。
• 健康监测：用于监控和负载平衡器的内置健康检查端点。

技术栈

• 后端：Python与FastAPI
• 嵌入: sentence-transformers, llama-index, langchain
• 数据库：DuckDB+VSS扩展
• 容器化：Docker
• 包管理: uv

如何跑步

先决条件

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

构建并运行Docker容器

1. 克隆存储库：

   git clone 
   cd 

1. 构建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 .

1. 运行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用户注意事项*：使用 ${pwd} 而不是 $(pwd) 在PowerShell中。

1. 访问应用程序：

打开您的网络浏览器并导航到 http://localhost:8000.

使用工作流程

1. 上传文件：使用web界面选择并上传一个或多个支持的文件。
2. 上传目录：或者，上传带有文件扩展名过滤的整个目录，仅处理特定的文件类型。
3. 流程文件：单击“开始处理”按钮。服务器将：

- 提取文本内容。 - 将文本拆分为易于管理、上下文感知的块。 - 为每个块生成向量嵌入。 - 将块及其嵌入保存到 data/rag.duckdb 数据库。 - 从中删除已处理的文件 uploads 文件夹。

1. 搜索文档：处理完文档后，使用语义搜索栏在所有索引块中查找相关内容。
2. 使用API：通过编程方式与服务器交互 /api/* 端点。

支持的文件类型

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

文本文档

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

程式语言

• .py python
• .js, .ts, .jsx, .tsx -JavaScript/TypeScript
• .java Java
• .c, .cpp, .cc, .cxx -C/C++
• .cs C
• .go -去吧
• .rs -生锈
• .php -PHP
• .rb -红宝石
• .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 / -主网页界面
• POST /upload-files/ -上传单个文件
• POST /upload-directory/ -上传带有扩展名过滤的目录
• POST /process-files/ -处理上传的文件
• POST /search/ -搜索界面
• POST /delete-file/ -删除上传的文件

应用程序接口

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

搜索API参数

• query （必填）：搜索查询字符串
• top_k （可选，默认值：5）：要返回的结果数（1-50）
• search_type （可选，默认：“hybrid”）：“混合”、“语义”或“关键字”
• use_reranker （可选，默认值：true）：启用/禁用结果重新排序
• expand_query （可选，默认值：false）：启用/禁用查询扩展

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 application, routes, and API endpoints
│   └── services.py       # Business logic (file processing, chunking, embeddings, DB)
├── mcp-rag-service/      # MCP integration service
│   ├── src/
│   │   ├── rag_client.py         # RAG server client
│   │   ├── rag_mcp_server.py     # MCP server implementation
│   │   ├── vector_operations.py  # Advanced vector analytics
│   │   └── utils.py              # Utility functions
│   ├── examples/                 # Working examples
│   └── pyproject.toml
├── templates/
│   └── index.html        # Jinja2 template for the UI
├── uploads/              # Directory for file uploads (mounted as a volume)
├── data/                 # Directory for DuckDB database (mounted as a volume)
├── .dockerignore         # Specifies files to ignore in Docker build context
├── .gitignore            # Specifies files to ignore for Git
├── Dockerfile            # Docker build instructions with uv and multi-stage builds
├── requirements-base.txt # Base Python dependencies
├── requirements-cpu.txt  # CPU-only ML dependencies
├── requirements-ml.txt   # Full ML dependencies (for GPU)
└── README.md             # This file

配置

• 嵌入模型：主模型和回退模型在中定义为常量 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 .

1. 内存问题：对于大型文档集合，请考虑：

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

1. 模型加载问题：如果主模型无法加载，系统会自动回退到较小的模型。

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

健康检查

使用健康检查终结点监视服务状态：

curl http://localhost:8000/health

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

贡献

欢迎投稿！请随时提交pull请求或打开bug和功能请求的问题。

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。