grepai-chunking

GrepAI のチャンク分割設定

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

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

• 検索精度の最適化
• コードスタイル（冗長か簡潔か）への調整
• 検索結果のトラブルシューティング
• インデックス作成の仕組みの理解

チャンク分割とは？

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

┌─────────────────────────────────────┐
│         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      # Tokens per chunk
  overlap: 50    # Overlap between chunks

パラメーターの理解

チャンクサイズ

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

サイズ	効果
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    # Larger to capture full methods
  overlap: 75

簡潔な言語（Go、Python）

chunking:
  size: 512    # Standard size
  overlap: 50

非常に簡潔な言語（Rust、Zig）

chunking:
  size: 384    # Smaller for precise results
  overlap: 40

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

小さな関数（マイクロサービス）

chunking:
  size: 384    # Capture individual functions
  overlap: 40

大きなクラス（モノリス）

chunking:
  size: 768    # Capture more context
  overlap: 100

混在するコードベース

chunking:
  size: 512    # Balanced default
  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)..."
        (Fragment, missing context)

適切なサイズの場合（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...
            }
        }"
        (Complete function with context)

チャンクが大きすぎる場合（size: 2048）

Query: "authentication middleware"

Result: "// Multiple unrelated functions...
        func AuthMiddleware()... (your match)
        func LoggingMiddleware()...
        func CORSMiddleware()..."
        (Too much noise)

試行

さまざまな設定のテスト

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