KnowledgeBase/docs/1.0/CHUNK_SIZE_LIMITS.md

チャンクサイズの制限に関する完全スキーム

🎯 設計目標

主要な問題の解決：

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

# チャンクサイズの上限 (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 (バックエンドコア)

// 環境変数から上限を読み込む
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. 検証ロジック

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 エンドポイント

// 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

// 状態管理
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. 動的なスライダー範囲

   <input
    type="range"
    min="50"
    max={limits?.maxChunkSize || 8191}  // 動的な上限
    value={chunkSize}
    onChange={handleChunkSizeChange}
   />
   

2. 制限のリアルタイム表示

   チャンクサイズ: 200 tokens (上限: 8191)
   

3. モデル情報の表示

   モデル: text-embedding-3-large
   チャンク上限: 8191 tokens
   オーバーラップ上限: 200 tokens
   バッチ制限: 2048
   

4. 最適化アドバイス

   💡 最適化アドバイス
   • チャンクが大きすぎます (800)。検索精度に影響する可能性があります。
   • 少なくとも 80 tokens のオーバーラップを推奨します。
   • 最大値を使用すると、処理速度が低下する可能性があります。
   

---

📊 ユースケース例

シナリオ1: OpenAI + 環境変数による制限

設定:

MAX_CHUNK_SIZE=4000  # モデルより厳格なカスタム制限

ユーザー操作:

1. モデル選択: text-embedding-3-large
2. スライダー上限: 4000 (環境変数による制限)
3. ユーザー設定: 3000 tokens
4. バックエンド検証: ✅ 合格
5. 実適用値: 3000 tokens

シナリオ2: Gemini + モデルによる制限

設定:

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. バックエンド記録: ⚠️ 設定修正ログ

---

🔍 優先順位ルール

上限計算ロジック

最終的な上限 = min(環境変数, モデル制限)

例:
- 環境変数: 8191
- モデル制限: 2048 (Gemini)
- 最終上限: 2048 ✅

- 環境変数: 4000
- モデル制限: 8191 (OpenAI)
- 最終上限: 4000 ✅

検証順序

1. チャンクサイズ ≤ 最終上限 かを確認
2. チャンクサイズ ≥ 最小値 (50) かを確認
3. オーバーラップサイズ ≤ 環境変数の上限 かを確認
4. オーバーラップサイズ ≤ チャンクサイズの 50% かを確認
5. オーバーラップサイズ ≥ 0 かを確認

---

📝 デプロイ時の推奨設定

開発環境

# テストに適した設定
MAX_CHUNK_SIZE=8191
MAX_OVERLAP_SIZE=200

本番環境 (OpenAI)

# 大容量ファイルへの対策を考慮した保守的な設定
MAX_CHUNK_SIZE=4000
MAX_OVERLAP_SIZE=500

本番環境 (Gemini)

# モデルの制限に合わせた設定
MAX_CHUNK_SIZE=2048
MAX_OVERLAP_SIZE=300

---

✅ メリットのまとめ

特徴	実装方法	効果
安全性	環境変数 + モデル制限の二重保護	API の制限を超えない
柔軟性	環境変数で調整可能	異なるデプロイ要件に対応
ユーザー体験	フロントエンドでの動的制限	無効な値を選択できない
透明性	制限情報をリアルタイム表示	設定理由が明確
自動調整	バックエンドでの検証・修正	実行時のエラーを回避
ログ管理	詳細な警告情報	問題の切り分けがスムーズ

---

🎯 結論

このスキームにより、以下が実現されました：

1. ✅ 環境変数の設定 - グローバルに制御可能な上限
2. ✅ モデル制限の認識 - 異なるモデルの自動識別
3. ✅ フロントエンドでの制限 - 無効な値を選択不可に
4. ✅ バックエンド検証 - 二重の保険
5. ✅ 自動調整 - 制限超過時の自動修正
6. ✅ 透明なフィードバック - 制限理由の表示

これで、ユーザーがモデルの制限を超える値を選択することはなくなり、システムが自動的に保護されます！