fuzhengwei / fuzhengwei/WaLiAPI

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

Open
#79 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 its existing build/search/serialization API, then trace reindex_document, the processing finalizer, and the HTTP/Tauri deletion paths. Run the listed index, hash-reuse, and retrieval roundtrip tests; done means incremental add/remove, reuse, and fallbacks work without breaking full rebuilds.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.