25 lines
2.8 KiB
Markdown
25 lines
2.8 KiB
Markdown
# 模型隔离向量索引与增量登记
|
||
|
||
## 目标与实现
|
||
|
||
向量仍保存在本地 `app.db`，重启复用。`routed_block_vectors` 主键升级为 `(space_id, dimensions, block_id)`，同维度不同模型、同模型不同维度均独立存储。每个空间建立以模型标识和维度的 SHA-256 命名的 `vec0` 虚拟表，动态表名不包含厂商输入。
|
||
|
||
首次访问旧空间时，在事务中将已有 JSON 向量转换为归一化 float32 索引，不重新调用 Embedding 模型。随后检索由 sqlite-vec 执行精确 KNN，避免每次在 Python 中解码所有向量、计算点积。该实现是精确搜索，不是 ANN；依据归一化向量的欧氏距离换算余弦分数。参见 [sqlite-vec KNN 文档](https://alexgarcia.xyz/sqlite-vec/features/knn.html)。
|
||
|
||
覆盖检查和 KNN 使用同一事务。向量更新、删除及笔记级联删除通过触发器清理派生索引，新向量与原始向量在同一保存点写入。索引缺失或不完整仍明确失败/按已有策略回退，不混入其他模型结果。本地专用笔记按 `local_only` 元数据过滤，不同空间的结果继续使用 RRF 融合。
|
||
|
||
数据库搜索及旧空间转换在线程中运行，不阻塞异步服务事件循环。首次转换仍会占用 SQLite 写事务；超大库应进一步评估迁移耗时。新增空间保留原空间索引，暂不自动清理历史空间。
|
||
|
||
## 外部新增文件
|
||
|
||
文件树检测到新增 Markdown 后先登记元数据与全文索引，然后为每条新笔记持久化 `note_vectors_pending:<note_id>`，逐笔记在后台计算。不再因新增文件设置全库重建标记；已存在的全库待处理标记仍保留，以免跳过之前未完成的任务。
|
||
|
||
新增文件在推理期间再次变化时校验快照并重试，只同步该笔记。写入失败保留待处理标记。手动“重建全部”仍执行全库重建，正常重新打开已完成的工作区不再入队。
|
||
|
||
## 验证
|
||
|
||
- 隔离数据库运行后端全套测试：637 项通过；最终覆盖检查优化另运行检索及后台工作区回归，96 项通过。
|
||
- 新增用例验证同模型不同维度并存、重新连接复用且查询不解码向量 JSON、旧表迁移只计算查询向量，以及外部新增文件不触发全量重建。
|
||
- `backend/scripts/vector-index-benchmark.py` 使用临时数据库、固定随机种子，比较 4000 条 384 维向量的 top-20，旧新路径结果顺序一致。5 次采样中位数：Python 扫描约 1289.64 ms，sqlite-vec 约 19.67 ms；首次转换约 1329.51 ms。该结果只测向量检索，不包含查询 Embedding、重排与 HTTP 耗时，不代表端到端加速比例。
|
||
- 原始结果：[2026-09-06-sqlite-vec-search.json](performance/2026-09-06-sqlite-vec-search.json)。基准可用后端虚拟环境 Python 直接执行上述脚本，不读写用户 Vault。
|