84 lines
2.3 KiB
Markdown
84 lines
2.3 KiB
Markdown
# 本地 RAG
|
||
|
||
本目录提供项目文档的本地 RAG 索引脚本，主要供 Agent 在执行任务前后检索项目上下文使用。它不是新的人工阅读入口；开发者仍按 `AGENTS.md`、`docs/README.md` 和 `docs/project-memory/` 阅读项目文档。
|
||
|
||
项目默认不安装 RAG 运行时依赖，也不把 LanceDB、Transformers.js 或本地模型写入根 `package.json`。
|
||
|
||
## 运行时依赖
|
||
|
||
RAG 运行时依赖安装在 gitignored 的 `.rag/runtime/`，模型缓存和向量库也都在 `.rag/` 下。
|
||
|
||
Agent 需要启用 RAG 检索时，应先询问用户是否安装本地依赖。用户确认后执行：
|
||
|
||
```bash
|
||
mkdir -p .rag/runtime
|
||
npm init -y --prefix .rag/runtime
|
||
npm install --prefix .rag/runtime @lancedb/lancedb@0.30.0 @huggingface/transformers@4.2.0
|
||
```
|
||
|
||
不要把这些依赖加入根 `package.json`。
|
||
|
||
## 索引
|
||
|
||
首次运行会下载本地 embedding 模型到 `.rag/models/`。默认模型为 `Xenova/multilingual-e5-small`，适合中英文混合文档。
|
||
|
||
```bash
|
||
npm run rag:index
|
||
```
|
||
|
||
小样本 smoke：
|
||
|
||
```bash
|
||
npm run rag:index -- --limit-files 3
|
||
```
|
||
|
||
只查看分片，不加载模型：
|
||
|
||
```bash
|
||
npm run rag:index -- --limit-files 3 --dry-run
|
||
```
|
||
|
||
## 搜索
|
||
|
||
默认输出 Agent 上下文包，包含来源、分数、候选上下文和使用规则：
|
||
|
||
```bash
|
||
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --limit 8
|
||
```
|
||
|
||
可限制上下文包大小：
|
||
|
||
```bash
|
||
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --limit 8 --max-chars 8000
|
||
```
|
||
|
||
可输出结构化格式，便于 Agent 或其它工具解析：
|
||
|
||
```bash
|
||
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --format json
|
||
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --format jsonl
|
||
```
|
||
|
||
如只想看短摘要，可使用旧式文本结果：
|
||
|
||
```bash
|
||
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --format text
|
||
```
|
||
|
||
Agent 使用规则：
|
||
|
||
- 把 RAG 输出视为候选上下文，不直接当作最终事实。
|
||
- 需要精确改代码或文档时，仍要打开对应源文件核对。
|
||
- 来源冲突时，以当前代码和最新 `docs/` 为准。
|
||
|
||
## 索引范围
|
||
|
||
索引范围由 `scripts/rag/rag-config.json` 配置，默认包含：
|
||
|
||
- `AGENTS.md`
|
||
- `CONTEXT.md`，如果存在
|
||
- `docs/project-memory/`
|
||
- `docs/`
|
||
|
||
`.codex/` 是 Codex 工具目录，不作为项目知识库索引源。
|