# チャンクサイズの制限に関する完全スキーム ## 🎯 設計目標 **主要な問題の解決：** 1. ✅ チャンクサイズがモデルの入力制限を超えないようにする 2. ✅ 環境変数でグローバルな上限を設定可能にする 3. ✅ フロントエンドのスライダーで動的に制限し、上限を超えられないようにする 4. ✅ バックエンドで自動検証と調整を行う --- ## 📋 設定階層構造 ``` ┌─────────────────────────────────────────┐ │ 環境変数の設定 (server/.env) │ │ MAX_CHUNK_SIZE=8191 │ │ MAX_OVERLAP_SIZE=200 │ └─────────────────────────────────────────┘ ↓ 優先度1（最も厳格） ┌─────────────────────────────────────────┐ │ モデル制限設定 (ChunkConfigService) │ │ OpenAI: 8191 tokens │ │ Gemini: 2048 tokens │ └─────────────────────────────────────────┘ ↓ 優先度2 ┌─────────────────────────────────────────┐ │ ユーザー設定 (フロントエンドスライダー)│ │ chunkSize: 200 tokens │ │ chunkOverlap: 40 tokens │ └─────────────────────────────────────────┘ ↓ 最終検証 ┌─────────────────────────────────────────┐ │ 実際に適用される値 (自動調整) │ └─────────────────────────────────────────┘ ``` --- ## 🔧 環境変数の設定 ### server/.env ```env # チャンクサイズの上限 (tokens) # 使用する埋め込みモデルに合わせて設定 # OpenAI text-embedding-3-large: 8191 # OpenAI text-embedding-3-small: 8191 # Google Gemini embedding-001: 2048 MAX_CHUNK_SIZE=8191 # チャンクオーバーラップの上限 (tokens) # チャンクサイズの 10-20% を推奨 MAX_OVERLAP_SIZE=200 ``` --- ## 🏗️ アーキテクチャの実装 ### 1. ChunkConfigService (バックエンドコア) ```typescript // 環境変数から上限を読み込む private readonly envMaxChunkSize: number; private readonly envMaxOverlapSize: number; // 主要なモデルの制限 private readonly MODEL_LIMITS = { 'text-embedding-3-large': { maxInputTokens: 8191, maxBatchSize: 2048, expectedDimensions: 3072, }, 'embedding-001': { maxInputTokens: 2048, maxBatchSize: 100, expectedDimensions: 768, }, }; // 最終的な上限を計算 const effectiveMaxChunkSize = Math.min( this.envMaxChunkSize, // 環境変数 limits.maxInputTokens // モデルの制限 ); ``` ### 2. 検証ロジック ```typescript async validateChunkConfig(chunkSize, chunkOverlap, modelId, userId) { const warnings = []; // 1. 最終的な上限を計算 const effectiveMaxChunkSize = Math.min( this.envMaxChunkSize, limits.maxInputTokens ); // 2. チャンクサイズの検証 if (chunkSize > effectiveMaxChunkSize) { warnings.push(`上限 ${effectiveMaxChunkSize} を超えています`); chunkSize = effectiveMaxChunkSize; } // 3. オーバーラップサイズの検証 const maxOverlap = Math.min( this.envMaxOverlapSize, Math.floor(chunkSize * 0.5) ); if (chunkOverlap > maxOverlap) { warnings.push(`オーバーラップが上限 ${maxOverlap} を超えています`); chunkOverlap = maxOverlap; } return { chunkSize, chunkOverlap, warnings, effectiveMaxChunkSize, effectiveMaxOverlapSize, }; } ``` ### 3. API エンドポイント ```typescript // GET /api/knowledge-bases/chunk-config/limits?embeddingModelId=xxx { "maxChunkSize": 8191, "maxOverlapSize": 200, "defaultChunkSize": 200, "defaultOverlapSize": 40, "modelInfo": { "name": "text-embedding-3-large", "maxInputTokens": 8191, "maxBatchSize": 2048, "expectedDimensions": 3072 } } ``` --- ## 🎨 フロントエンドの実装 ### IndexingModal.tsx ```typescript // 状態管理 const [limits, setLimits] = useState(null); const [chunkSize, setChunkSize] = useState(200); const [chunkOverlap, setChunkOverlap] = useState(40); // モデル選択時に制限をロード useEffect(() => { if (selectedEmbedding) { const limitData = await chunkConfigService.getLimits(selectedEmbedding, token); setLimits(limitData); // 現在の値を自動調整 if (chunkSize > limitData.maxChunkSize) { setChunkSize(limitData.maxChunkSize); } } }, [selectedEmbedding]); // スライダー変更時の処理 const handleChunkSizeChange = (value) => { if (limits && value > limits.maxChunkSize) { showWarning(`最大値は ${limits.maxChunkSize} です`); setChunkSize(limits.maxChunkSize); return; } setChunkSize(value); // オーバーラップの自動調整 if (chunkOverlap > value * 0.5) { setChunkOverlap(Math.floor(value * 0.5)); } }; ``` ### UI 機能 1. **動的なスライダー範囲** ```jsx ``` 2. **制限のリアルタイム表示** ``` チャンクサイズ: 200 tokens (上限: 8191) ``` 3. **モデル情報の表示** ``` モデル: text-embedding-3-large チャンク上限: 8191 tokens オーバーラップ上限: 200 tokens バッチ制限: 2048 ``` 4. **最適化アドバイス** ``` 💡 最適化アドバイス • チャンクが大きすぎます (800)。検索精度に影響する可能性があります。 • 少なくとも 80 tokens のオーバーラップを推奨します。 • 最大値を使用すると、処理速度が低下する可能性があります。 ``` --- ## 📊 ユースケース例 ### シナリオ1: OpenAI + 環境変数による制限 **設定:** ```env MAX_CHUNK_SIZE=4000 # モデルより厳格なカスタム制限 ``` **ユーザー操作:** ``` 1. モデル選択: text-embedding-3-large 2. スライダー上限: 4000 (環境変数による制限) 3. ユーザー設定: 3000 tokens 4. バックエンド検証: ✅ 合格 5. 実適用値: 3000 tokens ``` ### シナリオ2: Gemini + モデルによる制限 **設定:** ```env MAX_CHUNK_SIZE=8191 # 環境変数は緩和 ``` **ユーザー操作:** ``` 1. モデル選択: embedding-001 2. スライダー上限: 2048 (モデル制限の方が厳格) 3. ユーザー設定: 1500 tokens 4. バックエンド検証: ✅ 合格 5. 実適用値: 1500 tokens ``` ### シナリオ3: 制限超過時の自動調整 **ユーザー操作:** ``` 1. モデル選択: embedding-001 (制限 2048) 2. ユーザー入力: 3000 tokens 3. フロントエンド表示: "最大値は 2048 です" 4. スライダーを自動的に 2048 に調整 5. バックエンド記録: ⚠️ 設定修正ログ ``` --- ## 🔍 優先順位ルール ### 上限計算ロジック ```typescript 最終的な上限 = min(環境変数, モデル制限) 例: - 環境変数: 8191 - モデル制限: 2048 (Gemini) - 最終上限: 2048 ✅ - 環境変数: 4000 - モデル制限: 8191 (OpenAI) - 最終上限: 4000 ✅ ``` ### 検証順序 ```typescript 1. チャンクサイズ ≤ 最終上限 かを確認 2. チャンクサイズ ≥ 最小値 (50) かを確認 3. オーバーラップサイズ ≤ 環境変数の上限 かを確認 4. オーバーラップサイズ ≤ チャンクサイズの 50% かを確認 5. オーバーラップサイズ ≥ 0 かを確認 ``` --- ## 📝 デプロイ時の推奨設定 ### 開発環境 ```env # テストに適した設定 MAX_CHUNK_SIZE=8191 MAX_OVERLAP_SIZE=200 ``` ### 本番環境 (OpenAI) ```env # 大容量ファイルへの対策を考慮した保守的な設定 MAX_CHUNK_SIZE=4000 MAX_OVERLAP_SIZE=500 ``` ### 本番環境 (Gemini) ```env # モデルの制限に合わせた設定 MAX_CHUNK_SIZE=2048 MAX_OVERLAP_SIZE=300 ``` --- ## ✅ メリットのまとめ | 特徴 | 実装方法 | 効果 | |------|----------|------| | **安全性** | 環境変数 + モデル制限の二重保護 | API の制限を超えない | | **柔軟性** | 環境変数で調整可能 | 異なるデプロイ要件に対応 | | **ユーザー体験** | フロントエンドでの動的制限 | 無効な値を選択できない | | **透明性** | 制限情報をリアルタイム表示 | 設定理由が明確 | | **自動調整** | バックエンドでの検証・修正 | 実行時のエラーを回避 | | **ログ管理** | 詳細な警告情報 | 問題の切り分けがスムーズ | --- ## 🎯 結論 このスキームにより、以下が実現されました： 1. ✅ **環境変数の設定** - グローバルに制御可能な上限 2. ✅ **モデル制限の認識** - 異なるモデルの自動識別 3. ✅ **フロントエンドでの制限** - 無効な値を選択不可に 4. ✅ **バックエンド検証** - 二重の保険 5. ✅ **自動調整** - 制限超過時の自動修正 6. ✅ **透明なフィードバック** - 制限理由の表示 **これで、ユーザーがモデルの制限を超える値を選択することはなくなり、システムが自動的に保護されます！**