244 lines
9.3 KiB
Markdown
244 lines
9.3 KiB
Markdown
# Knowledge Core 与 Retrieval Core 开发说明
|
||
|
||
> 本文档用于团队开发和模块联调，记录 Knowledge Core / Retrieval Core 已经落地的
|
||
> 模块边界、数据模型、接口与使用方式，对应分工表中的杨星萱。
|
||
|
||
> 更新日期：2026-09-02。第一阶段 Knowledge/Retrieval 主链路已经完成，并已接入 Agent Tool Registry；完整后端回归基线为 136 项测试通过。
|
||
|
||
## 当前实现
|
||
|
||
当前已经建立第一条可运行的检索链路：
|
||
|
||
```text
|
||
Markdown Vault
|
||
→ Markdown Parser（Block 切分 / heading_path / offset）
|
||
→ SQLite（notes / blocks / FTS5）+ sqlite-vec（vec_blocks）
|
||
→ FTS5(BM25) + Vector(cosine) 双路召回
|
||
→ RRF 融合 → Reranker 精排 → Metadata Filter → 分页
|
||
→ Citation + Snippet
|
||
```
|
||
|
||
对应代码：
|
||
|
||
```text
|
||
backend/app/
|
||
├── constants.py EMBEDDING_DIM = 128
|
||
├── config.py Settings（data_dir / db_path / vault_path）
|
||
├── textutils.py 分词、FTS 查询串、摘要片段
|
||
├── repository.py notes / blocks / blocks_fts 读写（领域记录层）
|
||
├── database/
|
||
│ ├── db.py SQLite 连接 + 事务 + 加载 sqlite-vec
|
||
│ └── migrations.py 轻量迁移（建 notes / blocks / blocks_fts / vec_blocks）
|
||
├── knowledge/
|
||
│ └── parser.py Markdown → ParsedNote / NoteBlock
|
||
├── retrieval/
|
||
│ ├── embedding.py EmbeddingProvider 接口 + HashEmbeddingProvider
|
||
│ ├── reranker.py RerankerProvider 接口 + LexicalReranker
|
||
│ ├── vectorstore.py VectorStore 接口 + SqliteVecStore
|
||
│ ├── hybrid.py RRF 融合、分数归一化
|
||
│ └── engine.py RetrievalEngine（编排检索全流程）
|
||
└── services/
|
||
├── note_service.py Note CRUD + 索引编排
|
||
└── index_service.py 全量重建、索引状态、任务查询
|
||
```
|
||
|
||
Router（`backend/app/routes.py`）只负责 HTTP 与错误转换；`/api/notes`、`/api/search`、
|
||
`/api/index/*` 已接入上述服务，其余端点仍由对应模块负责。
|
||
|
||
## 模块边界
|
||
|
||
本模块负责（杨星萱）：
|
||
|
||
- Markdown Vault、Note / NoteBlock 数据模型与解析；
|
||
- SQLite 元数据、FTS5 全文检索、sqlite-vec 向量检索；
|
||
- Embedding、Hybrid RAG、RRF、Reranker、Metadata Filter；
|
||
- Citation 与笔记定位；
|
||
- 检索测试数据。
|
||
|
||
以下内容保持接口，不在本模块实现：
|
||
|
||
- Agent Runtime、Tool Registry、Permission：由 Agent Core 提供；
|
||
- Provider Adapter、多模型协议：由 Model Core 提供；
|
||
- Skill / Plugin 生命周期：由 Extension Core 提供；
|
||
- 文件系统与 API Key 明文读取：由 Rust Host 提供。
|
||
|
||
## 数据模型与稳定 ID
|
||
|
||
- 笔记元数据存 `notes` 表；正文切成 Block 存 `blocks` 表；`blocks_fts` 是 FTS5 虚拟表；
|
||
`vec_blocks` 是 sqlite-vec 的 `vec0` 虚拟表。
|
||
- 稳定 ID（内容/路径不变则 ID 不变）：
|
||
|
||
```text
|
||
note_id = "note_" + sha256(rel_path)[:16]
|
||
block_id = "blk_" + sha256(note_id | heading_path | content)[:16]
|
||
citation_id = "cit_" + block_id
|
||
```
|
||
|
||
> 注意：`note_id` 是稳定业务 ID；移动接口会保留原 ID，文件路径不能代替业务实体 ID。
|
||
|
||
每个 Block 记录 `heading_path`（章节路径）、`start_offset` / `end_offset`（相对原文的
|
||
字符偏移，用于前端跳转高亮）、`content_hash`、`token_count`。
|
||
|
||
## 分层依赖
|
||
|
||
按团队约定，依赖方向为：
|
||
|
||
```text
|
||
Router（HTTP/错误转换）
|
||
→ Service（note_service / index_service 编排）
|
||
→ Repository（notes/blocks/FTS5 访问） ← 只在此层访问 SQLite
|
||
→ Retrieval Infra（embedding/reranker/vectorstore） ← vec0 只在 vectorstore 层访问
|
||
```
|
||
|
||
- 检索 Executor 调用 `RetrievalEngine`，不直接拼接 FTS5 或 sqlite-vec SQL；
|
||
- 向量实现只在 `retrieval/vectorstore.py`；DB 访问只在 `repository.py`。
|
||
|
||
## 分词与中文检索
|
||
|
||
FTS5 默认 `unicode61` 不切分中文，因此统一预分词：ASCII 单词 + CJK 单字 + CJK 相邻双字。
|
||
写入与查询走同一套拆分（`textutils.segment` / `textutils.match_query`），实现中文子串/词级召回。
|
||
|
||
## Embedding / Reranker（轻量实现，接口可替换）
|
||
|
||
当前是「统一接口 + 轻量实现」，后续接入真实模型时替换实例即可，不改变上层调用：
|
||
|
||
- `EmbeddingProvider`（`embed_documents` / `embed_query`）→ `HashEmbeddingProvider`：
|
||
确定性特征哈希 + L2 归一化，`dim = 128`，`model_id = "hash-v1"`。
|
||
- `RerankerProvider`（`rerank`）→ `LexicalReranker`：分数归一化 + 词重叠加权，
|
||
`model_id = "lexical-v1"`。
|
||
- `VectorStore`（`upsert` / `delete` / `search` / `clear`）→ `SqliteVecStore`：
|
||
sqlite-vec `vec0`，相似度取余弦 `score = 1 - distance² / 2`。
|
||
|
||
## 检索流程
|
||
|
||
`RetrievalEngine.search(request)`：
|
||
|
||
1. 按 `mode` 收集候选：`fts` / `vector` 各取 Top `CANDIDATE_POOL = 50`；
|
||
2. `hybrid` 用 RRF（`k = 60`）融合两路排序；
|
||
3. Metadata Filter：`folders` / `note_ids` / `tags` / 时间范围；
|
||
4. `hybrid` 再经 Reranker 精排，其余模式按分数排序；
|
||
5. 分数归一化 → 分页 → 组装 `Citation` 与 `Snippet`。
|
||
|
||
模块级单例 `engine = RetrievalEngine(HashEmbeddingProvider(), LexicalReranker(), SqliteVecStore())`，
|
||
检索入口统一为 `engine.search(request)`。
|
||
|
||
## 接口清单
|
||
|
||
### Note
|
||
|
||
```text
|
||
GET /api/notes?limit=&offset=&folder=&tag=
|
||
POST /api/notes
|
||
GET /api/notes/{note_id}
|
||
PATCH /api/notes/{note_id}
|
||
DELETE /api/notes/{note_id}
|
||
POST /api/notes/{note_id}/move （已实现，保留 note_id）
|
||
```
|
||
|
||
创建笔记：
|
||
|
||
```json
|
||
POST /api/notes
|
||
{"title": "Python 基础", "markdown": "# 变量\n\nPython 是动态类型语言。", "folder": "编程", "tags": ["python"]}
|
||
```
|
||
|
||
### Search
|
||
|
||
```text
|
||
POST /api/search
|
||
```
|
||
|
||
```json
|
||
{"query": "向量数据库", "mode": "hybrid", "limit": 10}
|
||
```
|
||
|
||
`mode` 取 `fts` / `vector` / `hybrid`；可选 `folders` / `note_ids` / `tags` / 时间范围 /
|
||
`include_snippet`。结果项含 `score`、`snippet` 与 `citation`（`citation_id`、`file_path`、
|
||
`heading_path`、`start_offset`、`end_offset`）。
|
||
|
||
### Index
|
||
|
||
```text
|
||
GET /api/index/status
|
||
POST /api/index/rebuild
|
||
GET /api/index/jobs/{job_id}
|
||
```
|
||
|
||
重建（MVP 同步执行，直接返回 `completed`）：
|
||
|
||
```json
|
||
POST /api/index/rebuild
|
||
{"scope": "all"}
|
||
```
|
||
|
||
## 检索测试数据
|
||
|
||
样例 Vault 位于 `backend/data/vault/`，覆盖中英文、多级标题、frontmatter、子目录与不同 tags：
|
||
|
||
```text
|
||
项目说明.md
|
||
编程/Python 基础语法.md
|
||
编程/向量数据库与相似度检索.md
|
||
产品/RAG 检索增强与引用定位.md
|
||
日记/2026-08-27 周会.md
|
||
```
|
||
|
||
示例查询：
|
||
|
||
```text
|
||
POST /api/search {"query": "向量数据库", "mode": "hybrid"} → 命中《向量数据库与相似度检索》
|
||
POST /api/search {"query": "检索", "mode": "fts", "folders": ["产品"]} → 只返回 产品/ 下笔记
|
||
POST /api/search {"query": "向量", "mode": "hybrid", "tags": ["向量"]} → 按 tag 过滤
|
||
```
|
||
|
||
## 测试
|
||
|
||
```powershell
|
||
cd backend
|
||
uv run pytest -q
|
||
```
|
||
|
||
当前后端完整测试共 218 个用例通过（单元 + 端到端）。测试通过 `tests/conftest.py` 的 autouse fixture 把
|
||
数据目录/DB/Vault 重定向到临时目录，不读写真实 `backend/data`，任何本机状态下结果确定。
|
||
|
||
## 配置
|
||
|
||
```text
|
||
APP_DATA_DIR 默认 backend/data
|
||
APP_DB_PATH 默认 backend/data/app.db
|
||
APP_VAULT_PATH 默认 backend/data/vault
|
||
APP_ATTACHMENTS_PATH 默认 backend/data/attachments
|
||
```
|
||
|
||
运行期生成的 `backend/data/*.db*` 已被 `.gitignore` 忽略，vault 下的 Markdown 测试数据会提交。
|
||
|
||
## 接入约定（Agent / 其他模块）
|
||
|
||
Agent 通过注册 Tool 接入本模块，不让 Agent Runtime 直接依赖具体实现：
|
||
|
||
```text
|
||
notes.search / notes.read / notes.create / notes.update / notes.list / notes.move
|
||
rag.search
|
||
```
|
||
|
||
- 写操作 Executor 调用 `note_service`，不直接访问 SQLite；
|
||
- 检索 Executor 调用 `engine.search(request)`，不直接拼接 FTS5 或 sqlite-vec SQL。
|
||
|
||
## 当前限制与下一步
|
||
|
||
- `move` 接口已实现，移动文件后保持原 `note_id`，同时原子更新 Block、FTS 和向量索引。
|
||
- Citation 的 `start_offset` / `end_offset` 使用 UTF-16 code unit，直接兼容浏览器编辑器。
|
||
- Markdown 分块会识别 fenced code block，不会把代码中的 `#` 注释误判为标题。
|
||
- Embedding / Reranker 为轻量实现，后续替换为真实模型（接口不变）。
|
||
- 小语料下 hybrid 检索召回偏宽（向量 Top-K 覆盖全部 block），可加相关性阈值收紧。
|
||
- 重建为同步 + 全量，后续接入增量索引与异步任务队列。
|
||
- RAG Benchmark 已建立：`POST /api/benchmarks/rag/runs` 创建即返回 queued、后台 Task 执行，
|
||
通过 SSE 实时推送进度，报告含逐 Case 结果与 `total_cases` / `successful_cases` / `failed_cases` / `failure_rate`。
|
||
- Agent Benchmark 暂缓，待 Agent Runtime 完成后交付。
|
||
|
||
## 2026-09-06 实现补充
|
||
|
||
上文的 MVP 同步说明是早期基线。当前打开 Vault 和 HTTP PATCH 保存已拆分即时元数据 / FTS 与后台向量计算；手动全量重建仍等待完成。生产 Embedding 使用实际模型和隔离向量空间，HashEmbedding 仅用于测试。
|
||
|
||
后续维护以 [工作区后台索引与保存开发说明](工作区后台索引与保存开发说明.md) 的实现边界、状态和验证步骤为准。
|