修复文档重新分块时图谱删除与新增竞态

[ZhaoWeijunX]

问题描述

文档重新分块时，关系库 Chunk 和向量数据可以正常替换，但 LightRAG 图谱可能出现以下异常：

• 旧图谱已删除，新图谱没有重新创建
• 旧图谱未删除，重新写入又因同名冲突失败
• Ragent 文档状态显示 SUCCESS，实际图谱仍然缺失或内容陈旧

该问题可以稳定归因到 LightRAG 删除接口的异步语义与 Ragent 当前“先删后建”调用方式不兼容。

当前调用链

重新分块的主要链路如下：

KnowledgeDocumentServiceImpl.executeChunk
  -> DefaultIngestionKernel.run
  -> ChunkIndexWriter.replaceDocument
  -> VectorChunkSink.replaceDocument
  -> vectorStoreService.deleteDocumentVectors
  -> GraphSyncingVectorStoreService.deleteDocumentVectors
  -> LightRagClient.deleteByDoc
  -> vectorStoreService.indexDocumentChunks
  -> GraphSyncingVectorStoreService.indexDocumentChunks
  -> LightRagClient.insertText

VectorChunkSink.replaceDocument 连续执行：

1. 删除旧文档向量及图谱
2. 写入新文档向量及图谱

这对于同步存储成立，但 LightRAG 删除并不是同步完成的。

根因分析

当前 LightRAG 删除接口：

DELETE /documents/delete_document

返回：

{
  "status": "deletion_started"
}

只表示后台删除任务已经启动。

删除期间，LightRAG 会设置：

destructive_busy=true

此时 Ragent 立即调用：

POST /documents/text

LightRAG 会返回 HTTP 409，拒绝新增文档。

当前 LightRagClient 还存在两个放大问题：

1. HTTP 非 2xx 响应只记录日志并返回 null
2. insertText、deleteByDoc 返回 void，上层无法判断操作是否真正成功

因此实际时序通常变成：

删除请求返回 deletion_started
  -> 删除仍在后台运行
  -> 立即新增
  -> 新增返回 HTTP 409
  -> 客户端吞掉失败
  -> Ragent 分块任务仍标记为 SUCCESS
  -> 后台删除完成
  -> 最终图谱缺失

如果删除时 LightRAG 正在处理其他文档，删除接口还可能返回 busy。当前代码同样没有解析该业务状态，随后新增可能因同名文档存在而失败，最终保留旧图谱。

另外，当前删除反查使用已废弃的 GET /documents，该接口最多返回 1000 条记录；文档较多时可能找不到待删除文档。

复现步骤

1. 启用 LightRAG 图谱后端和图谱检索通道
2. 上传文档并等待图谱构建完成
3. 修改文档分块参数
4. 对同一文档重新执行分块
5. 查看 LightRAG 请求日志和文档列表

可能观察到：

DELETE /documents/delete_document -> deletion_started
POST /documents/text -> HTTP 409

最终旧文档被删除，但没有新的 processed 文档。

预期行为

文档重新分块时应保证：

1. 旧图谱删除真正完成后才提交新图谱
2. 删除返回 busy 时能够等待或有限重试
3. 新增返回非 2xx 或业务失败时不能被静默视为成功
4. 图谱同步失败需要输出包含 docId、远程文档 ID 和响应状态的明确日志
5. 不影响关系库和向量库现有的主链路行为