检索鸭库与MCP

Name: 检索鸭库与MCP
Author: niksh06

作者：niksh066 星标更新：2025-07-17

安装使用来源：spider==github.com

项目介绍

基于Python的RAG服务器与DuckDB

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

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

特性

Web界面：最小主义UI，用于上传文件、启动处理和执行搜索。
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化及优化：
- 使用Docker轻松构建和运行。
- 使用uv进行超快依赖安装。
- 多阶段Dockerfile以获得较小的最终镜像大小。
- 支持仅CPU构建，适用于没有GPU的环境。
MCP集成：包括一个示例mcp-rag-service以演示与外部系统的集成。
目录上传：支持上传整个目录并过滤文件扩展名。
健康监控：内置健康检查端点用于监控和负载均衡器。

技术栈

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

如何运行

先决条件

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

构建并运行Docker容器

克隆仓库：

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

构建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 .
```
运行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)。
访问应用： 打开您的网络浏览器并导航至http://localhost:8000。

使用工作流程

上传文件：使用Web界面选择并上传一个或多个支持的文件。
上传目录：或者上传整个目录并过滤文件扩展名以仅处理特定类型的文件。
处理文件：点击“开始处理”按钮。服务器将：
- 提取文本内容。
- 将文本分割成可管理的、上下文感知的块。
- 为每个块生成一个向量嵌入。
- 将块及其嵌入保存到data/rag.duckdb数据库中。
- 删除已处理的文件。
搜索文档：一旦文档被处理，可以使用语义搜索栏在整个索引块中查找相关内容。
使用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 - 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（基于图的检索增强生成）计划作为一个重大增强，将提供：

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

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

故障排除

常见问题

Docker构建失败：尝试仅CPU构建以获得更快、更可靠的构建：
```
docker build --build-arg USE_CPU_ONLY=true -t rag-duckdb-server-cpu .
```
内存问题：对于大型文档集合，请考虑：
- 使用仅CPU构建（较小的内存占用）
- 分批处理文件
- 增加Docker内存限制
模型加载问题：如果主模型加载失败，系统会自动回退到较小的模型。
数据库问题：DuckDB数据库会在首次运行时自动创建。如果遇到数据库错误，可以删除data/目录以重新开始。

健康检查

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

curl http://localhost:8000/health

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

贡献

欢迎贡献！请随时提交拉取请求或打开问题报告错误和功能请求。

许可证

本项目采用MIT许可证 - 详情参见LICENSE文件。 </中文翻译>