Visual RAPTOR ColVBERT Integration System

震災教訓継承のためのビジュアル文書検索システム - ColModernVBERT (SigLIP) 対応版

📋 目次

概要
主要機能
実行結果サマリー
エンコーダー性能比較
システム構成
技術スタック
インストール
クイックスタート
詳細な使用方法
トラブルシューティング
パフォーマンス最適化

概要

このシステムは、東日本大震災の教訓を次世代に継承するため、ビジュアル文書（避難所マップ、復旧計画、行政通知など）に対応した高度な検索・要約システムです。

🎯 主要機能

RAPTOR: 階層的文書検索・要約（3階層、Silhouetteベース最適クラスタリング）
ColModernVBERT: SigLIP基盤のマルチモーダル（テキスト+画像）検索エンコーダー
ColVBERT: BLIP基盤の従来型マルチモーダル検索エンコーダー
Enhanced OCR: 複数OCRエンジンによる高精度テキスト抽出
JinaVDR対応: Visual Document Retrievalベンチマーク
GPU加速: CUDA対応で高速処理
日本語対応: 災害関連文書の日本語処理

🚀 実行結果サマリー

✅ 検証済み実行結果（2025年10月23日）

1. Visual RAPTOR ColBERT 基本実行

python run_visual_raptor.py

実行結果:

✅ システム初期化: ColModernVBERT (SigLIP) + CUDA
✅ ドキュメント生成: 20個の災害関連Visual Document
✅ エンコード成功率: 100% (20/20)
✅ エンコーディング速度: 0.068秒/doc (非常に高速)
✅ 検索クエリ: 5個の災害関連クエリで検索成功
✅ 総処理時間: 1.35秒

検索精度例:

「津波警報の発令状況」 → TSUNAMI - Sendai (類似度: 0.0461)
「避難所の場所を教えてください」 → TSUNAMI - Sendai (類似度: 0.0698)
「災害発生時の緊急連絡先」 → TSUNAMI - Sendai (類似度: 0.0614)

2. ColModernVBERT vs ColVBERT 比較実験

python compare_encoders.py

実験条件:

📊 100枚のVisual Document生成
🔍 20個の検索クエリ
🖼️ 各ドキュメントに画像+テキスト埋め込み

比較結果:

項目	ColVBERT (BLIP)	ColModernVBERT (SigLIP)	改善率
エンコーディング時間	7.18秒	3.18秒	2.26倍高速 🚀
平均検索時間	0.13ms	0.14ms	ほぼ同等
メモリ使用量	0.29 MB	0.29 MB	同等
クロスモーダル類似度	-0.024 ⚠️	0.168 ✅	正常動作
テキスト自己類似度	0.869	0.724	より多様

重要な発見:

✅ ColModernVBERTが優位: 2.26倍高速なエンコーディング
✅ 正しいクロスモーダル対応: テキストと画像が適切に対応（0.168）
⚠️ ColVBERTの問題: クロスモーダル類似度が負の値（-0.024）

注意: SigLIPはsigmoid損失で学習されており、類似度の絶対値は低めですが、相対的なランキング精度が重要です。

3. 埋め込み特性分析

python analyze_embeddings.py

ColModernVBERT (SigLIP) の特性:

✅ L2正規化済み: ノルム = 1.000
✅ クロスモーダル類似度: 0.168（正の値で適切）
✅ テキスト埋め込み多様性: 自己類似度 0.724
✅ 画像埋め込み識別性: 自己類似度 0.906

4. 実際のPDF文書処理（131ページ）

python run_visual_raptor_on_pdfs.py

処理対象:

📄 PDF 1: 201205_EastJapanQuakeLesson.pdf (44ページ)
📄 PDF 2: 202505_Reiwa6DisasterExamples.pdf (87ページ)
🖼️ 総画像数: 262枚（重複含む）

実行結果:

項目	結果
PDF読み込み	✅ 131枚の画像
PyMuPDF テキスト抽出	✅ 131ページ（44 + 87ページ）
Visual Documents処理	✅ 262ドキュメント
インデックス構築時間	14.41秒
総処理時間	27.49秒
平均処理速度	0.105秒/ページ ⚡
埋め込み次元	768

テキスト抽出実績:

✅ PyMuPDFによる直接抽出: Tesseract不要
✅ テキスト長: 0～1,623文字/ページ
✅ 抽出成功率: 100%

検索クエリ例（8クエリ）:

クエリ	Top1スコア	Top1ページ	テキスト長
東日本大震災の教訓	0.0550	東日本大震災の教訓集 p.022	619文字
避難所の運営方法	0.0597	令和6年度災害事例集 p.013	1,623文字
災害対応の課題と改善点	0.0553	令和6年度災害事例集 p.039	638文字
復旧復興の取り組み	0.0802	東日本大震災の教訓集 p.009	783文字
防災対策の重要性	0.0591	東日本大震災の教訓集 p.001	0文字
津波の被害状況	0.0855	令和6年度災害事例集 p.013	1,623文字
地震発生時の対応	0.0756	令和6年度災害事例集 p.007	298文字
被災者支援の実践例	0.0455	東日本大震災の教訓集 p.043	1,328文字

平均検索時間: 10～20ms

📊 SigLIP評価指標

実際のPDF検索に対する6つの評価指標を測定しました。

評価指標の説明

分散 (Variance): 検索結果の多様性
- 範囲: 0.000004 ～ 0.000097
- 意味: 低いほど結果が均質、高いほど多様
正規化エントロピー (Normalized Entropy): 結果の不確実性
- 範囲: 1.0000（全クエリ）
- 意味: 0に近いほど確信的、1に近いほど不確実
- 結果: 全て1.0 = 結果が均等に分散
信頼度 (Confidence): Top1とTop2の差
- 範囲: 0.0002 ～ 0.0120
- 意味: 高いほど明確なトップ結果が存在
- 最高: クエリ2「避難所の運営方法」(0.0120)
相対優位性 (Relative Dominance): Top1が平均を超える度合い
- 範囲: 1.1465 ～ 1.9734
- 意味: 標準偏差で正規化したz-score
- 最高: クエリ4「復旧復興の取り組み」(1.9734)
ランキング品質 (Ranking Quality): DCG風スコア
- 範囲: -0.0106 ～ 0.2302
- 意味: 高いほど良好なランキング
- 最高: クエリ4「復旧復興の取り組み」(0.2302)
スコア減衰率 (Score Decay Rate): ランキングの滑らかさ
- 範囲: 0.001147 ～ 0.006398
- 意味: 低いほど滑らかな減衰
- 最低: クエリ8「被災者支援の実践例」(0.001147)

全体集計指標（8クエリ平均）

📊 平均信頼度: 0.0038 ± 0.0031
📊 平均エントロピー: 1.0000 ± 0.0000
📊 平均ランキング品質: 0.1743
📊 平均スコア減衰率: 0.003066

📈 評価指標グラフ

グラフ化された評価結果は results/siglip_metrics_*.png に保存されます。

グラフ内容:

6つの評価指標を3行×2列レイアウトで表示
各クエリ（Q1～Q8）の指標値を棒グラフで比較
高解像度PNG（300 DPI）
日本語表示対応

生成ファイル:

results/siglip_metrics_YYYYMMDD_HHMMSS.png - 評価指標グラフ
results/query_legend_YYYYMMDD_HHMMSS.txt - クエリ凡例
results/visual_raptor_results_YYYYMMDD_HHMMSS.json - 完全な検索結果データ

ColVBERT (BLIP) の問題:

⚠️ クロスモーダル類似度: -0.024（負の値）
⚠️ 画像埋め込みがほぼ同一: 自己類似度 1.000

� エンコーダー性能比較

ColModernVBERT (SigLIP) vs ColVBERT (BLIP) 包括的ベンチマーク

実際のPDFデータ（131ページ）を使用した詳細な性能比較を実施しました。

実行コマンド:

python compare_encoders_realdata.py

⚡ エンコーディング性能

指標	ColVBERT (BLIP)	ColModernVBERT (SigLIP)	改善率
総処理時間	14.05秒	10.79秒	1.30倍高速 ⚡
平均/ドキュメント	96.13ms	72.36ms	1.33倍高速 ⚡
平均/クエリ	20.75ms	7.73ms	2.68倍高速 ⚡

💾 GPU使用量

指標	ColVBERT (BLIP)	ColModernVBERT (SigLIP)
ピークメモリ	3,297 MB	4,141 MB (+25.6%)
平均利用率	31.1%	27.6%

注記: SigLIPはより大きいモデル（google/siglip-base-patch16-224）のため、GPUメモリ使用量は増加しますが、処理効率は向上しています。

📊 ランキング指標（情報検索の質）

MRR (Mean Reciprocal Rank) - 正解が上位何番目に出現するか

ColVBERT (BLIP): 0.1542
ColModernVBERT (SigLIP): 0.2625 ✅ +70.3%改善

MAP (Mean Average Precision) - 平均適合率

ColVBERT (BLIP): 0.0928
ColModernVBERT (SigLIP): 0.0884

NDCG@k (Normalized Discounted Cumulative Gain)

k値	ColVBERT	ColModernVBERT	改善率
@5	0.0744	0.1038	✅ +39.6%
@10	0.0754	0.0856	✅ +13.7%
@20	0.1021	0.1061	✅ +3.9%

Precision@k & Recall@k

指標	@5	@10	@20
Precision (BLIP)	0.0800	0.0600	0.0500
Precision (SigLIP)	0.1000 ✅	0.0500	0.0400
Recall (BLIP)	0.0518	0.0804	0.1357
Recall (SigLIP)	0.0744 ✅	0.0744	0.1220

📈 可視化グラフ

比較結果は9つのグラフ（3×3レイアウト）で可視化されます:

ドキュメントエンコーディング時間 - SigLIPが1.33倍高速
GPU ピークメモリ使用量 - SigLIPが844MB多い
GPU 平均利用率 - 両者とも27-31%で効率的
検索レイテンシー (平均/P95/P99) - 両者とも<1ms
MRR & MAP - MRRでSigLIPが70%改善
NDCG@k (k=5,10,20) - 全てのk値でSigLIPが優位
Precision@k - @5でSigLIPが25%改善
Recall@k - @5でSigLIPが44%改善
総エンコーディング時間 - SigLIPが30%高速

出力ファイル:

data/encoder_comparison_realdata/results/comprehensive_comparison.png - 包括的比較グラフ（300 DPI）
data/encoder_comparison_realdata/results/comparison_results.json - 詳細な数値データ

✨ 主要な発見

処理速度: ColModernVBERT (SigLIP) は全ての処理で高速化を実現
- ドキュメント: 1.33倍
- クエリ: 2.68倍
- 総合: 1.30倍
ランキング品質: 情報検索の質が大幅に向上
- MRR: 70.3%改善（正解の順位が上昇）
- NDCG@5: 39.6%改善（上位5件の品質向上）
- Precision@5: 25%改善（上位5件の適合率向上）
GPU効率: メモリは増加するが利用率は低下
- メモリ: +844MB (25.6%増)
- 利用率: 31.1% → 27.6% (より効率的)
実用性: 131ページのPDFを約11秒で処理可能

🎯 推奨事項

ColModernVBERT (SigLIP) を推奨する場合:

✅ 処理速度を優先
✅ 検索品質（ランキング精度）を重視
✅ GPUメモリに余裕がある（4GB以上のVRAM増加可能）
✅ 最新のマルチモーダルモデルを使用したい

ColVBERT (BLIP) を使用する場合:

⚠️ GPUメモリが限られている（3GB以下のVRAM余裕）
⚠️ 従来のBLIPモデルとの互換性が必要

結論: ColModernVBERT (SigLIP) は、わずかなメモリ増加と引き換えに、処理速度と検索品質の両面で大幅な改善を実現しています。

�📂 システム構成

📂 システム構成

visual-raptor-colvbert/
├── visual_raptor_colbert.py          # メインのVisual RAPTOR + ColBERT実装
│   ├── ColModernVBERTEncoder         # SigLIP基盤エンコーダー（推奨）
│   ├── ColVBERTEncoder               # BLIP基盤エンコーダー
│   ├── VisualDocumentProcessor       # PDF処理（PyMuPDF統合）
│   └── VisualRAPTORColBERT           # 統合システムクラス
├── run_visual_raptor.py              # 🚀 基本デモ実行スクリプト
├── run_visual_raptor_on_pdfs.py      # 📄 実PDF処理スクリプト（推奨）
├── process_pdf_documents.py          # PDF→画像変換ツール
├── compare_encoders.py               # エンコーダー比較ベンチマーク
├── analyze_embeddings.py             # 埋め込み特性分析ツール
├── jina_vdr_benchmark.py             # JinaVDRベンチマーク環境
│   ├── DisasterDocumentGenerator     # 災害文書生成
│   └── JinaVDRBenchmark              # ベンチマーク管理
├── integrated_system.py              # 統合システム（旧版）
├── requirements.txt                  # 依存関係
├── data/                             # データディレクトリ
│   ├── disaster_visual_documents/    # 元PDFファイル
│   ├── processed_pdfs/               # 処理済み画像
│   │   └── images/                   # PNG形式のページ画像
│   ├── visual_raptor_run/            # 基本実行結果
│   ├── encoder_comparison/           # 比較結果
│   └── embedding_analysis/           # 分析結果
└── results/                          # 検索結果・評価指標
    ├── visual_raptor_results_*.json  # 検索結果データ
    ├── siglip_metrics_*.png          # 評価指標グラフ
    └── query_legend_*.txt            # クエリ凡例

🛠️ 技術スタック

基盤技術

RAPTOR: 階層的検索とクラスタリング（Silhouette評価）
ColModernVBERT: SigLIP基盤マルチモーダルエンコーダー
ColVBERT: BLIP基盤マルチモーダルエンコーダー
FAISS: 高速ベクトル検索
LangChain: LLM統合フレームワーク

AI/MLモデル

推奨: ColModernVBERT (SigLIP)

統合モデル: google/siglip-base-patch16-224
特徴:
- Sigmoid損失による対照学習
- クロスアテンション機構（8ヘッド）
- 768次元埋め込み
- 2.26倍高速なエンコーディング
- 正しいクロスモーダル対応

従来型: ColVBERT (BLIP)

テキストエンコーダ: intfloat/multilingual-e5-large (1024次元 → 768次元投影)
ビジョンエンコーダ: Salesforce/blip-image-captioning-base
注意: クロスモーダル類似度に問題あり

その他

レイアウト解析: microsoft/layoutlmv3-base
LLM: Ollama granite-code:8b
埋め込み: Ollama mxbai-embed-large

PDF処理・OCR技術

PyMuPDF (fitz): PDF直接テキスト抽出（推奨、Tesseract不要）
- ネイティブPDFテキスト抽出
- PDF→画像変換（150 DPI PNG）
- 高速・高精度
Tesseract: 高精度日本語OCR（オプション、画像のみPDF用）
EasyOCR: 深層学習ベースOCR
PaddleOCR: 中国製高性能OCR

📥 インストール

1. 前提条件

Python: 3.8以上
GPU: NVIDIA GPU + CUDA 11.8以上（推奨）
メモリ: 16GB以上推奨
ストレージ: 10GB以上の空き容量

# Python バージョン確認
python --version  # 3.8+ 必須

# CUDA 確認（GPU使用時）
nvidia-smi

# Gitクローン
git clone https://github.com/langchain-ai/learning-langchain.git
cd learning-langchain/visual-raptor-colvbert

2. Python環境セットアップ

# 仮想環境作成（推奨）
python -m venv venv

# 仮想環境有効化
# Windows (PowerShell):
.\venv\Scripts\Activate.ps1
# Windows (CMD):
venv\Scripts\activate.bat
# Linux/Mac:
source venv/bin/activate

# 依存関係インストール
pip install -r requirements.txt

3. Ollama セットアップ

# Ollamaインストール
# Windows: https://ollama.ai/download
# Linux/Mac:
curl -fsSL https://ollama.ai/install.sh | sh

# モデルダウンロード（必須）
ollama pull mxbai-embed-large      # 埋め込みモデル（1024次元）
ollama pull granite-code:8b        # LLMモデル（8Bパラメータ）

# Ollama起動確認
ollama list

4. GPU設定（オプション）

# CUDA環境変数設定（必要に応じて）
# Windows (PowerShell):
$env:CUDA_VISIBLE_DEVICES="0"

# Linux/Mac:
export CUDA_VISIBLE_DEVICES=0

# PyTorch CUDA確認
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"

🎯 クイックスタート

最速実行（推奨）

# Visual RAPTOR ColBERT を実行
python run_visual_raptor.py

実行内容:

ColModernVBERT (SigLIP) 初期化
20個の災害関連Visual Document生成
マルチモーダルエンコーディング
5個の検索クエリで検索実行
Top-3結果表示

期待される出力:

================================================================================
🚀 Visual RAPTOR ColBERT - 完全実行デモ
================================================================================

[ステップ 1/8] 出力ディレクトリ準備...
✅ data\visual_raptor_run 準備完了

[ステップ 2/8] Ollamaモデル初期化...
✅ Ollama mxbai-embed-large & granite-code:8b 初期化完了

[ステップ 3/8] ColModernVBERT (SigLIP) 初期化...
✅ ColModernVBERT initialized with SigLIP
   Device: cuda
   Embedding dim: 768
   Cross-attention: True

... (省略)

================================================================================
📊 Visual RAPTOR ColBERT 実行統計
================================================================================
エンコーダー: ColModernVBERT (SigLIP)
生成ドキュメント数: 20
エンコード成功数: 20
検索クエリ数: 5
エンコーディング時間: 1.35秒
平均エンコード時間: 0.068秒/doc

実際のPDF文書処理（推奨）

# PDFファイルを画像に変換
python process_pdf_documents.py

# Visual RAPTORで検索実行
python run_visual_raptor_on_pdfs.py

処理内容:

PDFファイル（英語ファイル名）を data/disaster_visual_documents/ に配置
process_pdf_documents.py で画像変換（150 DPI PNG）
PyMuPDFによる直接テキスト抽出（Tesseract不要）
ColModernVBERT (SigLIP) でマルチモーダル検索
8つの災害関連クエリで検索実行
SigLIP評価指標をグラフ化

出力ファイル:

results/visual_raptor_results_*.json - 完全な検索結果
results/siglip_metrics_*.png - 評価指標グラフ
results/query_legend_*.txt - クエリ凡例

処理性能（131ページ実績）:

PDF読み込み: 44 + 87ページ
テキスト抽出: 100%成功（PyMuPDF）
インデックス構築: 14.41秒
平均処理速度: 0.105秒/ページ
検索時間: 10～20ms/クエリ

エンコーダー比較実験

# ColModernVBERT vs ColVBERT 比較
python compare_encoders.py

実験内容:

100枚のVisual Document生成
両エンコーダーでエンコーディング
20個のクエリで検索性能評価
結果を data/encoder_comparison/ に保存

埋め込み特性分析

# 詳細な埋め込み分析
python analyze_embeddings.py

分析内容:

埋め込みの統計（平均、標準偏差、ノルム）
自己類似度分析
クロスモーダル類似度評価
可視化グラフ生成

📖 詳細な使用方法

1. 基本的なPython API使用例

📖 詳細な使用方法

1. 基本的なPython API使用例

from visual_raptor_colbert import VisualRAPTORColBERT, VisualDocument
from langchain_ollama import OllamaEmbeddings, ChatOllama
from PIL import Image

# Ollamaモデル初期化
embeddings = OllamaEmbeddings(model="mxbai-embed-large")
llm = ChatOllama(model="granite-code:8b", temperature=0.0)

# ColModernVBERT (SigLIP) で初期化（推奨）
config = {
    'encoder_type': 'modern',
    'embedding_dim': 768,
    'use_cross_attention': True
}

visual_raptor = VisualRAPTORColBERT(
    embeddings_model=embeddings,
    llm=llm,
    use_modern_vbert=True,  # SigLIP使用
    colbert_config=config
)

# Visual Documentエンコーディング
image = Image.open("disaster_map.png").convert('RGB')
text = "避難所マップ：仙台市青葉区の指定避難所一覧"

embedding = visual_raptor.colbert_encoder.encode_multimodal(
    [text],
    [image]
)

# 検索クエリ
query_text = "仙台市の避難所を教えてください"
query_embedding = visual_raptor.colbert_encoder.encode_text([query_text])

# 類似度計算
import torch
similarity = torch.cosine_similarity(query_embedding, embedding)
print(f"類似度: {similarity.item():.4f}")

2. 従来型ColVBERT (BLIP) を使用する場合

# ColVBERT (BLIP) で初期化
config = {
    'encoder_type': 'standard',
    'embedding_dim': 768,
    'use_cross_attention': False
}

visual_raptor = VisualRAPTORColBERT(
    embeddings_model=embeddings,
    llm=llm,
    use_modern_vbert=False,  # BLIP使用
    colbert_config=config
)

3. バッチ処理

from jina_vdr_benchmark import DisasterDocumentGenerator
from pathlib import Path

# ドキュメント生成
doc_generator = DisasterDocumentGenerator()
documents = doc_generator.create_synthetic_documents(num_documents=50)

# バッチエンコーディング
encoded_docs = []
for doc in documents:
    image = Image.open(doc['image_path']).convert('RGB')
    text = doc['content'][:500]
  
    embedding = visual_raptor.colbert_encoder.encode_multimodal(
        [text], [image]
    )
    encoded_docs.append({
        'doc': doc,
        'embedding': embedding.detach().cpu()
    })

print(f"✅ {len(encoded_docs)}個のドキュメントをエンコード完了")

4. カスタム設定

# ColModernVBERT 詳細設定
config = {
    'encoder_type': 'modern',
    'text_model': 'google/siglip-base-patch16-224',
    'vision_model': 'google/siglip-base-patch16-224',
    'embedding_dim': 768,
    'use_cross_attention': True,  # クロスアテンション有効化
    'device': 'cuda'  # GPU使用
}

visual_raptor = VisualRAPTORColBERT(
    embeddings_model=embeddings,
    llm=llm,
    use_modern_vbert=True,
    colbert_config=config
)

📊 ベンチマーク結果

ColModernVBERT vs ColVBERT 比較（検証済み）

実験条件: 100個のVisual Document、20個の検索クエリ

メトリック	ColVBERT`<br>`(BLIP)	ColModernVBERT`<br>`(SigLIP)	改善
エンコーディング時間	7.18秒	3.18秒	✅2.26倍高速
平均エンコード時間	0.072秒/doc	0.032秒/doc	✅2.25倍高速
検索時間	0.13ms	0.14ms	≈ 同等
メモリ使用量	0.29 MB	0.29 MB	≈ 同等
クロスモーダル類似度	-0.024 ⚠️	0.168 ✅	✅正常動作
テキスト自己類似度	0.869	0.724	✅より多様
画像自己類似度	1.000 ⚠️	0.906	✅識別可能

埋め込み特性分析

ColModernVBERT (SigLIP) - 推奨

✅ テキスト埋め込み:
   平均: 0.015, 標準偏差: 0.033
   L2ノルム: 1.000（正規化済み）
   自己類似度: 0.724（多様性高）

✅ 画像埋め込み:
   平均: 0.015, 標準偏差: 0.033
   L2ノルム: 1.000（正規化済み）
   自己類似度: 0.906（識別可能）

✅ クロスモーダル類似度: 0.168
   - テキストと画像が正しく対応
   - 対角要素平均: 0.170

ColVBERT (BLIP) - 問題あり

⚠️ テキスト埋め込み:
   自己類似度: 0.869（多様性低）

⚠️ 画像埋め込み:
   自己類似度: 1.000（完全に同一）
   - 画像の識別ができていない

⚠️ クロスモーダル類似度: -0.024
   - 負の値（テキストと画像が逆方向）

JinaVDR ベンチマーク対応

システムは以下の評価指標をサポート：

Precision@K: 上位K件の適合率
Recall@K: 上位K件の再現率
F1 Score: 適合率と再現率の調和平均
NDCG@K: 順位を考慮した正規化割引累積利得

災害文書カテゴリ

生成可能な文書タイプ：

地震関連 (earthquake)
- 震度分布マップ
- 被害状況報告
- 余震情報
津波関連 (tsunami)
- 津波警報・注意報
- 浸水予測図
- 避難指示
避難情報 (evacuation)
- 避難所マップ
- 避難経路図
- 収容人数情報
救援・復旧 (recovery, rescue)
- 救援物資配布情報
- 復旧計画書
- ボランティア情報
その他 (flood, typhoon, fire, landslide)
- 洪水、台風、火災、土砂災害関連

🔧 トラブルシューティング

よくある問題と解決方法

1. Ollama接続エラー

エラー:

ConnectionError: Could not connect to Ollama server

解決方法:

# Ollamaサーバー起動確認
ollama serve

# 別のターミナルでモデル確認
ollama list

# モデルが無い場合はダウンロード
ollama pull mxbai-embed-large
ollama pull granite-code:8b

2. CUDA/GPU認識エラー

エラー:

RuntimeError: CUDA out of memory

解決方法:

# バッチサイズを削減
# または CPU使用
config = {
    'device': 'cpu',  # CPUに切り替え
    'embedding_dim': 768
}

# GPUメモリクリア
import torch
torch.cuda.empty_cache()

3. 類似度スコアが低い

現象:

ColModernVBERTの類似度が0.04〜0.07と低い

説明:

これは正常動作です
SigLIPはsigmoid損失で学習されており、類似度の絶対値は低めになります
相対的なランキングが重要で、Top-K結果の順位が正しければ問題ありません
ColVBERTの類似度が高くても、クロスモーダル類似度が負(-0.024)なら誤動作です

4. 画像読み込みエラー

エラー:

PIL.UnidentifiedImageError: cannot identify image file

解決方法:

from PIL import Image

# RGB変換を必ず行う
image = Image.open(path).convert('RGB')

# ファイル形式確認
print(f"画像フォーマット: {image.format}")
print(f"サイズ: {image.size}")

5. メモリ不足

エラー:

MemoryError: Unable to allocate array

解決方法:

# ドキュメント数を削減
documents = doc_generator.create_synthetic_documents(
    num_documents=20  # 100 → 20に削減
)

# テキスト長を制限
text_content = doc['content'][:500]  # 最初の500文字のみ

# バッチ処理で逐次エンコード
for i in range(0, len(documents), batch_size):
    batch = documents[i:i+batch_size]
    # エンコード処理

6. transformersバージョンエラー

エラー:

ImportError: SigLIP requires transformers>=4.35.0

解決方法:

# transformersをアップグレード
pip install --upgrade transformers>=4.35.0

# 互換性確認
pip show transformers

⚡ パフォーマンス最適化

GPU最適化

import torch

# GPU利用可能確認
if torch.cuda.is_available():
    device = "cuda"
    print(f"GPU: {torch.cuda.get_device_name(0)}")
    print(f"VRAM: {torch.cuda.get_device_properties(0).total_memory / 1e9:.2f} GB")
else:
    device = "cpu"
    print("CPU モードで実行")

# ColModernVBERT設定
config = {
    'device': device,
    'embedding_dim': 768,
    'use_cross_attention': True
}

バッチ処理最適化

# 大量ドキュメント処理
batch_size = 32 if torch.cuda.is_available() else 8

encoded_docs = []
for i in range(0, len(documents), batch_size):
    batch = documents[i:i+batch_size]
  
    # バッチエンコーディング
    texts = [doc['content'][:500] for doc in batch]
    images = [Image.open(doc['image_path']).convert('RGB') 
              for doc in batch]
  
    embeddings = visual_raptor.colbert_encoder.encode_multimodal(
        texts, images
    )
  
    encoded_docs.extend(embeddings)
  
    print(f"進捗: {min(i+batch_size, len(documents))}/{len(documents)}")

メモリ最適化

# メモリ効率的な処理
import gc

for doc in documents:
    # エンコード
    embedding = encode_document(doc)
  
    # CPU移動してメモリ解放
    embedding = embedding.detach().cpu()
  
    # 定期的にガベージコレクション
    if len(encoded_docs) % 100 == 0:
        gc.collect()
        if torch.cuda.is_available():
            torch.cuda.empty_cache()

並列処理

from concurrent.futures import ThreadPoolExecutor
import numpy as np

def encode_single_doc(doc):
    image = Image.open(doc['image_path']).convert('RGB')
    text = doc['content'][:500]
    return visual_raptor.colbert_encoder.encode_multimodal([text], [image])

# 並列エンコーディング（CPU専用）
with ThreadPoolExecutor(max_workers=4) as executor:
    embeddings = list(executor.map(encode_single_doc, documents))

📈 実行結果の解釈

SigLIP類似度の理解

ColModernVBERT (SigLIP)の類似度スコアは低めになりますが、これは設計上の特性です：

# 類似度例
query: "津波警報"
results:
  1. TSUNAMI - Sendai (0.0461)  ← 最も関連性高い
  2. FIRE - Sapporo (0.0274)    ← 中程度
  3. EARTHQUAKE - Tokyo (0.0215) ← 低い

重要なポイント:

✅ スコアの絶対値ではなく順位が重要
✅ Top-1が最も関連性の高い文書であればOK
✅ SigLIPはゼロショット転送に最適化されている

クロスモーダル類似度の評価基準

エンコーダー	クロスモーダル類似度	評価
ColModernVBERT	0.168	✅ 正常（テキスト↔画像が対応）
ColVBERT	-0.024	⚠️ 異常（逆方向を向いている）

正常な範囲:

0.1 〜 0.3: SigLIPとして正常
0.6 〜 0.9: 従来のCLIPモデル範囲
負の値: 異常（テキストと画像が対応していない）

🎓 使用例・ユースケース

1. 災害文書検索システム

# 避難所検索
query = "仙台市青葉区の避難所を教えてください"
query_emb = visual_raptor.colbert_encoder.encode_text([query])

# Top-5検索
similarities = compute_similarities(query_emb, document_embeddings)
top_5 = get_top_k(similarities, k=5)

for rank, (doc_id, score) in enumerate(top_5, 1):
    doc = documents[doc_id]
    print(f"{rank}. {doc['title']} (類似度: {score:.4f})")

2. マルチモーダル質問応答

# テキスト+画像による質問
question = "この地図の避難経路を説明してください"
map_image = Image.open("evacuation_map.png")

# マルチモーダルクエリ
query_emb = visual_raptor.colbert_encoder.encode_multimodal(
    [question], [map_image]
)

# 類似文書検索
similar_docs = search_documents(query_emb, document_index)

# LLMで回答生成
answer = llm.invoke(f"質問: {question}\n参考文書: {similar_docs}")

3. バッチドキュメント分類

# カテゴリ別クエリ
categories = {
    'earthquake': "地震関連の情報",
    'tsunami': "津波警報・注意報",
    'evacuation': "避難所・避難経路",
    'recovery': "復旧・復興情報"
}

# 各文書を分類
for doc in documents:
    doc_emb = encode_document(doc)
  
    best_category = None
    best_score = -1
  
    for cat, query_text in categories.items():
        query_emb = visual_raptor.colbert_encoder.encode_text([query_text])
        score = compute_similarity(doc_emb, query_emb)
      
        if score > best_score:
            best_score = score
            best_category = cat
  
    doc['category'] = best_category
    doc['confidence'] = best_score

📚 参考文献・リソース

論文

RAPTOR: Recursive Abstractive Processing for Tree-Organized Retrieval
- Sarthi, P., et al. (2024)
ColBERT: Efficient and Effective Passage Search via Contextualized Late Interaction
- Khattab, O., & Zaharia, M. (2020)
SigLIP: Sigmoid Loss for Language Image Pre-training
- Zhai, X., et al. (2023)
BLIP: Bootstrapping Language-Image Pre-training
- Li, J., et al. (2022)

リポジトリ・ツール

JinaVDR: Visual Document Retrieval
ColBERT: Original implementation
LangChain: LLM framework
Ollama: Local LLM server

ハードウェア要件

最小構成:

CPU: 4コア以上
RAM: 8GB
ストレージ: 5GB

推奨構成:

CPU: 8コア以上
RAM: 16GB以上
GPU: NVIDIA GPU (8GB VRAM以上)
ストレージ: 10GB以上

検証済み環境:

GPU: NVIDIA GeForce RTX 4060 Ti (16GB VRAM)
CUDA: 11.8 / 12.9
Python: 3.12
PyTorch: 2.7.1+cu118
OS: Windows 11

🤝 コントリビューション

プルリクエストや Issue の報告を歓迎します。

開発ガイドライン

フォークしてブランチ作成
機能追加・バグ修正
テスト実行
プルリクエスト作成

📝 ライセンス

MIT License

📧 連絡先

技術的な質問や改善提案は、GitHub Issues をご利用ください。

🌳 RAPTOR Tree構築性能比較（追加実験）

実際のPDFデータ（131ページ）を使用したRAPTOR階層ツリー構築の包括的比較を実施しました。

実行コマンド:

python compare_encoders_with_raptor.py

⚡ Tree構築時間

指標	ColVBERT (BLIP)	ColModernVBERT (SigLIP)	改善率
総構築時間	1173.33秒 (19分33秒)	1145.13秒 (19分5秒)	1.025倍高速 ⚡
時間短縮	-	28.2秒削減	-

🌲 Tree構造

両エンコーダーで完全に同一の階層構造を生成:

指標	ColVBERT (BLIP)	ColModernVBERT (SigLIP)
総ノード数	37	37
リーフノード	27	27
内部ノード	10	10
最大深度	3	3

💾 GPU使用量（Tree構築時）

指標	ColVBERT (BLIP)	ColModernVBERT (SigLIP)	差分
ピークメモリ	3,217 MB	4,093 MB	+876 MB (+27.2%)

📊 クラスタリング品質

Depth 0 (131ドキュメント):

Silhouette Score: 0.7799 (両エンコーダー共通)
選択クラスタ数: k=2 (自動選択)
クラスタリング時間: 0.07-0.08秒

階層構造:

Depth 0: 131 docs → 2 clusters (87 + 44)
├─ Depth 1: 各クラスタを5つに分割
│  ├─ Depth 2: さらに2-5クラスタに細分化
│  │  └─ Depth 3: リーフノード (最大深度到達)

🔍 エンコーディング内訳

Depth 0 (131ドキュメント):

指標	ColVBERT (BLIP)	ColModernVBERT (SigLIP)	改善率
エンコーディング時間	80.47秒	77.08秒	1.04倍高速

全階層合計 (再帰的エンコーディング):

Depth 0: 131ドキュメント
Depth 1: 87 + 44 = 131ドキュメント相当
Depth 2: 複数の小クラスタ
Depth 3: リーフノード

⏱️ 処理時間の内訳

RAPTOR Tree構築の主要コンポーネント:

エンコーディング (約40-45%): 画像+テキストの埋め込み生成
クラスタリング (約5%): FAISS k-meansとSilhouette評価
LLM要約 (約50-55%): Ollama granite-code:8bによる各クラスタの要約生成

注記: 構築時間の大部分はLLMによる要約生成が占めており、エンコーダーの速度差は相対的に小さくなります。

✨ 主要な発見

構築時間: わずかな差（1.025倍）
- 総時間の大部分はLLM要約生成
- エンコーダー速度差(1.04倍)は全体では目立たない
Tree構造: 完全に同一
- 同じクラスタリング結果
- 同じSilhouette Score (0.7799)
- エンコーディング空間が類似
GPU使用量: SigLIPが27%増加
- ピーク時+876MB
- より大きなモデルサイズが影響
クラスタリング品質: 優れた分離性能
- Silhouette Score 0.7799 は高品質
- 自動的に最適なクラスタ数を選択

🎯 推奨事項

RAPTOR Tree構築における選択基準:

シナリオ	推奨エンコーダー	理由
GPU制約あり	ColVBERT (BLIP)	3.2GB vs 4.1GB（876MB節約）
速度優先	ColModernVBERT (SigLIP)	わずかに高速（28秒短縮）
バランス重視	どちらでも可	性能差は最小限

重要な洞察:

RAPTOR Tree構築では、エンコーダー性能差はLLM処理時間に吸収される
両エンコーダーとも実用レベルで優秀（約19分で131ページ処理）
GPU制約がなければSigLIPを推奨、制約があればBLIPも十分

出力ファイル:

data/encoder_comparison_with_raptor/results/raptor_comparison.png - 比較グラフ
data/encoder_comparison_with_raptor/results/raptor_comparison_results.json - 詳細データ
data/encoder_comparison_with_raptor/raptor_trees/colbert_blip_tree.json - BLIP Tree統計
data/encoder_comparison_with_raptor/raptor_trees/colmodern_siglip_tree.json - SigLIP Tree統計

作成日: 2025年10月23日 最終更新: 2025年10月24日 バージョン: 2.3 - RAPTOR Tree構築性能比較追加版

主要アップデート:

✅ ColModernVBERT (SigLIP) 1.3倍高速化
✅ 包括的性能比較（GPU使用量 & ランキング指標）
✅ MRR 70%改善、NDCG@5 40%改善
✅ PyMuPDF統合（Tesseract不要）
✅ 実PDF 131ページ処理実績
✅ SigLIP評価指標6種（グラフ化対応）
✅ RAPTOR Tree構築性能比較 (NEW!)
- Tree構築時間: 両エンコーダーほぼ同等（1.025倍差）
- Tree構造: 完全に同一（37ノード、深度3）
- GPU使用量: SigLIP +876MB (27.2%増)
- クラスタリング品質: 同一 (Silhouette 0.7799)

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
data		data
results		results
.gitignore		.gitignore
README.md		README.md
analyze_embeddings.py		analyze_embeddings.py
colmodern_vbert_demo.py		colmodern_vbert_demo.py
compare_encoders.py		compare_encoders.py
compare_encoders_realdata.py		compare_encoders_realdata.py
compare_encoders_with_raptor.py		compare_encoders_with_raptor.py
complete_system_demo.py		complete_system_demo.py
continuous_gpu_workload.py		continuous_gpu_workload.py
disaster_dataset_generator.py		disaster_dataset_generator.py
enhanced_visual_processing.py		enhanced_visual_processing.py
fix_integrated_system.py		fix_integrated_system.py
fix_jina_all.py		fix_jina_all.py
fix_jina_comprehensive.py		fix_jina_comprehensive.py
fix_jina_escaped_newlines.py		fix_jina_escaped_newlines.py
fix_jina_final.py		fix_jina_final.py
fix_jina_vdr_benchmark.py		fix_jina_vdr_benchmark.py
full_feature_demo.py		full_feature_demo.py
gpu_accelerated_demo.py		gpu_accelerated_demo.py
gpu_immediate_activation.py		gpu_immediate_activation.py
gpu_utilization_test.py		gpu_utilization_test.py
integrated_system.py		integrated_system.py
integrated_system.py.backup		integrated_system.py.backup
integrated_system_backup.py		integrated_system_backup.py
integrated_system_simple.py		integrated_system_simple.py
jina_vdr_benchmark.py		jina_vdr_benchmark.py
jina_vdr_benchmark_backup.py		jina_vdr_benchmark_backup.py
jina_vdr_benchmark_before_fix.py		jina_vdr_benchmark_before_fix.py
minimal_demo.py		minimal_demo.py
process_pdf_documents.py		process_pdf_documents.py
quick_start_demo.py		quick_start_demo.py
quick_start_simple.py		quick_start_simple.py
quick_start_working.py		quick_start_working.py
requirements.txt		requirements.txt
run_visual_raptor.py		run_visual_raptor.py
run_visual_raptor_on_pdfs.py		run_visual_raptor_on_pdfs.py
setup.py		setup.py
simple_ollama_demo.py		simple_ollama_demo.py
visual_raptor_colbert.py		visual_raptor_colbert.py
visual_raptor_demo.py		visual_raptor_demo.py

tk-yasuno/visual-raptor-colvbert

Folders and files

Latest commit

History

Repository files navigation

Visual RAPTOR ColVBERT Integration System

📋 目次

概要

🎯 主要機能

🚀 実行結果サマリー

✅ 検証済み実行結果（2025年10月23日）

1. Visual RAPTOR ColBERT 基本実行

2. ColModernVBERT vs ColVBERT 比較実験

3. 埋め込み特性分析

4. 実際のPDF文書処理（131ページ）

📊 SigLIP評価指標

評価指標の説明

全体集計指標（8クエリ平均）

📈 評価指標グラフ

� エンコーダー性能比較

ColModernVBERT (SigLIP) vs ColVBERT (BLIP) 包括的ベンチマーク

⚡ エンコーディング性能

💾 GPU使用量

📊 ランキング指標（情報検索の質）

📈 可視化グラフ

✨ 主要な発見

🎯 推奨事項

�📂 システム構成

📂 システム構成

🛠️ 技術スタック

基盤技術

AI/MLモデル

推奨: ColModernVBERT (SigLIP)

従来型: ColVBERT (BLIP)

その他

PDF処理・OCR技術

📥 インストール

1. 前提条件

2. Python環境セットアップ

3. Ollama セットアップ

4. GPU設定（オプション）

🎯 クイックスタート

最速実行（推奨）

実際のPDF文書処理（推奨）

エンコーダー比較実験

埋め込み特性分析

📖 詳細な使用方法

1. 基本的なPython API使用例

📖 詳細な使用方法

1. 基本的なPython API使用例

2. 従来型ColVBERT (BLIP) を使用する場合

3. バッチ処理

4. カスタム設定

4. カスタム設定

📊 ベンチマーク結果

ColModernVBERT vs ColVBERT 比較（検証済み）

埋め込み特性分析

ColModernVBERT (SigLIP) - 推奨

ColVBERT (BLIP) - 問題あり

JinaVDR ベンチマーク対応

災害文書カテゴリ

🔧 トラブルシューティング

よくある問題と解決方法

1. Ollama接続エラー

2. CUDA/GPU認識エラー

3. 類似度スコアが低い

4. 画像読み込みエラー

5. メモリ不足

6. transformersバージョンエラー

⚡ パフォーマンス最適化

GPU最適化

バッチ処理最適化

メモリ最適化

並列処理

📈 実行結果の解釈

SigLIP類似度の理解

クロスモーダル類似度の評価基準

🎓 使用例・ユースケース

1. 災害文書検索システム

2. マルチモーダル質問応答

Packages