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，使最終鏡像體積更小。
  • 支持僅使用CPU的構建，適用於沒有GPU的環境。
• MCP集成：包含一個示例mcp - rag - service，用於演示與外部系統的集成。
• 目錄上傳：支持上傳整個目錄，並可進行文件擴展名過濾。
• 健康監控：內置健康檢查端點，便於監控和負載均衡。

📦 安裝指南

前提條件

• 你的機器上已安裝並運行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使用示例

以下是使用Python請求庫調用搜索API的示例：

import requests

url = 'http://localhost:8000/api/search'
params = {
    'query': '示例查詢',
    'top_k': 10,
    'search_type': 'semantic',
    'use_reranker': True,
    'expand_query': False
}

response = requests.post(url, params=params)
print(response.json())

📚 詳細文檔

支持的文件類型

服務器支持廣泛的文件類型：

文本文檔

• .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的機器學習依賴項
├── requirements-ml.txt   # 完整的機器學習依賴項（用於GPU）
└── README.md             # 本文件

配置

• 嵌入模型：主要和備用模型在app/services.py中作為常量定義。
• 分塊：可以通過CHUNK_SIZE和CHUNK_OVERLAP環境變量調整分塊大小和重疊。默認值分別為700和100。
• 數據庫路徑：DuckDB文件的路徑在app/services.py中配置。
• 搜索功能：
  • 搜索類型：可以在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文件。