引入 PageIndex PR #343 的限速能力 — 根治 MiniMax Token Plan HTTP 429

[Leooone]

关联

上游 PageIndex Issue: Leooone/PageIndex#1
PageIndex PR #343: VectifyAI/PageIndex#343

问题

使用 MiniMax Token Plan API 索引大文档时，即使 PAGEINDEX_MAX_CONCURRENCY=1，summary 阶段的 LLM 调用仍频繁触发 HTTP 429。

解决

从 VectifyAI/PageIndex PR #343 移植了三个能力到 Leooone/PageIndex@pymupdf-toc：

1. SlidingWindowRateLimiter — 滑动窗口限速器，通过 PAGEINDEX_RPM_LIMIT 环境变量控制每分钟请求上限
2. _extract_retry_delay() — 智能重试延迟：429 时解析 Retry-After 响应头，无头时使用指数退避+抖动
3. _is_rate_limit_error() — 自动检测 429 错误类型

用法

在 .env 中添加：

PAGEINDEX_MAX_CONCURRENCY=1   # 并发上限
PAGEINDEX_RPM_LIMIT=20        # 每分钟请求上限（建议 20-30）

改动文件

• pageindex/config.py — 新增 rpm_limit 字段和 rpm_limit_scope()
• pageindex/index/utils.py — 新增 SlidingWindowRateLimiter、429 检测、智能延迟
• pageindex/index/pipeline.py — build_index 接入 rpm_limit_scope
• .env.example — 增加 PAGEINDEX 相关配置说明
• PYMUPDF_TOC.md — 增加限速配置文档

[Leooone]

修复方案

依赖 Leooone/PageIndex#1 的修复。

PageIndex 侧改动（commit f94fadc）

从 VectifyAI/PageIndex PR #343 移植：

• SlidingWindowRateLimiter：滑动窗口限速器，PAGEINDEX_RPM_LIMIT 控制每分钟请求上限
• _extract_retry_delay()：429 时解析 Retry-After 头，否则指数退避+抖动
• rpm_limit_scope()：build_index 自动激活/停用限速器

OpenKB 侧改动（本仓库）

• .env.example：增加 PAGEINDEX 限速配置示例
• PYMUPDF_TOC.md：增加限速配置文档

最终配置

# .env
PAGEINDEX_MAX_CONCURRENCY=1
PAGEINDEX_RPM_LIMIT=20

效果

设置 RPM=20 后，即使并发较高，限速器在信号量之前控制发射频率，从根本上避免触发 MiniMax Token Plan 的 HTTP 429。