aurak/docs/1.0/VISION_PIPELINE_COMPLETE.md

# Vision Pipeline 完全実装

## 🎯 概要

Vision Pipeline は、画像とテキストが混在したドキュメントを処理するためのシステムの「高精度モード」機能です。LibreOffice による変換、ImageMagick による画像処理、および Vision モデルによる分析を通じて、完全なドキュメント内容の抽出を実現します。

### デュアルモードの比較

| 特徴 | 高速モード | 高精度モード |
|------|---------|---------|
| 処理ツール | Apache Tika | Vision Pipeline |
| 画像処理 | ❌ スキップ | ✅ 完全な分析 |
| 処理速度 | 高速 | 低速 |
| コスト | 無料 | 約 $0.01/ページ |
| 適用シーン | テキストのみのドキュメント | 画像・テキスト混在ドキュメント |

## 🏗️ 技術アーキテクチャ

### コアフロー

```
ドキュメントのアップロード → LibreOffice 変換 → PDF を画像化 → Vision 分析 → ベクトルインデックス
```

### サービスコンポーネント

#### 1. LibreOffice サービス (FastAPI)

- **ポート**: 8100
- **機能**: ドキュメント形式の統一化 (Word/PPT/Excel → PDF)
- **API ドキュメント**: <http://localhost:8100/docs>

```python
# libreoffice-server/main.py
from fastapi import FastAPI, File, UploadFile
from pydantic import BaseModel

app = FastAPI(title="ドキュメント変換サービス")

@app.post("/convert")
async def convert(file: UploadFile = File(...)):
    # 変換ロジック
    return {"pdf_path": "...", "converted": True}

@app.get("/health")
async def health():
    return {"status": "healthy"}
```

#### 2. PDF2Image サービス (Node.js)

```typescript
// server/src/pdf2image/pdf2image.service.ts
@Injectable()
export class Pdf2ImageService {
  async convertToImages(pdfPath: string): Promise<string[]> {
    // ImageMagick を使用して変換
    const images = await this.imagemagick.convert(pdfPath, {
      density: 300,
      format: 'jpeg',
      quality: 85
    });
    return images;
  }
}
```

#### 3. Vision サービス

```typescript
// server/src/vision/vision.service.ts
@Injectable()
export class VisionService {
  async analyzeImage(imagePath: string, modelConfig: ModelConfig): Promise<VisionResult> {
    // OpenAI/Gemini Vision API を呼び出し
    const result = await this.callVisionAPI(imagePath, modelConfig);
    return {
      text: result.text,
      confidence: result.confidence,
      layout: result.layout
    };
  }
}
```

## 🚀 デプロイ設定

### Docker Compose

```yaml
services:
  libreoffice:
    build:
      context: ./libreoffice-server
    ports:
      - "8100:8100"
    volumes:
      - ./uploads:/uploads
      - ./temp:/temp

  server:
    environment:
      - LIBREOFFICE_URL=http://libreoffice:8100
      - TEMP_DIR=/app/temp
    depends_on:
      - libreoffice
```

### 環境変数

```env
# LibreOffice サービス
LIBREOFFICE_URL=http://127.0.0.1:8100

# 一時ファイルディレクトリ
TEMP_DIR=./temp

# Vision API 設定
VISION_API_KEY=sk-xxx
VISION_MODEL=gpt-4-vision-preview
```

## 💰 コスト管理

### 予想コスト

| ドキュメント形式 | ページ数 | 予想コスト | 処理時間 |
|---------|------|---------|---------|
| PDF | 10ページ | $0.10 | 約 1分 |
| Word | 50ページ | $0.50 | 約 5分 |
| PPT | 30ページ | $0.30 | 約 3分 |

### 節約戦略

- 小規模ドキュメント (<10ページ): 高精度モードを使用。
- 大規模ドキュメント (>50ページ): 分割して処理するか、高速モードを検討。
- テキストのみのドキュメント: 常に高速モードを使用。

## 🔧 利用方法

### 1. サービスの起動

```bash
# すべてのサービスを起動
docker-compose up -d

# 状態の確認
docker-compose ps
```

### 2. サービスの検証

```bash
# LibreOffice のヘルスチェック
curl http://localhost:8100/health

# API ドキュメントの確認
open http://localhost:8100/docs

# 変換テスト
curl -X POST -F "file=@test.docx" http://localhost:8100/convert
```

### 3. Vision モデルの設定

1. 「モデル管理」に移動します。
2. Vision をサポートするモデル (GPT-4V/Gemini Pro Vision) を追加します。
3. API キーを設定します。
4. 「ビジョンをサポート」オプションにチェックを入れます。

### 4. アップロードテスト

1. PDF/Word/PPT ファイルを選択します。
2. アップロード画面で「高精度モード」を選択します。
3. 処理の進捗とコストの見積もりを確認します。

## 🔍 トラブルシューティング

### LibreOffice サービスの問題

```bash
# コンテナ状態の確認
docker-compose ps libreoffice

# ログを表示
docker-compose logs libreoffice

# サービスの再起動
docker-compose restart libreoffice
```

### Vision 分析の失敗

- API キーの設定を検証してください。
- モデルが Vision をサポートしているか確認してください。
- ネットワーク接続が正常か確認してください。
- 詳細なエラーログを確認してください。

### メモリ使用率が高すぎる場合

- バッチ処理サイズを調整してください。
- 同時処理数を制限してください。
- メモリの使用状況を監視してください。

## 📊 監視指標

### 主要な指標

- 変換成功率: >95%
- 平均処理時間: <10分 / 100ページ
- Vision 分析の精度: >85%
- コスト管理: <$0.30 / ドキュメント

### ログの確認

```bash
# リアルタイムログ
docker-compose logs -f server | grep "Vision\|高精度モード"

# LibreOffice ログ
docker-compose logs -f libreoffice
```

## ⚡ クイックコマンド

```bash
# 一括起動
docker-compose up -d

# ヘルスチェック
curl http://localhost:8100/health

# API ドキュメントを表示
open http://localhost:8100/docs

# 変換テスト
curl -X POST -F "file=@test.docx" http://localhost:8100/convert | jq

# ログを表示
docker-compose logs -f libreoffice server
```

## 🎯 技術選型の説明

### なぜ FastAPI を選んだのか

| 特徴 | Flask | FastAPI | 優位点 |
|------|-------|---------|------|
| パフォーマンス | 中程度 | ⭐⭐⭐⭐⭐ 非同期 | 2〜3倍高速 |
| ドキュメント | 拡張が必要 | ⭐⭐⭐⭐⭐ 自動生成 | `/docs` で即座にアクセス可能 |
| 型安全性 | オプション | ⭐⭐⭐⭐⭐ 強制的 | エラーの削減 |
| 本番対応 | 設定が必要 | ⭐⭐⭐⭐⭐ 即利用可能 | 最小限の設定で運用可能 |

### FastAPI の核となるメリット

1. **自動ドキュメント**: <http://localhost:8100/docs> にて利用可能。
2. **型安全性**: リクエストパラメータを自動的に検証。
3. **非同期処理**: 複数のリクエストを同時に処理可能。
4. **本番対応**: パフォーマンスの最適化が組み込まれている。

---

**更新日**: 2025-01-14
**バージョン**: v2.0
**ステータス**: 実装済み