fuzhengwei / fuzhengwei/WaLiAPI

KB 增量索引:单文档差集更新 + 内容哈希复用 embedding + 删除文档同步摘除向量

Open
#84 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
128
Forks
39
Avg merge
15h 25m
Merged PRs (30d)
44

Description

### 现状

知识库索引维护是「三全」模式,三条都会伤用户:

1. **全库重建**:任何一篇文档变更后 `retriever::build_index` 拉全库 chunk 重造 HNSW(处理流水线收尾,fire-and-forget),耗时随库规模线性恶化;
2. **全量重嵌**:文档重处理/reindex 时所有 chunk 重新调用付费 embedding 渠道,内容未变的块也照付;
3. **删除不更新索引**(核实中新发现):删除文档的两条路径(HTTP handler / Tauri 命令)只删库行,HNSW 文件中的死向量留存到下次全量重建。

另:`HnswIndex` 公开 API 只有整体 build/search/序列化,**无单点 insert/remove**——增量能力需先行开发(并非简单接线)。

### 方案

- **HnswIndex 增强**:`insert(id, doc_id, vector)` 贪心下沉找近邻、双向连边——host 邻居表满员时**替换最远邻居**(只跳过会让新节点在图中不可达);`remove(id)` 墓碑集合(检索过滤、len 扣减),物理压实只在全量 build(图内删点破坏连通性)。
- **内容哈希复用**(迁移 031 `kb_chunks.content_hash`):处理文档时按 chunk 内容 SHA-256 比对同文档现存向量,未变块直接复用、跳过渠道调用;维度不符(换过嵌入模型)或向量损坏回退重嵌。`reindex_document` 先捕获复用映射再删旧 chunk。
- **index_delta 接线**:以「库内该文档现存 chunk ↔ 索引内该文档节点」差集做增/墓碑;索引文件缺失或**旧格式**时自动回退全量 `build_index`;处理器收尾与两条删除路径均接入(删除路径 best-effort 摘除,不阻断删除)。全量 build 与三个手动重建入口(命令/HTTP/MCP)语义不变。

### 协议边界(诚实声明)

bincode 非自描述,**旧格式索引文件无法原地升级**——首次增量时自动回退一次全量重建(对用户透明,一次性成本)。

### 测试

index 单测 12 条(插入可检索、摘除不伤召回、重建压实、旧格式判定、维度/重复拒绝、序列化往返);哈希复用纯函数单测;检索层 roundtrip(增/删/整删后索引状态与检索可用性、缺失与旧格式回退全量)。

### 开放点

1. 同维度不同嵌入模型的旧向量无法通过维度判断区分(复用按维度过滤,全量重建可修复)。是否需要记录 per-chunk 嵌入模型?
2. 是否需要在 KB 设置中暴露「手动全量重建」快捷入口的 UI 提示(接口已有)?

---
对应分支:`feat/capability-c06-r1-incremental-index`(迁移 031,基于 v0.3.0——原 030 与上游 `030_request_log_policy` 撞号已重编号)。

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with HnswIndex and retriever::build_index, then trace reindex_document and the HTTP handler and Tauri deletion command. Review migration 031 and the listed index, hash-reuse, and retrieval roundtrip tests. Done means incremental insert/remove, safe hash reuse, deletion cleanup, and full-build fallback for missing or old indexes, with all tests passing.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust, tauri
Domain
backend, databases, search
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.