[Bug]: Wiki REFINE does not recover after transient LLM retries are exhausted

问题场景

用户在 RAGFlow 0.27.x 上生成 Wiki 页面，走的是增量 REFINE（page-writer）路径，模型通过带请求数限制的 OpenAI 兼容网关调用。当网关在短时间内大量返回 429（例如“您已达到总请求数限制”）和超时后，Wiki 生成报告大量页面失败，且网关恢复后当前运行不会自动重试这些页面，需要手动触发 Update 才能恢复。

报错原文

Wiki incomplete: 734 page(s) failed; retry required.

**ERROR**: ERROR_MAX_RETRIES - Error code: 429 - 您已达到总请求数限制

原因分析

Issue 中的分析是：provider/client 和自适应 LLM 池本身已有重试，但当这些重试耗尽后，_chat_mdl_ask 抛出异常，REFINE 路径为该页写入失败标记，run_wiki 将进度置为 -1，执行器直接确认消息；此后即使网关恢复，当前这一轮也不会再重试失败的 page-writer，只有之后再手动 Update 才能恢复。可能原因是瞬态错误（429、超时）与配额/鉴权/非法请求等不可恢复错误在 REFINE 路径上被同等处理，缺少在持久化失败标记之前的有限延迟恢复。日志中请求数（约 2,500 次 chat 请求、1,857 次 429、137 次超时）与失败页面数（734 页）是不同指标，Issue 明确不假定两者一一对应。

环境排查

• 确认 RAGFlow 版本与提交，是否在 0.27.x / 0.27.2 范围内，以及是否已包含 #20930。
• 确认 LLM 网关的请求数上限、配额状态，以及 429 响应体是否为瞬态限流（Issue 中为 ERROR_MAX_RETRIES - Error code: 429）。
• 查看部署日志中的 chat 请求量、429 拒绝数与超时数，判断是否集中出现瞬态失败。
• 持续出现的配额耗尽、鉴权失败或非法请求不属于本 Issue 的瞬态场景，需要单独处理网关侧配置。
• Issue 未提供 Python、CUDA、PyTorch、显卡及具体依赖版本，这些项需按自身部署另行核对。

解决步骤

1. 先降低网关侧瞬态失败：核对请求数限制与配额，确认 429 属于短期限流而非配额用完。
2. 升级到包含 #20930 的 RAGFlow 版本；该修复会在页面被判定失败之前重试瞬态的 page-writer 失败。
3. 若暂时无法升级，在网关恢复后对失败的 Wiki 手动触发 Update，重新生成失败页面（这是 Issue 中确认可行的现有恢复方式）。
4. 如果仍希望保留原有失败标记与手动 Update 兜底，按现有行为处理；不要重复执行持久化或编辑历史相关操作，Issue 要求成功页面与持久化/编辑历史操作不得重放。

验证方法

按 Issue 的复现方式验证：让 chat 适配器先返回重试耗尽的 429（ERROR_MAX_RETRIES - Error code: 429），随后让下一次调用成功以模拟网关恢复。修复前，_wiki_refine_page 在收到 429 时直接抛出，不会发出后续的成功调用；修复后，该瞬态失败应在标记页面失败前被重试，Wiki 不再需要手动 Update 即可完成该页。Issue 提到的覆盖 generate、modify、re-synthesize 三种模式的 REFINE 路径单元回归可用于确认。

参考来源

infiniflow/ragflow #20929（修复 PR：#20930，已合并）；相关背景：#19156、#19254、#18857。

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。