个人主页 for_ever_love__ 欢迎各位大佬莅临其他栏目: 大模型开发从0到1 其他栏目: iOS项目总结大全 其他栏目: 我想学python了 其他栏目: iOS UI 文章目录增量索引实战新文档怎么做到分钟级可检索一、增量索引的三个基本操作二、变更侦测怎么知道什么变了2.1 轮询比对最通用2.2 消息驱动有事件源的场景三、增量更新的实现upsert 的正确姿势3.1 块 ID 稳定设计3.2 删旧查新必须原子3.3 向量库的 Upsert 语义四、删除与权限同步安全红线五、完整流水线设计六、一致性级别没必要全上强一致七、监控指标八、落地检查清单九、小结增量索引实战新文档怎么做到分钟级可检索“合同昨天就存进系统了为什么今天问它还说不知道”——RAG 系统上线后最高频的用户抱怨。全量重建索引几十万文档重新 embedding一次几小时不可能每天做不管它知识库就永远是几天前的快照。增量索引要解决的就是这个矛盾新文档/变更文档快速进索引旧索引不受扰动删除要同步生效。这篇文章讲增量索引的完整机制变更侦测、局部更新、删除同步、一致性保证以及一套可落地的流水线。一、增量索引的三个基本操作先把增量拆开——它从来不是一个操作是三个新增新文档 → 解析 → 切块 → embedding → 入库。最简单也是 90% 的日常流量更新文档内容变了 → 旧的块要删、新的块要加。比新增难一个量级——找旧块、删干净、加新的中间状态要可控删除文档下架/权限收回 → 索引里的块要消失且不能残留——漏删一条就是安全事故离职员工合同还在被检索。三个操作的正确性要求不同新增可以最终一致慢几分钟没事更新和删除必须可追踪、可回滚、无残留。二、变更侦测怎么知道什么变了2.1 轮询比对最通用定时任务扫描文档源对象存储、CMS、数据库和本地记录的已处理清单比对# 已处理清单doc_id → {version, etag, processed_at}processedload_state()fordocinscan_source():# 定期全扫或按 mtime 增量扫key(doc.id,doc.version)# version/etag 由源给出ifprocessed.get(doc.id)!key:enqueue(upsert,doc)fordoc_idinset(processed)-set(doc.idfordocinscan_source()):enqueue(delete,doc_id)# 源里没了的 删除关键字段version/etag源文件的版本标识必须有——不能只比 mtime批量复制会全刷 mtime造成无意义全量更新。对象存储的 etagMD5、CMS 的 version 字段、数据库的 updated_at 都行。删除侦测的坑全扫才能发现删除——如果源支持增量列举只列变更删除事件容易漏。没有删除事件的源就必须全量比对 ID 集合这是成本换正确性。2.2 消息驱动有事件源的场景Confluence webhook、Kafka 消息、S3 事件通知——源系统有事件推送比轮询实时秒级 vs 分钟级且省扫描成本。适合自研系统发布/更新文章时主动发消息。混合架构最务实消息驱动做主链路快定时轮询兜底防消息丢失的删除侦测。三、增量更新的实现upsert 的正确姿势单个文档的 upsert 流程新文档进来 ├─ 1. 内容哈希hash(doc 正文) → 和已记录的比没变直接跳过幂等 ├─ 2. 解析 → 清洗 → 切块 → 生成块级 ID hash(doc_id chunk_index chunk_text) ├─ 3. 删旧删除该 doc_id 的所有旧块按 doc_id 前缀删 / 按 where 过滤删 ├─ 4. 插新新块批量入库 └─ 5. 记录状态doc_id → version/etag/块数/chunk_ids3.1 块 ID 稳定设计块 ID 用hash(doc_id chunk_index chunk_hash)生成有两个好处内容没变的块 ID 不变去重、后续可做细粒度 diff重新解析后一致幂等重跑不产生垃圾块。3.2 删旧查新必须原子删除旧块和插入新块之间有窗口检索恰好发生在这个窗口可能命中半新半旧的状态。两种处理简单场景容忍短暂不一致先删后插窗口几十毫秒用户无感严格场景新块用新 doc_version 写入同一 doc_id 下并存 old/new 两组块写完后原子切换生效版本标记再异步删旧块——这就是小型的版本化索引下一篇 rg5-index-version 展开。3.3 向量库的 Upsert 语义主流向量库都支持按 ID upsert相同 ID 覆盖写Qdrantupsert、Milvusupsert、Weaviatemerge。用 upsert 而非 insert——先 insert 后 delete 的写法在失败时会留孤儿块。按文档删除要高效向量库按 ID 删是点删删一篇文档的 50 个 chunk 50 次调用。优化metadata 里带doc_id用过滤删除一次清完delete where doc_id XQdrant/Milvus 2.3 都支持过滤删除。四、删除与权限同步安全红线删除是最容易被做漏的操作漏一片就是合规事故。要点删除是全链路传播文档从 CMS 消失 → 索引删块 → 图谱删实体带血缘来源的边清理→ 缓存清除该文档的摘要/embedding 缓存→ 引用它的缓存失效。漏一环删了也白删权限变更等同删除文档权限从全员可见改成部门可见索引里 ACL 元数据要更新——ACL 元数据延迟 越权可见窗口删除要可验证删完跑一次按 doc_id 查存量断言残留数必须为 0不为 0 报警软删缓冲正式删前标记deleted_at24 小时缓冲期源系统误删可回滚缓冲期后物理删——防手滑防误操作传播。五、完整流水线设计文档源CMS/对象存储/DB │ ├─ 事件流webhook/MQ─┐ └─ 定时轮询兜底删侦测┘ ↓ 变更队列upsert/delete按 doc_id 保序 ↓ 处理器 ├─ upsert: hash 去重 → 解析 → 切块 → embedding → upsert 入库 ├─ delete: 过滤删除 缓存清除 断言残留为 0 └─ 每步 checkpoint 落库 ↓ 状态库doc_id → version/块数/状态 ↓ 监控队列堆积、处理延迟、删除残留、解析失败率工程要点保序同一 doc_id 的 upsert 和 delete 要按时间序处理先删后加的乱序 数据丢失并发不同 doc 并行同 doc 串行per-key 队列幂等全链路用内容 hash 稳定 ID任何一步失败重跑不产生重复前篇图谱流水线的 checkpoint 设计在这里同样适用背压embedding API 限流时队列会涨监控堆积深度超阈值告警——知识库延迟 RAG 用户最先感知。六、一致性级别没必要全上强一致不同业务对延迟的容忍度不同别过度设计业务要求方案客服知识库分钟级可查轮询 5 分钟 upsert 直接生效内部文档搜索小时级可接受每日批量增量金融合规库权限变更秒级消息驱动 ACL 实时刷 断言校验合同库删除必须零残留软删缓冲 全链路传播 残留断言设计原则按业务定一致性级别别为技术优雅上最终一致——反过来也一样分钟级能用的别承诺实时。七、监控指标增量索引的健康度全看这四个指标端到端延迟文档创建 → 可检索的耗时P50/P99按业务定阈值队列深度与处理速率堆积持续上涨 消费能力不足扩容 embedding 并发删除残留数每天全量校验一次已删文档 ID 抽样查索引 0 立即告警失败率解析失败、embedding 失败、写入失败按原因分类聚合作业看板。这四个指标做成 DashboardRAG 知识库从黑盒变可运维系统——索引延迟和删除残留是 RAG 独有的 SLO传统搜索系统同样要盯。八、落地检查清单变更侦测源有事件走消息无事件轮询 5~15 分钟删除侦测必须全扫比对upsert内容 hash 去重 块 ID 稳定 删除旧块与插入新块的窗口控制删除全链路传播索引/图谱/缓存、软删缓冲 24h、残留断言为 0权限变更等同 upsertACL 元数据实时更新延迟进监控流水线per-doc 保序 跨 doc 并行 幂等重跑状态库 checkpoint 落库中断可续跑四个监控指标端到端延迟、队列深度、删除残留、失败率一致性级别按业务定写进 SLO 文档。九、小结增量索引的四句话增量 新增 更新 删除三个操作更新和删除的复杂度远高于新增全链路传播索引/图谱/缓存/ACL一步不能漏侦测靠消息驱动 定时轮询兜底轮询必须比对全量 ID 集合才能发现删除内容 hash 决定幂等去重删除是安全红线软删缓冲、残留断言、权限变更等同删除——漏一条就是合规事故RAG 知识库要有自己的 SLO索引延迟、队列深度、删除残留、失败率四个指标让系统可运维。下一篇讲索引版本管理怎么做到重建索引不中断服务蓝绿切换在 RAG 里的做法。