尧图网站建设 
LightRAG 所有接口返回 503 recovery_required 怎么排查半提交存储与恢复顺序【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG当 LightRAG Server 的 upload / text / scan / 手动重试 / delete / clear 等所有写操作统一开始返回 HTTP 503而查询类接口不受影响时通常是管道抬起了recovery_required围栏fence某些故障会让工作区处于继续跑下去只能靠猜的状态管道宁可拒绝一切写入也不猜测直到操作者显式解除围栏。本文给出排查围栏原因、按原因选择恢复路径、以及修复半提交存储的完整操作顺序。该机制的权威说明在 File Processing Pipeline 文档 §8.5两个离线修复工具的使用说明分别在 README_KG_INTEGRITY_REPAIR.md 和 README_REBUILD_VDB.md。先确认这就是围栏而不是别的限流503 围栏和另外两类限流错误要区分开上传返回413 / 429是请求准入限制admission limits与管道忙闲和围栏都无关POST /documents/reprocess_failed在围栏已抬起或有 clear/delete 正在运行时也会返回 503但这是该接口自身的忙闲语义不一定是全局围栏。判断是否全局围栏看两个信号所有写接口而不只是某一个都 503且GET /documents/pipeline_status返回的recovery_required为true。第一步用 pipeline_status 读出围栏原因GET /documents/pipeline_status报告三个围栏字段recovery_required布尔值围栏是否抬起recovery_kind粗粒度原因区分下面哪一类recovery_message与 503 响应相同的文字说明部分原因还会附带阻塞文档 id 的有界样本。围栏由三种情况触发其中第 1 和第 3 种依赖跨进程死主进程检测只发生在 Linux 多 worker Gunicorn 部署下单进程 Uvicorn 随进程死亡丢失协调状态不会出现worker 在custom_chunks/delete/clear中途死亡。这些操作可能是半提交的不能简单重跑。对比processing/scan的 owner 死亡是可重跑的会被静默回收不抬围栏。手动重试的 drain 无法到达空闲。两种卡法同一批文档反复出现且状态无变化重查只会空转或 drain 永远无法推进的行——持有未完成的 custom-chunk 操作的行只有/documents/scan的回滚能解决。两种情况下重置都不会执行重试请求保持未确认状态。recovery_kind用manual_drain_stalled和manual_drain_blocked区分它们。owner 存活与否无法判定。回收某 owner 的持有需要先证明其进程确实死亡没有进程身份的持有记录永远无法证明这一点管道不做猜测围栏就是出口。第二步按 recovery_kind 选恢复路径recovery_kind / 原因操作顺序manual_drain_blockedPOST /documents/recovery/force_reset然后POST /documents/scan——scan 既回滚未完成的操作又自行执行FAILED重置不需要单独的重试调用manual_drain_stalledPOST /documents/recovery/force_reset然后排查recovery_message里点名的文档——围栏无法说明它们卡住的原因解决后重新发起POST /documents/reprocess_failedworker 死于custom_chunks/delete/clear中途不要用force_reset——按下面半提交存储修复的顺序操作force_reset 的副作用与语义POST /documents/recovery/force_reset这是一个不安全的手工覆盖——它本身不修复任何东西。除了清围栏它还会取消该工作区排队的全部手动重试请求而这是必需的只要还有排队请求/documents/scan就拒绝运行scan 自带独占的FAILED重置不能插队只清围栏会让恢复路径同样被堵住。响应中的cancelled_manual_retries报告取消数量status为reset或no_recovery_required。没有文档会丢失败文档保持FAILED由下一次重试请求或 scan 自身的重置处理。两个注意点接口要求请求体带confirm: true才执行工作区可能处于部分提交状态需先核实/修复再重置该调用是all-or-nothing如果排队请求无法被取消端点返回 503 且围栏保持抬起你可以重试完成恢复而不是让 API 报告一次实际未发生的恢复。重启服务能否替代判断标准只有一个阻塞项在内存里还是在存储里重启只清除运行时协调状态pipeline_status里的围栏与 owner 记录、ingress 里排队的重试请求这些都不落盘。写入doc_status/full_docs/ 各存储的内容原样存活。原因重启能修好吗原因owner 存活无法判定能卡住的预留记录在跨进程共享状态里重启进程组即移除且存储从未被碰过——最干净的修法manual_drain_stalled通常能围栏和排队请求随重启消失如果反复出现的活动行是死进程的PROCESSING/PARSING/ANALYZING孤儿重启后会自动重置为PENDING并在下次触发时重跑。但重启不做诊断若它们因别的原因卡在相同状态下一次/documents/reprocess_failed还会再次卡住manual_drain_blocked不能阻塞项是doc_status.metadata里的未完成 custom-chunk 日志已持久化、重启原样存活。重启只清围栏和排队请求这仍然必要——排队请求会让/scan拒绝自己的预留真正的回滚必须来自POST /documents/scanworker 死于custom_chunks/delete/clear不能半提交的是存储本身见下所以重启相当于更温和的 force_reset两者都清围栏和排队请求、都不修复任何东西只是重启额外把中断文档重置为PENDING这正是 stall 常常自愈的原因代价是停机。能安排停机就优先重启不能停机且确认存储从未被碰原因 2 和 3时才用force_reset。半提交存储修复离线工具与恢复顺序围栏本身不落盘住在pipeline_status里所以重启服务会连围栏和排队请求一起清掉。这决定了force_reset的定位原因 2 和 3 用它重置从未执行、存储未被碰过原因 1 避免用它——它只清一个标志位清掉之后所有写入包括并发上传立刻对可能半提交的存储恢复运行。下面两个离线工具都要求服务已停止而停止本身就会移除围栏所以force_reset在此路径中根本不出现。两个离线工具的能力边界工具数据真源与修复内容修不了什么代价python -m lightrag.tools.kg_integrity_repair沿 graph → chunksource_id→text_chunks→full_doc_id重建缺失或不可用的full_entities/full_relations锚点行可为确实不拥有任何东西的文档写空锚点行graph↔VDB 漂移、doc_status/full_docs本身、custom-chunk 日志、围栏本身从不调用 LLM 或 embedder——基本免费lightrag-rebuild-vdb丢弃并重建entities_vdb/relationships_vdb来自 graph和chunks_vdb来自text_chunks还能清除反向孤儿向量库有、graph 里没有增量修复做不到锚点行、doc_status、graph 本身是否正确、围栏本身全量重新 embedding——真实金钱成本两个顺序陷阱搞反会把可修数据变成不可修kg_integrity_repair必须在任何进一步删除之前运行。它只能从幸存的chunk 溯源重建锚点如果半截的 delete 已经删掉了text_chunks行这些贡献就变成不可恢复的孤儿工具只能报告、永远不会自行修改。先跑报告模式不带--apply没有任何理由不跑。lightrag-rebuild-vdb必须最后运行。它以 graph 和text_chunks为真源半截 delete 本应删掉的 graph 对象会被忠实地重新 embed 回向量库。它保证向量与 graph一致不保证 graph正确。所以先解决 graph 侧再考虑重建向量。原因 1 的完整操作顺序停止服务围栏随之消失——不要碰force_reset。先跑报告python -m lightrag.tools.kg_integrity_repair --verbose查看锚点缺口以及已经救不回来的不可恢复孤儿。仅在确实有缺口时才加--apply。启动服务重跑未完成的操作——整文档 purge 有日志、会从已完成的阶段之后续跑clear直接重跑custom_chunks的回滚由POST /documents/scan触发。稳定后如果怀疑 graph↔VDB 漂移再次停止服务并运行lightrag-rebuild-vdb先用它的只读一致性检查菜单选项 1判断这笔 embedding 成本是否值得付。两个工具的硬性前提服务必须停止、工作区必须空闲并发写入会让它们读到一个移动的目标lightrag-rebuild-vdb必须与服务使用同一份.env否则重建的向量落在另一个 embedding 空间。验证恢复完成GET /documents/pipeline_status中recovery_required回到falserecovery_kind/recovery_message随之为空原本 503 的写接口上传、/documents/scan、删除等不再返回 503能正常受理走 offline 路径时kg_integrity_repair --apply的报告字段repaired_docs列出实际写入的锚点修复missing_entity_anchors/missing_relation_anchors是诊断项修复后不会清空lightrag-rebuild-vdb的一致性检查通过。限制与边界围栏只影响写操作查询接口不受管道准入约束、不会被 503但在 clear/delete 期间查询结果不保证一致可能看到空结果、部分结果或存储错误。503 围栏机制中的worker 死亡中途与owner 存活无法判定两类只在Linux 多 worker Gunicorn下出现单进程 Uvicorn 或 Windows 不会出现这两类。若删除文档时收到的是 409缺少 recovery anchor而非 503那是另一条路径原样重试会被再次拒绝需要先运行audit_kg_integrity(..., applyTrue)即上面的kg_integrity_repair --apply。【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 LightRAG 所有接口返回 503 recovery_required 怎么排查半提交存储与恢复顺序
LightRAG 所有接口返回 503 recovery_required 怎么排查半提交存储与恢复顺序【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG当 LightRAG Server 的 upload / text / scan / 手动重试 / delete / clear 等所有写操作统一开始返回 HTTP 503而查询类接口不受影响时通常是管道抬起了recovery_required围栏fence某些故障会让工作区处于继续跑下去只能靠猜的状态管道宁可拒绝一切写入也不猜测直到操作者显式解除围栏。本文给出排查围栏原因、按原因选择恢复路径、以及修复半提交存储的完整操作顺序。该机制的权威说明在 File Processing Pipeline 文档 §8.5两个离线修复工具的使用说明分别在 README_KG_INTEGRITY_REPAIR.md 和 README_REBUILD_VDB.md。先确认这就是围栏而不是别的限流503 围栏和另外两类限流错误要区分开上传返回413 / 429是请求准入限制admission limits与管道忙闲和围栏都无关POST /documents/reprocess_failed在围栏已抬起或有 clear/delete 正在运行时也会返回 503但这是该接口自身的忙闲语义不一定是全局围栏。判断是否全局围栏看两个信号所有写接口而不只是某一个都 503且GET /documents/pipeline_status返回的recovery_required为true。第一步用 pipeline_status 读出围栏原因GET /documents/pipeline_status报告三个围栏字段recovery_required布尔值围栏是否抬起recovery_kind粗粒度原因区分下面哪一类recovery_message与 503 响应相同的文字说明部分原因还会附带阻塞文档 id 的有界样本。围栏由三种情况触发其中第 1 和第 3 种依赖跨进程死主进程检测只发生在 Linux 多 worker Gunicorn 部署下单进程 Uvicorn 随进程死亡丢失协调状态不会出现worker 在custom_chunks/delete/clear中途死亡。这些操作可能是半提交的不能简单重跑。对比processing/scan的 owner 死亡是可重跑的会被静默回收不抬围栏。手动重试的 drain 无法到达空闲。两种卡法同一批文档反复出现且状态无变化重查只会空转或 drain 永远无法推进的行——持有未完成的 custom-chunk 操作的行只有/documents/scan的回滚能解决。两种情况下重置都不会执行重试请求保持未确认状态。recovery_kind用manual_drain_stalled和manual_drain_blocked区分它们。owner 存活与否无法判定。回收某 owner 的持有需要先证明其进程确实死亡没有进程身份的持有记录永远无法证明这一点管道不做猜测围栏就是出口。第二步按 recovery_kind 选恢复路径recovery_kind / 原因操作顺序manual_drain_blockedPOST /documents/recovery/force_reset然后POST /documents/scan——scan 既回滚未完成的操作又自行执行FAILED重置不需要单独的重试调用manual_drain_stalledPOST /documents/recovery/force_reset然后排查recovery_message里点名的文档——围栏无法说明它们卡住的原因解决后重新发起POST /documents/reprocess_failedworker 死于custom_chunks/delete/clear中途不要用force_reset——按下面半提交存储修复的顺序操作force_reset 的副作用与语义POST /documents/recovery/force_reset这是一个不安全的手工覆盖——它本身不修复任何东西。除了清围栏它还会取消该工作区排队的全部手动重试请求而这是必需的只要还有排队请求/documents/scan就拒绝运行scan 自带独占的FAILED重置不能插队只清围栏会让恢复路径同样被堵住。响应中的cancelled_manual_retries报告取消数量status为reset或no_recovery_required。没有文档会丢失败文档保持FAILED由下一次重试请求或 scan 自身的重置处理。两个注意点接口要求请求体带confirm: true才执行工作区可能处于部分提交状态需先核实/修复再重置该调用是all-or-nothing如果排队请求无法被取消端点返回 503 且围栏保持抬起你可以重试完成恢复而不是让 API 报告一次实际未发生的恢复。重启服务能否替代判断标准只有一个阻塞项在内存里还是在存储里重启只清除运行时协调状态pipeline_status里的围栏与 owner 记录、ingress 里排队的重试请求这些都不落盘。写入doc_status/full_docs/ 各存储的内容原样存活。原因重启能修好吗原因owner 存活无法判定能卡住的预留记录在跨进程共享状态里重启进程组即移除且存储从未被碰过——最干净的修法manual_drain_stalled通常能围栏和排队请求随重启消失如果反复出现的活动行是死进程的PROCESSING/PARSING/ANALYZING孤儿重启后会自动重置为PENDING并在下次触发时重跑。但重启不做诊断若它们因别的原因卡在相同状态下一次/documents/reprocess_failed还会再次卡住manual_drain_blocked不能阻塞项是doc_status.metadata里的未完成 custom-chunk 日志已持久化、重启原样存活。重启只清围栏和排队请求这仍然必要——排队请求会让/scan拒绝自己的预留真正的回滚必须来自POST /documents/scanworker 死于custom_chunks/delete/clear不能半提交的是存储本身见下所以重启相当于更温和的 force_reset两者都清围栏和排队请求、都不修复任何东西只是重启额外把中断文档重置为PENDING这正是 stall 常常自愈的原因代价是停机。能安排停机就优先重启不能停机且确认存储从未被碰原因 2 和 3时才用force_reset。半提交存储修复离线工具与恢复顺序围栏本身不落盘住在pipeline_status里所以重启服务会连围栏和排队请求一起清掉。这决定了force_reset的定位原因 2 和 3 用它重置从未执行、存储未被碰过原因 1 避免用它——它只清一个标志位清掉之后所有写入包括并发上传立刻对可能半提交的存储恢复运行。下面两个离线工具都要求服务已停止而停止本身就会移除围栏所以force_reset在此路径中根本不出现。两个离线工具的能力边界工具数据真源与修复内容修不了什么代价python -m lightrag.tools.kg_integrity_repair沿 graph → chunksource_id→text_chunks→full_doc_id重建缺失或不可用的full_entities/full_relations锚点行可为确实不拥有任何东西的文档写空锚点行graph↔VDB 漂移、doc_status/full_docs本身、custom-chunk 日志、围栏本身从不调用 LLM 或 embedder——基本免费lightrag-rebuild-vdb丢弃并重建entities_vdb/relationships_vdb来自 graph和chunks_vdb来自text_chunks还能清除反向孤儿向量库有、graph 里没有增量修复做不到锚点行、doc_status、graph 本身是否正确、围栏本身全量重新 embedding——真实金钱成本两个顺序陷阱搞反会把可修数据变成不可修kg_integrity_repair必须在任何进一步删除之前运行。它只能从幸存的chunk 溯源重建锚点如果半截的 delete 已经删掉了text_chunks行这些贡献就变成不可恢复的孤儿工具只能报告、永远不会自行修改。先跑报告模式不带--apply没有任何理由不跑。lightrag-rebuild-vdb必须最后运行。它以 graph 和text_chunks为真源半截 delete 本应删掉的 graph 对象会被忠实地重新 embed 回向量库。它保证向量与 graph一致不保证 graph正确。所以先解决 graph 侧再考虑重建向量。原因 1 的完整操作顺序停止服务围栏随之消失——不要碰force_reset。先跑报告python -m lightrag.tools.kg_integrity_repair --verbose查看锚点缺口以及已经救不回来的不可恢复孤儿。仅在确实有缺口时才加--apply。启动服务重跑未完成的操作——整文档 purge 有日志、会从已完成的阶段之后续跑clear直接重跑custom_chunks的回滚由POST /documents/scan触发。稳定后如果怀疑 graph↔VDB 漂移再次停止服务并运行lightrag-rebuild-vdb先用它的只读一致性检查菜单选项 1判断这笔 embedding 成本是否值得付。两个工具的硬性前提服务必须停止、工作区必须空闲并发写入会让它们读到一个移动的目标lightrag-rebuild-vdb必须与服务使用同一份.env否则重建的向量落在另一个 embedding 空间。验证恢复完成GET /documents/pipeline_status中recovery_required回到falserecovery_kind/recovery_message随之为空原本 503 的写接口上传、/documents/scan、删除等不再返回 503能正常受理走 offline 路径时kg_integrity_repair --apply的报告字段repaired_docs列出实际写入的锚点修复missing_entity_anchors/missing_relation_anchors是诊断项修复后不会清空lightrag-rebuild-vdb的一致性检查通过。限制与边界围栏只影响写操作查询接口不受管道准入约束、不会被 503但在 clear/delete 期间查询结果不保证一致可能看到空结果、部分结果或存储错误。503 围栏机制中的worker 死亡中途与owner 存活无法判定两类只在Linux 多 worker Gunicorn下出现单进程 Uvicorn 或 Windows 不会出现这两类。若删除文档时收到的是 409缺少 recovery anchor而非 503那是另一条路径原样重试会被再次拒绝需要先运行audit_kg_integrity(..., applyTrue)即上面的kg_integrity_repair --apply。【免费下载链接】LightRAG[EMNLP2025] LightRAG: Simple and Fast Retrieval-Augmented Generation项目地址: https://gitcode.com/GitHub_Trending/li/LightRAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考