GrepAI チャンキング設定

このスキルでは、GrepAI がソースファイルを埋め込み用の小さなセグメントに分割する方法と、あなたのコードベースに合わせてチャンキングを最適化する方法について説明します。

このスキルを使用する場合

• 検索精度の最適化
• コードスタイルに合わせた調整 (冗長 vs 簡潔)
• 検索結果のトラブルシューティング
• インデックス作成の仕組みを理解する

チャンキングとは

チャンキングはソースファイルを埋め込み用の小さなセグメントに分割するプロセスです:

┌─────────────────────────────────────┐
│         Large Source File           │
│         (1000+ tokens)              │
└─────────────────────────────────────┘
                  ↓
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Chunk 1 │ │ Chunk 2 │ │ Chunk 3 │
│ ~512    │ │ ~512    │ │ ~512    │
│ tokens  │ │ tokens  │ │ tokens  │
└─────────┘ └─────────┘ └─────────┘
                  ↓
          Each chunk gets
          its own embedding

チャンキングが重要な理由

埋め込みモデルには最適な入力サイズがあります:

• チャンクが大きすぎる場合: 検索結果の精度が低下
• チャンクが小さすぎる場合: コンテキストが失われ、結果が断片化
• ちょうど良い場合: 精度とコンテキストの良好なバランス

設定

基本設定

# .grepai/config.yaml
chunking:
  size: 512      # チャンクあたりのトークン数
  overlap: 50    # チャンク間のオーバーラップ

パラメータの理解

チャンクサイズ

チャンクあたりのトークン数の目標値です。

サイズ	効果
256	より精密で、コンテキストが少ない
512	バランス型 (デフォルト)
1024	より多くのコンテキスト、精度が低い

オーバーラップ

隣接するチャンク間で共有されるトークン。境界でのコンテキストを保持します。

オーバーラップ	効果
0	オーバーラップなし、境界でコンテキスト喪失の可能性
50	標準的なオーバーラップ (デフォルト)
100	より多くのコンテキスト、インデックスが大きくなる

可視化

size=512、overlap=50 の場合:

File: auth.go (1000 tokens)

Chunk 1: tokens 1-512
         ┌────────────────────────────────────┐
         │ func Login(user, pass)...          │
         └────────────────────────────────────┘
                                    ↘
                              50 token overlap
                                    ↙
Chunk 2: tokens 463-974
         ┌────────────────────────────────────┐
         │ ...validate credentials...         │
         └────────────────────────────────────┘
                                    ↘
                              50 token overlap
                                    ↙
Chunk 3: tokens 925-1000
         ┌──────────────┐
         │ ...return    │
         └──────────────┘

言語別の推奨設定

冗長な言語 (Java、C#)

chunking:
  size: 768    # メソッド全体をキャプチャするために大きめ
  overlap: 75

簡潔な言語 (Go、Python)

chunking:
  size: 512    # 標準サイズ
  overlap: 50

非常に簡潔な言語 (Rust、Zig)

chunking:
  size: 384    # 正確な結果のために小さめ
  overlap: 40

コードベース別の推奨設定

小さな関数 (マイクロサービス)

chunking:
  size: 384    # 個別の関数をキャプチャ
  overlap: 40

大きなクラス (モノリス)

chunking:
  size: 768    # より多くのコンテキストをキャプチャ
  overlap: 100

混合コードベース

chunking:
  size: 512    # バランスの取れたデフォルト
  overlap: 50

トークンの数え方

GrepAI は概算トークン数を使用します:

• 約 4 文字 = 1 トークン (英語テキスト)
• コードは識別子と構文に基づいて異なります

例:

func calculateTotal(items []Item) float64 {
    total := 0.0
    for _, item := range items {
        total += item.Price * float64(item.Quantity)
    }
    return total
}

≈ 45 トークン

インデックスサイズへの影響

オーバーラップが大きいほど = チャンク数が増える = インデックスが大きくなる:

サイズ	オーバーラップ	10K トークンあたりのチャンク数	インデックス影響
512	0	~20	最小
512	50	~22	標準
512	100	~24	+10%
256	50	~44	+100%

検索品質への影響

チャンクが小さすぎる場合 (size: 128)

Query: "authentication middleware"

Result: "...c.AbortWithStatus(401)..."
        (フラグメント、コンテキストが不足)

ちょうど良い場合 (size: 512)

Query: "authentication middleware"

Result: "func AuthMiddleware() gin.HandlerFunc {
            return func(c *gin.Context) {
                token := c.GetHeader("Authorization")
                if token == "" {
                    c.AbortWithStatus(401)
                    return
                }
                // validate token...
            }
        }"
        (コンテキスト付きの完全な関数)

チャンクが大きすぎる場合 (size: 2048)

Query: "authentication middleware"

Result: "// Multiple unrelated functions...
        func AuthMiddleware()... (your match)
        func LoggingMiddleware()...
        func CORSMiddleware()..."
        (ノイズが多すぎる)

実験

異なる設定をテストする

1. より精密な結果を得るために小さなチャンクを試す:

chunking:
  size: 384
  overlap: 40

2. 再インデックス:

rm .grepai/index.gob
grepai watch

3. 検索でテスト:

grepai search "your query"

4. 調整して繰り返す。

結果の比較

設定を変更する前に検索結果を保存:

grepai search "authentication" > before.txt

設定を変更して再インデックス後:

grepai search "authentication" > after.txt
diff before.txt after.txt

チャンク境界

GrepAI は論理的な境界で分割しようとします:

1. 空行 (関数/クラス境界)
2. 閉じ括弧
3. ステートメント終了

つまり、実際のチャンクサイズはターゲットから若干異なる場合があります。

ベストプラクティス

1. デフォルトから始める: 512/50 はほとんどのコードベースで良好
2. コードスタイルに基づいて調整: 冗長 = 大きい、簡潔 = 小さい
3. 実際のクエリでテストする: 検索結果が何を返すかを確認
4. 変更後に再インデックス: 埋め込みを再生成する必要があります
5. オーバーラップを検討: インデックスサイズが重要でない限り 0 に設定しないでください

よくある問題

❌ 問題: 検索結果が断片化しすぎている ✅ 解決策: チャンクサイズを増やす:

chunking:
  size: 768

❌ 問題: 検索結果に無関係なコンテキストが多すぎる ✅ 解決策: チャンクサイズを減らす:

chunking:
  size: 384

❌ 問題: 結果が関数境界での関連コードを逃している ✅ 解決策: オーバーラップを増やす:

chunking:
  overlap: 100

❌ 問題: インデックスが大きすぎる ✅ 解決策:

• オーバーラップを減らす
• チャンクサイズを増やす
• さらに無視パターンを追加

出力形式

チャンキングステータス:

✅ Chunking Configuration

   Size: 512 tokens
   Overlap: 50 tokens

   Index Statistics:
   - Total files: 245
   - Total chunks: 1,234
   - Avg chunks/file: 5.0
   - Avg chunk size: 478 tokens

   Recommendations:
   - Current settings are balanced
   - Consider size: 384 for more precise results
   - Consider size: 768 for more context