需要配置、优化或排查 GrepAI 时，查阅…

在项目中使用 GrepAI 并需要设置、优化或校验 `.grepai/config.yaml` 配置时使用。

适用场景

解决思路

1. 在项目根目录创建或编辑 `.grepai/config.yaml`，以 `version: 1` 声明配置版本。
2. 配置 `embedder.provider`：可选 `ollama`、`openai`、`lmstudio`。
3. 根据 provider 设置 `embedder.model`：Ollama 可用 `nomic-embed-text`、`bge-m3`、`mxbai-embed-large`；OpenAI 可用 `text-embedding-3-small`、`text-embedding-3-large`；LM Studio 可用 `nomic-embed-text-v1.5`、`bge-small-en-v1.5`。
4. 设置 `embedder.endpoint`：Ollama 默认 `http://localhost:11434`，LM Studio 默认 `http://localhost:1234`，OpenAI 使用官方 API。
5. 可选设置 `embedder.dimensions`；省略时自动检测；常见值为 `nomic-embed-text: 768`、`text-embedding-3-small: 1536`、`text-embedding-3-large: 3072`。
6. 使用 OpenAI 时设置 `embedder.api_key`，支持环境变量如 `${OPENAI_API_KEY}`。
7. 使用 OpenAI 时可设置 `embedder.parallelism`（例如 `4`）以并行请求加速。
8. 配置 `store.backend`：可选 `gob`、`postgres`、`qdrant`。
9. 当 `store.backend: postgres` 时，设置 `store.postgres.dsn`，例如 `postgres://user:password@localhost:5432/grepai`。
10. 当 `store.backend: qdrant` 时，设置 `store.qdrant.endpoint`、`store.qdrant.port`（例如 `6334`）、`store.qdrant.use_tls`，可选 `store.qdrant.api_key`。
11. 配置 `chunking.size` 为每块 token 数；推荐 `256-1024`。
12. 配置 `chunking.overlap` 为块间重叠 token 数；推荐为 `size` 的 `10-20%`。
13. 配置 `watch.debounce_ms`（例如 `500`），把快速文件变更合并处理。
14. 配置 `trace.mode` 为 `fast` 或 `precise`；`fast` 使用正则、无依赖、更快，`precise` 使用 tree-sitter AST 解析、更准确。
15. 在 `trace.enabled_languages` 中列出要分析调用图的文件扩展名，例如 `.go`、`.js`、`.ts`、`.jsx`、`.tsx`、`.py`、`.php`、`.c`、`.h`、`.cpp`、`.hpp`、`.cc`、`.cxx`、`.rs`、`.zig`、`.cs`、`.pas`、`.dpr`。
16. 在 `trace.exclude_patterns` 中排除 trace 分析模式，例如 `*_test.go`、`*.spec.ts`、`*.test.js`。
17. 配置 `search.boost.enabled`（例如 `true`）启用搜索得分加权。
18. 在 `search.boost.penalties` 中按路径降低得分，示例：`/tests/` 使用 factor `0.5`、`_test.` 使用 factor `0.5`、`.spec.` 使用 factor `0.5`、`/docs/` 使用 factor `0.6`、`/vendor/` 使用 factor `0.3`、`/node_modules/` 使用 factor `0.3`。
19. 在 `search.boost.bonuses` 中按路径提高得分，示例：`/src/` 使用 factor `1.1`、`/lib/` 使用 factor `1.1`、`/core/` 使用 factor `1.2`、`/app/` 使用 factor `1.1`。
20. 配置混合搜索：设置 `search.hybrid.enabled`（默认 `false`），设置 `search.hybrid.k`（例如 `60`，BM25 参数）。
21. 在 `ignore` 中列出要排除索引的目录，例如 `.git`、`.grepai`、`.svn`、`.hg`、`node_modules`、`vendor`、`target`、`__pycache__`、`.pytest_cache`、`dist`、`build`、`out`、`.next`、`.nuxt`。
22. 在 `ignore` 中列出要排除索引的文件，例如 `*.min.js`、`*.min.css`、`*.bundle.js`、`*.map`、`*.lock`、`package-lock.json`、`yarn.lock`、`pnpm-lock.yaml`、`go.sum`。
23. 在 `ignore` 中排除生成文件，例如 `*.generated.*`、`*.pb.go`、`*.d.ts`。
24. 小型个人项目按以下配置：`version: 1`；`embedder.provider: ollama`、`embedder.model: nomic-embed-text`；`store.backend: gob`；`chunking.size: 512`、`chunking.overlap: 50`。
25. 大型代码库按以下配置：`version: 1`；`embedder.provider: ollama`、`embedder.model: bge-m3`、`embedder.parallelism: 4`；`store.backend: postgres` 并设置 `store.postgres.dsn`；`chunking.size: 768`、`chunking.overlap: 100`。
26. 团队环境按以下配置：`version: 1`；`embedder.provider: openai`、`embedder.model: text-embedding-3-small`、`embedder.api_key: ${OPENAI_API_KEY}`、`embedder.parallelism: 8`；`store.backend: qdrant` 并设置 `store.qdrant.endpoint: qdrant.internal.company.com`、`store.qdrant.port: 6334`、`store.qdrant.use_tls: true`。
27. 最大隐私按以下配置：`version: 1`；`embedder.provider: ollama`、`embedder.model: nomic-embed-text`、`embedder.endpoint: http://localhost:11434`；`store.backend: gob`（仅本地文件）。
28. 使用环境变量替换：在配置中写 `embedder.api_key: ${OPENAI_API_KEY}`、`store.postgres.dsn: ${DATABASE_URL}`，并在 shell 中执行 `export OPENAI_API_KEY="sk-..."`、`export DATABASE_URL="postgres://..."`。
29. 运行 `grepai status` 校验配置；若存在配置错误，命令会显示错误。
30. 遵循配置优先级：当前目录 `.grepai/config.yaml` 优先于 workspace 配置（如使用 workspaces），再次是默认值。
31. 最佳实践：从默认值/简单配置开始，之后再优化。
32. 最佳实践：根据代码风格调整 chunking，啰嗦代码使用更大 chunk。
33. 最佳实践：使用 boosting，惩罚 test/vendor，提升 src/lib。
34. 最佳实践：用环境变量保存 API key，绝不提交到仓库。
35. 最佳实践：排除噪声，忽略生成文件和依赖。
36. 有效配置时 `grepai status` 输出包含 `✅ GrepAI Configuration Valid`，并列出 Embedder、Storage、Chunking、Trace mode、Languages、Ignore patterns、Boosting。

适用边界 · 注意事项

• 不使用 GrepAI 或没有 `.grepai/config.yaml` 的项目。
• 想配置其他代码检索或向量数据库工具而非 GrepAI 时。
• 只需要普通文本搜索、不需要代码向量索引时。