# PDFMathTranslate 429 排查：并发、失败页与重试记录

用明确标注的本地 HTTP 限流演练理解 Retry-After，再配置 Next 的 qps 与 worker，按失败原页号恢复任务。

运行范围：原创 PDF/CSV/EPUB/HTML 材料与本地验收已实际执行。没有调用翻译模型、没有连接 Zotero 库、没有填写凭证。官方截图为官方项目示例，不是本练习运行输出。

依赖：Python 3.11+；PDF 验收需 Poppler 的 pdfinfo/pdftotext；OCR 复现需 tesseract 英文语言数据。安装翻译工具时遵循各自官方 Python 要求。

## 1. 区分源文件错误与服务限流

HTTP 429 表示实际请求被限制；额度不足、配额规则和并发过高都可能触发。先保存状态、错误体与源页号，隐藏 Key；只凭“翻译失败”不能下结论。

```sh
python3 verify.py
```

## 2. 运行明确标注的本地演练

retry-demo.py 只在 127.0.0.1 的临时端口启动 HTTPServer，先返回 429 与 Retry-After: 0，重试后返回 200 的 fixture 标记。它不访问上游、不调用模型，也不生成假译文。

```sh
python3 retry-demo.py
```

## 3. 读取实际演练日志

retry-log.json 记录真实 localhost 请求的状态序列、尝试次数和响应标记。确认是 [429,200]，不要把它宣传成 apizt 或任何翻译服务的实测。

## 4. 在 Next 里同时降速与降并发

确认实际使用 pdf2zh_next。qps 约束请求速率，pool-max-workers 限制翻译线程数；术语提取还有 term-qps/term-pool-max-workers。默认值和版本不同，不套用一个通用“最佳并发”。

```sh
pdf2zh_next --version
pdf2zh_next source.pdf --qps 1 --pool-max-workers 1 --term-qps 1 --term-pool-max-workers 1 --output output
```

## 5. 记录失败页与原始范围

failed-pages.csv 用原始页号，不用双语输出页号。示例把第 2 页列为待重做任务，这是人工演练清单，不是模型失败记录；自己的清单必须来自真实运行日志。

## 6. 等待恢复后只做失败范围

按服务实际 Retry-After 和额度规则等待，再指定原始失败页重做。不要无间隔反复发送整本文件；以下命令是需自己运行的 Next 示例。

```sh
pdf2zh_next source.pdf --pages 2 --qps 1 --pool-max-workers 1 --output output/retry-page-2
```

## 7. 验收并关闭任务

检查真实译文原页映射、错误次数和完整性后更新台账。缓存或已有文件不等于本次请求成功；将本地 fixture 日志与真实服务日志分开保存。

## 来源

- https://pdf2zh-next.com/advanced/advanced.html

## 教材

原创输入材料可用于学习练习。官方图片版权归原作者，网页中保留来源；ZIP 不打包这些官方图片。