跳转至

PaddleOCR 官方 API Python SDK

Python SDK 通过 paddleocr 包中的 PaddleOCRClient 和 AsyncPaddleOCRClient 调用 PaddleOCR 官方 API。它提交 OCR 或文档解析任务到官方托管服务，不运行本地推理，也不加载本地模型。

安装与认证

先按 安装 paddleocr 安装 Python 包。安装 paddleocr 本体后即可使用此功能，无需安装额外依赖组。

请先在 AI Studio Access Token 页面 获取访问令牌。

export PADDLEOCR_ACCESS_TOKEN="your-access-token"

PaddleOCRClient() 默认读取 PADDLEOCR_ACCESS_TOKEN，也支持 PaddleOCRClient(token="...")。未提供 token 时会抛出 AuthError。

快速开始

from paddleocr import PaddleOCRClient, Model

client = PaddleOCRClient()
result = client.ocr(
    file_url="https://example.com/invoice.pdf",
    model=Model.PP_OCRV5,
)
print(result.job_id, len(result.pages))
client.close()

传入本地文件时使用 file_path。file_url 与 file_path 必须二选一。

公共 API

Python SDK 常用公共方法包括：

  • ocr(...)：提交 OCR 任务，等待完成并返回 OCR 结果。
  • parse_document(...)：提交文档解析任务，等待完成并返回文档解析结果。
  • submit_ocr(...)：只提交 OCR 任务，返回任务对象。
  • submit_document_parsing(...)：只提交文档解析任务，返回任务对象。
  • get_status(job_id)：执行一次非阻塞状态查询，不等待完成。
  • wait_ocr_result(job)：等待 OCR 任务完成并解析结果。
  • wait_document_parsing_result(job)：等待文档解析任务完成并解析结果。
  • save_resource(resource_url, destination)：保存单个资源 URL。
  • save_ocr_result_resources(result, destination)：保存 OCR 结果对象引用的资源。
  • save_document_parsing_result_resources(result, destination)：保存文档解析结果对象引用的资源。

异步客户端 AsyncPaddleOCRClient 暴露上述任务操作和资源保存方法的异步版本。

模型选择

表中的 Model 枚举是官方 API 模型名字符串的类型安全写法，提交请求时会转换为对应的实际模型名。也可以直接传入官方 API 模型名字符串，例如 model="PaddleOCR-VL-1.6"。

任务 适用接口 默认模型 可选模型 参数类型
OCR ocr、submit_ocr、wait_ocr_result Model.PP_OCRV5 Model.PP_OCRV5 OCROptions
文档解析 parse_document、submit_document_parsing、wait_document_parsing_result Model.PADDLE_OCR_VL_16 Model.PP_STRUCTURE_V3、Model.PADDLE_OCR_VL、Model.PADDLE_OCR_VL_15、Model.PADDLE_OCR_VL_16 选择 PP-StructureV3 时传入 PPStructureV3Options；选择 PaddleOCR-VL 系列模型时传入 PaddleOCRVLOptions。

常用对应关系：Model.PP_OCRV5 对应 PP-OCRv5，Model.PP_STRUCTURE_V3 对应 PP-StructureV3，Model.PADDLE_OCR_VL 对应 PaddleOCR-VL，Model.PADDLE_OCR_VL_15 对应 PaddleOCR-VL-1.5，Model.PADDLE_OCR_VL_16 对应 PaddleOCR-VL-1.6。

配置与参数

客户端配置

client = PaddleOCRClient(
    request_timeout=300.0,
    poll_timeout=600.0,
)

request_timeout 限制一次 HTTP 请求，包括提交、查询状态和下载结果资源。poll_timeout 限制 ocr、parse_document、wait_ocr_result 和 wait_document_parsing_result 的总等待时间。

通过环境变量 PADDLEOCR_BASE_URL 或 base_url 参数指定自定义服务地址：

client = PaddleOCRClient(base_url="https://my-proxy.com/paddle")

请求参数

SDK 的参数名使用 Python 惯用的 snake_case，提交请求时自动转换为官方 API 的 camelCase。只需传入非 None 的字段，未设置的字段使用服务端默认值。完整字段定义见各 Options 类型源码或「官方 API 参考」。

OCROptions（常用字段）

字段 类型 说明
use_doc_orientation_classify bool 文档方向分类
use_doc_unwarping bool 文档扭曲矫正
visualize bool 是否返回可视化结果图

PPStructureV3Options（常用字段）

字段 类型 说明
use_table_recognition bool 表格识别
use_formula_recognition bool 公式识别
use_chart_recognition bool 图表识别
prettify_markdown bool Markdown 美化

PaddleOCRVLOptions（常用字段）

字段 类型 说明
use_layout_detection bool 版面检测
use_chart_recognition bool 图表识别
temperature float 采样温度
prettify_markdown bool Markdown 美化

错误处理

所有 SDK 错误都继承自 PaddleOCRAPIError，常见类型包括 AuthError、InvalidRequestError、RateLimitError、ServiceUnavailableError、APIError、NetworkError、JobFailedError、RequestTimeoutError、PollTimeoutError、ResponseFormatError 和 ResultParseError。

批量任务查询

提交任务时可传入 batch_id。之后可使用 client.get_batch_status("batch-id") 查询该批次下各任务的状态、进度和结果 URL。

官方 API 参考

配额与错误码

评论