海量扫描件批量识别的调度设计：队列、分片与限流

扫描件批量识别的调度，难的不是「调接口」，是几十万次调用里必然出现的长尾和失败。一次几万页的项目跑下来，调度设计的每个决策都会被放大验证。这篇拆四个关键设计。

设计一：分片粒度——按页还是按文档

最小调度单元选「页」还是「文档（多页 PDF）」，决定了整个批次的失败半径。按文档分片：一个 200 页的 PDF 失败，200 页全部重来；按页分片：单页失败只重试单页，但任务数量放大几十倍，队列管理开销上升。

实践结论：按页分片、按文档记账。调度粒度到页（失败半径最小），进度和计费按文档汇总。分片时给每页打上「文档 id + 页序」的复合键，聚合时靠它归组——这个键同时是幂等键的一部分。

设计二：限流自适应

识别服务的限流墙是批处理的常客。固定速率发送，限流后全线失败重试，再撞限流，雪崩。解法是自适应速率：

• 基线速率从配额推算（每分钟配额 × 0.8 起步）；
• 收到限流响应，速率乘 0.5 退避，之后每成功 100 次恢复 10%；
• 连续成功率高于 99% 且持续 5 分钟，速率试探性 +20%，撞墙再退。

这个「加性增、乘性减」的节奏和 TCP 拥塞控制同源，在识别批处理场景实测有效。关键是退避要果断、恢复要克制——恢复太快会形成限流震荡。

设计三：断点续传

几万页的批次跑几个小时，中途因为任何原因（发布、超时、网络）中断是常态，不是异常。断点续传的要点：

• 已完成页落库先于下一页派发——顺序反了，崩溃时会丢一段进度；
• 进度键用业务幂等键（文档 hash + 页序 + 引擎版本），恢复任务时先查库再派发，天然防重复投递；
• 恢复点不追求精确——宁可多跑十几页已完成的（幂等保护下无害），不要少跑。

设计四：失败隔离

三类失败必须隔离，不能混在一个重试池里：

• 瞬时失败（超时、连接断）——指数退避重试，上限 5 次；
• 确定性失败（文件损坏、页为空、格式不支持）——重试无意义，直接进死信，人工看一眼原因；
• 质量性失败（识别成功但置信度低）——不是失败，是低置信结果，标记后走人工复核队列，不进重试。

混池的代价是死循环：确定性失败的任务反复重试，把瞬时失败的合理重试额度全吃掉。

验证清单

调度设计做完，用四个数字验收：单页失败半径（应为 1 页）、限流雪崩恢复时间（撞墙后 2 分钟内速率稳定）、中断恢复丢页数（应为 0）、死信占比（健康批次应低于 0.5%）。四个数字达标，几十万页的批次才敢接。