知识库文档删除后怎么同步清理向量数据

知识库删除一篇文档时，真正需要清理的不只是业务表里的原文，还包括这篇文档切出来的所有向量分块。比较稳妥的做法是：写入 Qdrant 时给每个 point 的 payload 保存稳定的 doc_id，删除时用过滤器一次匹配整篇文档，再根据一致性要求决定是否等待操作完成。不要依赖“每篇文档有连续向量 ID”这种脆弱约定。

核心链路是“业务库删除成功或进入删除状态 → Qdrant 按 doc_id 删除 points → 等待删除完成 → 让旧的异步切片任务失效”。其中 wait=false 只代表服务已接收操作，不代表旧向量已经不能被检索。

先把文档和 chunk 的关系存进 payload

一篇文档通常会被切成很多 chunk，每个 chunk 都有自己的 point ID。如果 payload 只有正文片段和来源 URL，删除时就只能先回业务库查一遍所有 chunk ID，再组装删除请求；中间任何一次分页、缓存或重试不完整，都可能留下孤儿向量。

写入时可以把关系设计成下面这样。doc_id 是业务文档的稳定标识，不要使用会随重新切片而变化的数组下标。

payload = {
    "doc_id": "manual-0148",       # 关联业务库中的唯一文档
    "doc_version": 7,               # 防止旧切片任务覆盖新版本
    "chunk_no": 3,                  # 只用于定位分块，不作为删除依据
    "source": "产品使用手册"
}

用 filter 一次删除文档对应的全部 points

Qdrant 的删除 points 接口支持按 ID 列表删除，也支持用过滤器选择 points。对知识库文档来说，按 payload 中的 doc_id 过滤更适合重切片、补写和重试场景，因为它表达的是业务边界，而不是某一次索引任务产生的临时 ID。

curl -X POST "http://localhost:6333/collections/kb_chunks/points/delete?wait=true&ordering=strong" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "must": [
        {
          "key": "doc_id",
          "match": {"value": "manual-0148"}
        }
      ]
    }
  }'  # 等待删除完成，再把结果返回给上层服务

如果应用已经可靠保存了 point ID，也可以用 {"points":[...]} 精确删除；但这份 ID 清单必须和文档生命周期一起维护。采用过滤器时，建议为常用的 doc_id 建立 payload 索引，并在服务端记录文档删除请求的幂等键，避免重复点击产生难以追踪的并发操作。

为什么接口成功后还可能搜到旧内容

Qdrant 的点修改操作会先写入日志，再在后台完成处理。未显式等待时，客户端可能只收到 status: acknowledged 和 operation_id；这表示服务接受了操作，不等价于查询侧已经看不到旧 point。需要在删除后马上执行检索、或要把删除结果作为业务事务的下一步时，应显式使用 wait=true。

另一个常见误区是把删除和重建当成两个互不相关的请求：删除请求刚完成，队列里几分钟前启动的旧解析任务又把旧 chunk upsert 回来。建议删除或更新文档时生成新的版本号，写入前先检查任务携带的版本仍是当前版本；更严格的场景可以在业务库保留 tombstone，让消费任务看到删除标记后直接丢弃。

把删除流程做成可重试的业务动作

生产环境不要把“删业务记录”和“删向量”藏在一个没有状态的请求里。可以给文档增加 deleting 或 deleted 状态，保存删除请求 ID；后台任务按请求 ID 调用 Qdrant，成功后再把状态推进到最终结果。重复执行同一个过滤删除通常比维护一份过期 ID 列表更容易做到幂等，但仍要保留日志和超时重试上限。

• 删除前：冻结该文档的新版本写入，或把删除时间戳写入任务上下文。
• 删除中：按 doc_id 过滤删除，记录 Qdrant 返回的操作状态。
• 删除后：需要立即检索时等待完成；异步任务发现版本过期就不再 upsert。
• 恢复文档：生成新的版本号，重新切片并写入，避免复用旧任务的消息。

常见问题

只删除业务数据库记录，向量库会自动同步吗？

不会。Qdrant 不知道你的业务表删除了哪篇文档，必须由应用显式调用删除 points 或删除 payload 的接口。

应该按 chunk ID 删除还是按 doc_id 删除？

如果目标是清理整篇文档，优先按 doc_id 过滤；只有在 point ID 清单可靠、规模明确且删除边界不是整篇文档时，才更适合按 ID 列表处理。

wait=true 能解决所有旧答案问题吗？

不能。它只解决本次 Qdrant 删除操作的完成等待；如果旧的异步切片任务随后又写入，仍然会出现旧内容，所以还需要版本检查或 tombstone。

总结

知识库删除的关键不是记住一批向量 ID，而是把文档生命周期映射到可过滤的 payload。用稳定 doc_id 执行删除，用 wait=true 明确完成边界，再用版本号或删除标记约束并发重建任务，才能让业务库、向量库和检索结果保持同一套删除语义。