---
title: "PaddleOCR OCR 工具链使用指南"
source: "PaddleOCR 官方 API 文档 + 2026-08-07 本地实测（wikillm/scripts/paddleocr_v2_ocr.py）"
tags:
  - "PaddleOCR"
  - "OCR"
  - "工具链"
sources:
  - path: "raw/技术/paddleocr/paddleocr-api-配额与错误码-摘编.md"
---

# PaddleOCR OCR 工具链使用指南

## 页面定位
本页是云端 OCR 工具链的实践页：双模型选型、调用方式、配额注意与结果处理。负责工具使用；配额细则与错误码原文见 `raw/技术/paddleocr/` 摘编，不替代扫描件入库流程。

本页是**实践页**：说明本地 PaddleOCR 云端 OCR 工具链怎么用——两种模型的选型、调用方式、配额注意与结果处理。配额与错误码细则见 `raw/技术/paddleocr/` 摘编。

## 工具入口

```bash
python wikillm/scripts/paddleocr_v2_ocr.py <本地文件或URL> [--model 模型名] [--out 输出目录]
```

- 协议：PaddleOCR v2 异步 jobs API（提交 job → 轮询 → 下载 jsonl 结果）。
- 凭证：`PADDLEOCR_ACCESS_TOKEN`（已存 hermes-home/.env；脚本内嵌 fallback token）。
- 输出：每页原始 JSON（`page_N.json`）+ 模型专属产物（见下）。

## 模型选型

| 模型 | 输出形态 | 适用场景 |
|---|---|---|
| `PP-OCRv6`（默认） | 行级文本 + bbox 坐标 + 每行置信度（`rec_scores`） | 纯文字提取：截图、照片、扫描件文字 |
| `PaddleOCR-VL-1.6` | **整页 Markdown**（`doc_N.md`，表格还原为 HTML 表格）+ 版面分块 + 可视化图 | 带表格/复杂版式的文档：研报、报表、书籍页面 |

选型口诀：**纯文字用 v6，带表格用 VL-1.6**。两模型配额独立（各 3000 页/日），可轮换规避 429。

## 配额与限流（2026-08-07 官方声明）

- 每用户 × 每模型 **3000 页/日**；超额返回 429，当日该模型不可用。
- **单文件 ≤ 100 页**，超过只解析前 100 页（静默截断，无报错）。
- 批量任务（如整本书扫描件）务必先按章拆页；大批量按批次规划并预留双模型轮换。

## 常见错误速查

| 码 | 含义 | 处理 |
|---|---|---|
| 403 | Token 错/URL 不匹配 | 核对 hermes-home/.env 中的 token |
| 413 | 请求体过大 | 减页数/文件大小 |
| 429 | 超当日页数上限 | 换模型或次日再试 |
| 504 | 网关超时 | 稍后重试（大文件建议先拆页） |

## 实测记录（2026-08-07）

- PP-OCRv6：中文金融表格图片识别，文本置信度 0.94–1.00，行级输出正确。
- PaddleOCR-VL-1.6：同图整页 Markdown 还原，5 行 4 列表格 HTML 全部正确（品种/产地/价格/较昨日）。

## 相关

- [[Glossary|术语表]] - PaddleOCR、OCR 等术语
- raw 摘编：`raw/技术/paddleocr/paddleocr-api-配额与错误码-摘编.md`
- 官方：https://www.paddleocr.com / https://paddleocr.aistudio-app.com