展开本页目录
开始前准备什么
- 下载到独立练习目录，先运行材料校验，再连接自己的翻译服务。
- 准备 Python 与对应工具的隔离环境；PDF 检查使用 Poppler，翻译版本分别记录。
- 原文均为原创练习材料；密钥只填在本机，不写入下载文件或截图。
- 区分源文件错误与服务限流
- 运行明确标注的本地演练
- 读取实际演练日志
- 在 Next 里同时降速与降并发
- 记录失败页与原始范围
- 等待恢复后只做失败范围
- 验收并关闭任务
原创 PDF/CSV/EPUB/HTML、逐步说明、校验脚本与真实离线记录；不含模型译文。
对应本页操作、工具边界与验收范围。
本页截图使用的原始文档。
读取真实材料与文件结构；不请求模型、不读取凭证。
当前材料与脚本的实际运行结果。
本页专用练习材料；运行范围见 README。
本页专用练习材料；运行范围见 README。
本页专用练习材料；运行范围见 README。
1. 区分源文件错误与服务限流
HTTP 429 表示实际请求被限制；额度不足、配额规则和并发过高都可能触发。先保存状态、错误体与源页号，隐藏 Key；只凭“翻译失败”不能下结论。
bash
python3 verify.py
2. 运行明确标注的本地演练
retry-demo.py 只在 127.0.0.1 的临时端口启动 HTTPServer，先返回 429 与 Retry-After: 0，重试后返回 200 的 fixture 标记。它不访问上游、不调用模型，也不生成假译文。
bash
python3 retry-demo.py3. 读取实际演练日志
retry-log.json 记录真实 localhost 请求的状态序列、尝试次数和响应标记。确认是 [429,200]，不要把它宣传成 apizt 或任何翻译服务的实测。
4. 在 Next 里同时降速与降并发
确认实际使用 pdf2zh_next。qps 约束请求速率，pool-max-workers 限制翻译线程数；术语提取还有 term-qps/term-pool-max-workers。默认值和版本不同，不套用一个通用“最佳并发”。
bash
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 示例。
bash
pdf2zh_next source.pdf --pages 2 --qps 1 --pool-max-workers 1 --output output/retry-page-27. 验收并关闭任务
检查真实译文原页映射、错误次数和完整性后更新台账。缓存或已有文件不等于本次请求成功；将本地 fixture 日志与真实服务日志分开保存。
怎样确认已经完成
- 本地真实 HTTP 演练出现 429 后 200，响应明确标有 fixture 且不含译文。
- Next 的速率、worker 与术语提取限制按实际配置核对。
- 真实失败原页号与重试产物可追溯；教材人工清单不当作上游故障记录。
常见问题
降低线程数为什么仍 429？
线程只是一项因素，还可能受到请求速率、令牌额度、账号配额或其他并行任务影响。查看实际错误体与服务后台。
成功重试 200 是否代表这页翻译通过？
不代表。还要检查翻译内容、文件写出和原页映射。本地 fixture 的 200 仅证明演练客户端执行了重试。