Rag Duckdb With MCP

🚀 Python RAG Server with DuckDB

このプロジェクトは、ドキュメントの処理と検索拡張生成（RAG）を目的としたPythonベースのサーバーです。簡単なウェブインターフェイスとJSON APIを提供し、ドキュメントをアップロード、チャンクに分割、埋め込みベクトルを生成し、DuckDBデータベースに保存して、効率的な類似性検索を行うことができます。

アプリケーション全体はDockerでコンテナ化されており、高速で最適化された依存関係管理にuvを使用しています。また、MCP（Machine Comprehension Platform）との統合にmcp-rag-serviceも含まれています。

✨ 主な機能

• ウェブインターフェイス：ファイルのアップロード、処理の開始、検索を行うためのシンプルな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次元）を使用。
• ベクトルデータベース：DuckDBとVSS（Vector Similarity Search）拡張機能を利用して、埋め込みベクトルの効率的な保存とクエリを行います。
• Docker化と最適化：
  • Dockerで簡単にビルドと実行が可能。
  • uvを使用して超高速な依存関係のインストール。
  • マルチステージのDockerfileにより、最終的なイメージサイズが小さくなります。
  • GPUがない環境でもCPUのみのビルドがサポートされています。
• 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サーバーでの使用を推奨）： このビルドは、PyTorchのCPU専用バージョンを使用することで、より高速で小さなイメージを生成します。

   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. アプリケーションにアクセスする： ウェブブラウザを開き、http://localhost:8000にアクセスします。

💻 使用例

利用ワークフロー

1. ファイルのアップロード：ウェブインターフェイスを使用して、サポートされている1つ以上のファイルを選択してアップロードします。
2. ディレクトリのアップロード：代わりに、ファイル拡張子のフィルタリングを伴うディレクトリ全体をアップロードして、特定のファイルタイプのみを処理することができます。
3. ファイルの処理：「処理を開始」ボタンをクリックします。サーバーは以下の操作を行います。
   • テキストコンテンツを抽出します。
   • テキストを管理可能なコンテキスト認識チャンクに分割します。
   • 各チャンクのベクトル埋め込みを生成します。
   • チャンクとその埋め込みをdata/rag.duckdbデータベースに保存します。
   • 処理されたファイルをuploadsフォルダから削除します。
4. ドキュメントの検索：ドキュメントが処理されたら、セマンティック検索バーを使用して、すべてのインデックス付きチャンクから関連するコンテンツを検索します。
5. 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

ウェブテクノロジー

• .html、.htm - HTML
• .css、.scss、.sass - CSSおよびプリプロセッサ

シェルスクリプト

• .sh、.bash、.zsh、.fish - シェルスクリプト

データ形式

• .json - JSON
• .yaml、.yml - YAML
• .xml - XML
• .sql - SQL
• .ini、.toml - 設定ファイル

注意：サポートされていない拡張子のファイルは、処理時に自動的にスキップされます。

APIエンドポイント

ウェブインターフェイス

• GET / - メインのウェブインターフェイス
• 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-rag-service/ディレクトリにある別のMCP（Machine Comprehension Platform）統合サービスが含まれています。このサービスは以下を提供します。

• 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       # ビジネスロジック（ファイル処理、チャンキング、埋め込みベクトル、DB）
├── 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）検索を選択できます。
  • 再ランキング：Cross-Encoderモデルを使用して、上位の検索結果を再ランキングして、より高い精度を得ることができます。これはUIで切り替えることができます。
  • クエリ拡張：初期検索から見つかった関連用語でクエリを自動的に拡張します。これはUIで切り替えることができます。
• 処理機能：
  • TF-IDFキーワード：ファイルを処理する際に、TF-IDFを使用して各チャンクのメタデータに関連するキーワードを生成して添付することができます。これにより、キーワードベースの検索が向上します。

エラーハンドリング

• サポートされていないファイル：サポートされていない拡張子のファイルは、アップロードと処理時に自動的にスキップされます。
• 空のファイル：空または読み取り不可能なファイルは、アップロードディレクトリから自動的に削除されます。
• 処理エラー：個々のファイルの処理エラーはログに記録されますが、全体のプロセスを停止させることはありません。
• APIエラー：すべてのAPIエンドポイントは、適切なHTTPステータスコードを含む構造化されたエラー応答を返します。

既知の制限事項

• ファイルサイズ：非常に大きなファイルは、処理時にメモリの問題を引き起こす可能性があります。
• 同時ユーザー：現在の実装は、単一ユーザーのシナリオを対象としています。
• ファイル形式：テキストベースのファイルのみがサポートされています。バイナリファイル（画像、動画など）はサポートされていません。
• 言語サポート：埋め込みモデルは多言語対応ですが、チャンキング戦略は英語と一般的なプログラミング言語に最適化されています。

ロードマップと将来の計画

予定されている機能

• GraphRAG統合：高度なグラフベースの検索と推論機能
• マルチユーザーサポート：ユーザー認証と分離されたドキュメントコレクション
• リアルタイム処理：リアルタイム処理の更新のためのWebSocketサポート
• 高度な分析：より洗練されたベクトル分析と視覚化ツール
• プラグインシステム：カスタムプロセッサーとアナライザーのための拡張可能なアーキテクチャ
• パフォーマンス最適化：キャッシュ、インデックスの改善、分散処理

GraphRAGの実装

GraphRAG（Graph-based Retrieval-Augmented Generation）は、主要な機能強化として計画されており、以下を提供します。

• 知識グラフの構築：エンティティと関係の自動抽出
• グラフベースの検索：グラフトラバーサルと推論を使用した強化された検索
• マルチホップ推論：複数の推論ステップを必要とする複雑なクエリ
• コンテキスト理解：ドキュメントの関係と階層のより良い理解

この機能は現在計画段階であり、オプションで有効にできる別のモジュールとして実装されます。

トラブルシューティング

一般的な問題

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ファイルを参照してください。