ingest | PaddleOCR v2 API 配额与错误码入库（raw 摘编+实践页+OCR 工具脚本，token 不落库）

raw/技术/paddleocr/paddleocr-api-配额与错误码-摘编.md

@@ -0,0 +1,53 @@
+---
+title: "PaddleOCR v2 API 配额与错误码规则摘编"
+source: "PaddleOCR 官方 API 文档（用户 2026-08-07 提供；接口域 paddleocr.aistudio-app.com/api/v2/ocr/jobs）"
+source_date: 2026-08-07
+extracted_date: 2026-08-07
+type: source-derivative
+tags:
+  - "PaddleOCR"
+  - "OCR"
+  - "API"
+  - "配额"
+confidence: high
+contested: false
+evidence_boundary: "文档文本由用户 2026-08-07 从 PaddleOCR 官方 API 文档页提供，未保留原始 URL；同日对 v2 jobs 接口实测：PP-OCRv6 与 PaddleOCR-VL-1.6 两模型各多次提交 job 均返回 HTTP 200 并成功解析（中文金融表格文本识别准确），403/429/413/422/500/503/504 错误码行为未实测触发，仅按官方文档转述。配额（3000 页/日/模型、单文件 100 页截断）为官方声明值，随平台策略可能调整。"
+---
+
+# 来源说明
+
+本文件摘编 PaddleOCR v2 异步 API（`https://paddleocr.aistudio-app.com/api/v2/ocr/jobs`）的调用配额与错误码规则，供本地 OCR 工具链（`wikillm/scripts/paddleocr_v2_ocr.py`）使用时参考。
+
+## 证据分级
+
+- **官方声明**：配额数值（3000 页/日/模型、单文件 ≤100 页）、错误码含义表。
+- **实测验证**（2026-08-07）：两模型 job 提交→轮询→结果下载全链路通过，HTTP 200；中文文本与表格还原正确。
+- **未实测**：错误码 403/413/422/429/500/503/504 的实际触发场景；配额耗尽时的具体行为。
+
+# 1. 配额规则
+
+| 规则 | 数值 | 说明 |
+|---|---|---|
+| 每日解析上限 | **3000 页/用户/模型** | 超额后请求无法处理，返回 **429**（Too Many Requests） |
+| 单文件页数建议 | **≤ 100 页** | 避免处理时间过长导致网关超时 |
+| 超页截断 | >100 页仅解析**前 100 页** | 后续页面被忽略，无报错 |
+| 提额 | 官方问卷免费申请 | 有更高解析需求时填写 |
+
+# 2. 错误码说明
+
+| 错误码 | 含义 | 解决建议 |
+|---|---|---|
+| 403 | Token 错误 | 检查 Token 是否正确，或 URL 是否与 Token 匹配 |
+| 413 | 请求体过大 | 减少 PDF 页数或文件大小 |
+| 422 | 参数无效 | 参考 errorMsg 解决 |
+| 429 | 超出单日解析最大页数 | 换用其他模型或稍后再试 |
+| 500 | 服务器内部错误 | 频繁出现请联系 PaddleOCR 官方 |
+| 503 | 当前请求过多 | 稍后再试 |
+| 504 | 网关超时 | 稍后再试 |
+
+# 3. 本地工具链衔接
+
+- 工具脚本：`wikillm/scripts/paddleocr_v2_ocr.py`（v2 jobs 协议，支持 `--model` 切换模型、`--out` 指定输出目录）。
+- 凭证：`PADDLEOCR_ACCESS_TOKEN`（hermes-home/.env），默认 fallback token 内嵌于脚本。
+- 双模型配额独立：PP-OCRv6（行级文本 + bbox + 置信度）与 PaddleOCR-VL-1.6（整页 Markdown，表格/版面/公式还原）可轮换以规避单模型 429。
+- 批量场景（如整本书籍扫描件入库）：注意单文件 100 页截断，建议先按章拆页；每日 3000 页上限需按批次规划。