企业官网建设流程全解析

PaddleOCR 官方 API Python SDK 实战指南：PaddleOCRClient 与 AsyncPaddleOCRClient 使用详解

【免费下载链接】PaddleOCR飞桨多语言OCR工具包（实用超轻量OCR系统，支持80+种语言识别，提供数据标注与合成工具，支持服务器、移动端、嵌入式及IoT设备端的训练与部署） Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80+ languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR

导读

本文围绕 PaddleOCR 官方 API 的 Python SDK 展开，讲解如何通过paddleocr包中的PaddleOCRClient（同步）与AsyncPaddleOCRClient（异步）将本地文件或文件 URL 提交到托管式 PaddleOCR 云服务，轮询异步任务并解析类型化结果。读完本文，你将掌握从安装认证、快速起步、模型选择、参数配置到错误处理、批量状态查询与结果资源下载的完整实战技能，并理解 SDK 内部「提交 → 轮询 → 拉取结果」的异步任务调用链与源码级实现细节。

一、SDK 定位：托管式 API 客户端，不做本地推理

PaddleOCR 官方 API 的 Python SDK 是官方托管服务的客户端库，核心特点是：

• 通过PaddleOCRClient与AsyncPaddleOCRClient两个类封装全部交互；
• 将本地文件或文件 URL 提交给托管服务，轮询异步任务，并解析为强类型结果对象；
• 不运行本地推理、不加载本地模型——所有计算发生在云端。

从源码看，两个客户端类在 paddleocr/_api_client/client.py 与 paddleocr/_api_client/async_client.py 中定义，并在 paddleocr/init.py 中作为包顶层导出，因此可以直接从paddleocr导入。底层默认服务地址为https://paddleocr.aistudio-app.com，API 路径为/api/v2/ocr/jobs（见 paddleocr/_api_client/_http.py）。

这套 SDK 是 PaddleOCR 官方 API 多语言客户端家族的一员，同一家族还包括 TypeScript SDK、Go SDK 以及 CLI 中的paddleocr api命令，整体概览见 overview.en.md。

二、安装与认证

2.1 安装

按官方安装文档 installation.en.md 安装paddleocrPython 包即可。安装核心paddleocr包后，官方 API 客户端功能开箱即用，无需安装额外的依赖分组。

2.2 获取并配置 Access Token

首先从 AI Studio 的 Access Token 页面获取访问令牌，然后通过环境变量暴露给 SDK：

export PADDLEOCR_ACCESS_TOKEN="your-access-token"

PaddleOCRClient()默认读取PADDLEOCR_ACCESS_TOKEN环境变量，也支持显式传参PaddleOCRClient(token="...")。当令牌缺失时，构造过程会直接抛出AuthError（源码依据：paddleocr/_api_client/client.py）。

认证失败的场景（如令牌无效或过期，对应 HTTP 401/403）同样会以AuthError形式报出（源码依据：paddleocr/_api_client/_core.py）。

三、快速开始：同步客户端

最简单的用法如下（完整示例来自 python.en.md）：

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_url，本地文件用file_path；
• file_url与file_path必须二选一，同时传或都不传都会抛出InvalidRequestError（源码依据：paddleocr/_api_client/_core.py）；
• client.close()负责关闭底层 HTTP 连接；客户端同时实现了上下文管理器协议（__enter__/__exit__），也可配合with语句使用（源码依据：paddleocr/_api_client/client.py）。

3.1 任务提交的内部调用链

client.ocr(...)并非一步到位的同步 HTTP 调用，其内部执行了「提交 → 轮询 → 拉取 JSONL → 解析」的完整链路（源码依据：paddleocr/_api_client/client.py）：

1. resolve_ocr_model(model)：校验模型是否属于 OCR 模型集合；
2. _submit(...)：校验输入源、构建请求 payload，通过submit_url（远程文件）或submit_file（本地文件）提交任务并获得job_id；
3. poller.poll_until_done(job_id)：按退避策略轮询直到任务进入done或failed状态；
4. parse_ocr_result(job_id, jsonl_data)：将结果 JSONL 解析为OCRResult对象。

也就是说，同步客户端内部本质上也是异步任务模型——「立即返回 jobId，服务端后台执行，客户端轮询结果」。

四、任务类型与模型选择

SDK 支持两大类任务：

Model枚举值是官方 API 模型名字符串的类型安全别名，提交请求时会被序列化为对应的模型名。你也可以直接传官方 API 模型名字符串，例如model="PaddleOCR-VL-1.6"。

从源码看，完整枚举定义（paddleocr/_api_client/models.py）还包含一个文档未列出的 OCR 成员PP_OCRV5_LATIN（对应PP-OCRv5-latin）。模型按用途分为三组（paddleocr/_api_client/models.py）：

• _OCR_MODELS：PP_OCRV5、PP_OCRV5_LATIN、PP_OCRV6；
• _DOCUMENT_PARSING_MODELS：PP_STRUCTURE_V3与全部 VL 模型；
• _VL_MODELS：PADDLE_OCR_VL、PADDLE_OCR_VL_15、PADDLE_OCR_VL_16。

若为错误任务传错模型（例如给ocr传文档解析模型），resolve_ocr_model/resolve_document_model会抛出InvalidRequestError（源码依据：paddleocr/_api_client/_core.py）。

4.1 文档解析的选项自动匹配

调用parse_document时若未显式传 options，SDK 会根据模型自动创建对应类型的选项对象：PP_STRUCTURE_V3得到PPStructureV3Options()，VL 系列得到PaddleOCRVLOptions()；若显式传入的选项类型与模型不匹配（例如给 VL 模型传PPStructureV3Options），会抛出InvalidRequestError（源码依据：paddleocr/_api_client/_core.py）。

五、公共 API 一览

同步客户端PaddleOCRClient的常用公共方法（同步阻塞版本）：

• ocr(...)：提交 OCR 任务、等待完成并返回 OCR 结果；
• parse_document(...)：提交文档解析任务、等待完成并返回文档解析结果；
• submit_ocr(...)：仅提交 OCR 任务，返回Job对象；
• submit_document_parsing(...)：仅提交文档解析任务，返回Job对象；
• get_status(job_id)：发起一次非阻塞的状态查询，不等待任务完成；
• wait_ocr_result(job)：等待 OCR 任务完成并解析其结果（job可为Job对象或 job_id 字符串）；
• 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提供上述任务操作与资源保存方法的异步版本（async def，源码见 paddleocr/_api_client/async_client.py）。

5.1 提交-等待分离的两种工作模式

submit_*+wait_*的组合把「提交」与「等待」解耦：先提交拿到Job（含job_id、model、task，见 paddleocr/_api_client/results.py），后续任意时刻再通过wait_ocr_result(job)/wait_document_parsing_result(job)取回结果。wait_*方法对Job有任务类型校验——把 OCR 的Job传给文档解析的等待方法会抛出InvalidRequestError（源码依据：paddleocr/_api_client/_core.py）。这非常适合将任务 ID 持久化后跨进程恢复的场景。

5.2 结果对象结构

• OCRResult：job_id+pages（每页含pruned_result、ocr_image_url、doc_preprocessing_image_url、input_image_url、raw）+data_info；
• DocParsingResult：job_id+pages（每页含markdown_text、markdown_images、output_images、pruned_result、exports等）+data_info；
• JobStatus：job_id、state（pending/running/done/failed）、progress（total_pages/extracted_pages等）、result、error_msg；
• BatchStatus：batch_id+jobs列表。

数据结构定义见 paddleocr/_api_client/results.py，解析逻辑见 paddleocr/_api_client/_poller.py。

六、客户端配置

6.1 超时配置

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的总等待时长。

两个参数的默认值分别为 300.0 秒与 600.0 秒（源码依据：paddleocr/_api_client/client.py）。异步客户端额外提供timeout快捷参数，一旦设置会同时覆盖request_timeout与poll_timeout（源码依据：paddleocr/_api_client/async_client.py）。

6.2 服务地址覆盖

通过PADDLEOCR_BASE_URL环境变量或base_url参数覆盖默认服务地址：

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

URL 解析优先级为：base_url参数 >PADDLEOCR_BASE_URL环境变量 > 内置默认地址（源码依据：paddleocr/_api_client/client.py）。这一能力便于在内网代理或网关场景下接入。

七、请求选项详解

SDK 参数名采用 Python 惯用的 snake_case，提交时自动转换为 camelCase；只有非None字段会被发送，未指定的字段使用服务端默认值。payload 构建逻辑见 paddleocr/_api_client/models.py：遍历 dataclass 字段，跳过None，extra_options字典会直接平铺合并进 payload，其余字段经snake_to_camel转换后写入。

7.1 OCROptions（OCR 任务，常见字段）

除文档列出的字段外，源码还包含更多可配置项（paddleocr/_api_client/models.py）：use_textline_orientation（文本行方向分类）、text_det_limit_side_len（检测最长边限制）、text_det_limit_type（限制类型min/max）、text_det_thresh（检测阈值）、text_det_box_thresh（检测框阈值）、text_det_unclip_ratio（检测框扩展比例）、text_rec_score_thresh（识别置信度阈值）以及extra_options（透传给服务端的额外参数）。

7.2 PPStructureV3Options（PP-StructureV3 任务，常见字段）

该选项类字段最丰富（paddleocr/_api_client/models.py），还包括：文档预处理三件套（use_doc_orientation_classify、use_doc_unwarping、use_textline_orientation）、use_seal_recognition（印章识别）、use_region_detection（区域检测）、布局参数（layout_threshold、layout_nms、layout_unclip_ratio、layout_merge_bboxes_mode）、format_block_content、检测/识别阈值参数（与 OCR 同名同义）、表格相关开关（use_wired_table_cells_trans_to_html、use_wireless_table_cells_trans_to_html、use_table_orientation_classify、use_ocr_results_with_table_cells、use_e2e_wired_table_rec_model、use_e2e_wireless_table_rec_model）、Markdown 输出控制（markdown_ignore_labels、prettify_markdown、show_formula_number、return_markdown_images、output_formats）与visualize。

7.3 PaddleOCRVLOptions（PaddleOCR-VL 系列任务，常见字段）

VL 选项类（paddleocr/_api_client/models.py）额外包含：use_seal_recognition、use_ocr_for_image_block（对图像块执行 OCR）、布局参数（layout_threshold、layout_nms、layout_unclip_ratio、layout_merge_bboxes_mode、layout_shape_mode）、prompt_label、format_block_content、解码参数（repetition_penalty、top_p、min_pixels、max_pixels、max_new_tokens、vlm_extra_args）、版面合并与标题重排（merge_layout_blocks、merge_tables、relevel_titles、restructure_pages）以及 Markdown 输出控制。

7.4 参数校验：提交前的守卫

PaddleOCRVLOptions.to_payload()在构建 payload 前会执行_validate_vl_options（paddleocr/_api_client/models.py），对非法取值直接抛出InvalidRequestError：

• top_p必须满足0 < top_p <= 1；
• temperature必须>= 0；
• repetition_penalty必须> 0；
• min_pixels、max_pixels必须> 0，且min_pixels <= max_pixels。

八、错误处理

所有 SDK 错误统一继承自PaddleOCRAPIError基类（paddleocr/_api_client/errors.py），常用类型化错误包括：

HTTP 状态码到异常类型的映射在 paddleocr/_api_client/_core.py 中集中实现。实践中建议按「先宽后窄」的顺序捕获：先用except PaddleOCRAPIError兜底 SDK 自身错误，再针对业务需求捕获具体子类；对PollTimeoutError可考虑用submit_*先提交任务、稍后wait_*恢复，避免长任务丢失。

九、批量状态查询

提交任务时传入batch_id，之后可用client.get_batch_status("batch-id")查询该批次内每个任务的状态、进度与结果 URL：

job = client.submit_ocr( file_path="/data/invoice.pdf", batch_id="my-batch-2026", ) batch = client.get_batch_status("my-batch-2026") for item in batch.jobs: print(item.job_id, item.state, item.progress)

BatchStatus包含batch_id与jobs（每个元素为JobStatus），其解析要求响应中的extractResult为对象列表，否则抛ResponseFormatError（源码依据：paddleocr/_api_client/_core.py）。这非常适合「批量发票/合同识别 + 统一进度看板」的场景。

十、异步客户端：并发提交与轮询

AsyncPaddleOCRClient的 API 形状与同步客户端一一对应，全部为async def，特别适合在asyncio事件循环中通过asyncio.gather并发提交与轮询多个任务（类注释明确说明此用途，见 paddleocr/_api_client/async_client.py）：

import asyncio from paddleocr import AsyncPaddleOCRClient, Model async def main(): async with AsyncPaddleOCRClient() as client: results = await asyncio.gather( client.ocr(file_path="/data/a.pdf"), client.ocr(file_path="/data/b.pdf"), client.parse_document( file_path="/data/c.pdf", model=Model.PP_STRUCTURE_V3, ), ) for r in results: print(r.job_id, len(r.pages)) asyncio.run(main())

异步客户端同样支持上下文管理器（async with），其资源保存方法通过asyncio.to_thread将阻塞式下载放到线程池执行，避免阻塞事件循环（源码依据：paddleocr/_api_client/async_client.py）。

十一、结果资源下载

OCR 结果页可能带有可视化图、文档预处理图等资源 URL，文档解析结果页带有 Markdown 内嵌图片与输出图片。SDK 提供三层保存接口：

1. save_resource(resource_url, destination)：下载单个资源；
2. save_ocr_result_resources(result, destination)：批量保存 OCR 结果每页的ocr_image_url，按ocr-page-{index}{ext}命名；
3. save_document_parsing_result_resources(result, destination)：批量保存文档解析结果的markdown_images与output_images。

保存实现（paddleocr/_api_client/_resources.py）具备安全防护：校验 URL 协议必须为 http/https、文件名必须安全（拒绝路径穿越）、目标已存在且未开启overwrite=True时抛InvalidRequestError、下载失败抛NetworkError/RequestTimeoutError，并通过临时文件 + 原子写入（os.replace或os.link）保证落盘一致性。注意save_ocr_result_resources与save_document_parsing_result_resources要求destination为已存在的目录，否则抛FileNotFoundError。

十二、轮询机制与超时行为（源码级）

Poller（paddleocr/_api_client/_poller.py）采用指数退避策略轮询任务状态：

• 初始间隔initial_interval = 3.0秒；
• 每次间隔乘以multiplier = 1.5；
• 间隔上限max_interval = 15.0秒；
• 总等待上限max_wait_time = 600.0秒（与poll_timeout对应）。

轮询过程中识别三类状态：

• done：从resultUrl.jsonUrl拉取 JSONL 结果并返回；
• failed：抛出携带errorMsg的JobFailedError；
• pending/running：继续退避等待；超过截止时间则抛PollTimeoutError。

状态字段取值集合在 paddleocr/_api_client/_core.py 中白名单校验，未知状态直接抛ResponseFormatError。理解这套退避逻辑有助于评估任务耗时与设置合理的poll_timeout：默认 600 秒上限对大多数文档足够，但超大 PDF 或高峰期排队任务建议按需调大。

十三、从官方 API 参考进一步深入

官方 API 参考与配额/错误码说明分别覆盖 PP-OCRv5、PP-StructureV3、PaddleOCR-VL、PaddleOCR-VL-1.5 的接口细节，以及 API 配额规则与错误码描述。在仓库内，你可以：

• 阅读同目录下的中文版文档 python.md 与 CLI 版 cli.en.md、Go 版 go.en.md、TypeScript 版 typescript.en.md，对比不同语言的 API 形态；
• 阅读 tests/api_client/test_core.py、tests/api_client/test_http.py、tests/api_client/test_resources.py 等测试，了解输入校验、HTTP 解析与资源下载的边界行为；
• 直接阅读 SDK 源码模块paddleocr/_api_client/下的client.py、async_client.py、models.py、results.py、errors.py、_poller.py、_core.py、_http.py、_resources.py，获得完整的字段定义与调用链。

总结

PaddleOCR 官方 API Python SDK 将「文件提交、异步轮询、类型化结果解析、资源下载」完整封装进PaddleOCRClient与AsyncPaddleOCRClient两个类，无需本地模型即可完成 OCR 与文档解析任务。实际落地时建议：令牌通过环境变量注入、按任务类型选择正确的Model与 Options 组合、对大文件合理调大poll_timeout、用submit_*+wait_*解耦长任务、用batch_id统一管理批量任务、最后用资源保存接口落盘可视化与 Markdown 图片。

【免费下载链接】PaddleOCR飞桨多语言OCR工具包（实用超轻量OCR系统，支持80+种语言识别，提供数据标注与合成工具，支持服务器、移动端、嵌入式及IoT设备端的训练与部署） Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80+ languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR