用途
本技能介绍如何为 GrepAI 配置 GOB（Go Binary）本地文件存储后端。GOB 是 GrepAI 默认且最简单的存储选项，适合单开发者项目、中小型代码库、无需外部依赖的简单配置以及本地开发环境。
什么是 GOB 存储
GOB 是 Go 语言原生的二进制序列化格式。GrepAI 使用它存储向量嵌入、文件元数据和分块信息，所有内容都保存在单个本地文件中。
优势
- 简单：无需外部服务
- 快速搭建：开箱即用
- 可移植：单文件，易于备份
- 免费：无基础设施成本
- 私密：数据保留在本地
限制
- 可扩展性：不适合非常大的代码库
- 单用户：不支持并发访问
- 无法共享：不能跨机器共享索引
- 内存：搜索时需加载到 RAM
配置
默认配置：GOB 是默认后端，最小配置如下：
# .grepai/config.yaml
store:
backend: gob
显式配置：
store:
backend: gob
# Index stored in .grepai/index.gob (automatic)
存储位置
GOB 存储会在项目的 .grepai/ 目录中创建文件：
.grepai/
├── config.yaml # Configuration
├── index.gob # Vector embeddings
└── symbols.gob # Symbol index for trace
文件大小
.grepai/index.gob 的大致大小：
- 小型：100 个文件、500 个分块，约 5 MB
- 中型：1,000 个文件、5,000 个分块，约 50 MB
- 大型：10,000 个文件、50,000 个分块，约 500 MB
操作
创建索引：
# Initialize project
grepai init
# Start indexing (creates index.gob)
grepai watch
查看索引状态：
grepai status
# Output:
# Index: .grepai/index.gob
# Files: 245
# Chunks: 1,234
# Size: 12.5 MB
# Last updated: 2025-01-28 10:30:00
备份索引：
# Simple file copy
cp .grepai/index.gob .grepai/index.gob.backup
清理索引：
# Delete and re-index
rm .grepai/index.gob
grepai watch
迁移到新机器：
# Copy entire .grepai directory
cp -r .grepai /path/to/new/location/
# Note: Only works if using same embedding model
性能考量
内存使用：GOB 在搜索时会将整个索引加载到 RAM：
- 10 MB 索引约占用 20 MB RAM
- 50 MB 索引约占用 100 MB RAM
- 500 MB 索引约占用 1 GB RAM
搜索速度：
- 小型（100 个文件）：<50ms
- 中型（1K 个文件）：<200ms
- 大型（10K 个文件）：<1s
何时升级
当出现以下情况时，考虑迁移到 PostgreSQL 或 Qdrant：
- 索引超过 1 GB
- 需要并发访问
- 希望在团队间共享索引
- 代码库有 50K+ 个文件
.gitignore 配置
将 .grepai/ 添加到 .gitignore：
# GrepAI (machine-specific index)
.grepai/
原因：索引是机器特定的，因为它包含二进制嵌入、与所使用的嵌入模型绑定，每台机器应生成自己的索引。
共享索引（不推荐）
虽然可以复制索引文件，但不推荐，因为必须使用完全相同的嵌入模型、文件路径是绝对路径、不同机器可能有不同的代码版本。更好的做法是每位开发者运行自己的 grepai watch。
迁移到其他后端
迁移到 PostgreSQL：
store:
backend: postgres
postgres:
dsn: postgres://user:pass@localhost:5432/grepai
rm .grepai/index.gob
grepai watch
迁移到 Qdrant：
store:
backend: qdrant
qdrant:
endpoint: localhost
port: 6334
rm .grepai/index.gob
grepai watch
常见问题
- 索引文件过大：添加更多忽略规则，或迁移到 PostgreSQL/Qdrant
- 大型代码库搜索缓慢：迁移到 Qdrant 以获得更好性能
- 索引损坏：删除并重建：
rm .grepai/index.gob .grepai/symbols.gob
grepai watch
- 出现 "Index not found" 错误：运行 grepai watch 创建索引
最佳实践
- 用于小型/中型项目：最多约 10K 个文件
- 添加到 .gitignore：不要提交索引
- 重大变更前备份：实验前复制 index.gob
- 模型变更后重建索引：如果更改了嵌入模型
- 监控文件大小：索引超过 1GB 时迁移
输出格式
GOB 存储状态示例：
✅ GOB Storage Configured
Backend: GOB (local file)
Index: .grepai/index.gob
Size: 12.5 MB
Contents:
- Files: 245
- Chunks: 1,234
- Vectors: 1,234 × 768 dimensions
Performance:
- Search latency: <100ms
- Memory usage: ~25 MB