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

参数说明

块大小

每个块的目标 Token 数量。

大小	效果
256	更精准，上下文较少
512	平衡（默认值）
1024	上下文较多，精度较低

重叠

相邻块之间共享的 Token 数量，可保留边界处的上下文。

重叠量	效果
0	无重叠，边界处可能丢失上下文
50	标准重叠量（默认值）
100	上下文更多，索引更大

可视化

大小为 512、重叠量为 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

Token 的计算方式

GrepAI 使用近似的 Token 计数方式：

• ~4 个字符 = 1 个 Token（适用于英文文本）
• 代码的计数会因标识符和语法而异

示例：

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

≈ 45 个 Token

对索引大小的影响

重叠量越大 = 块越多 = 索引越大：

大小	重叠量	每 10K 个 Token 的块数	对索引的影响
512	0	~20	最小
512	50	~22	标准
512	100	~24	+10%
256	50	~44	+100%

对搜索质量的影响

块太小（大小：128）

Query: "authentication middleware"

Result: "...c.AbortWithStatus(401)..."
        (Fragment, missing context)

大小适中（大小：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)

块太大（大小：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