PaddleOCR 文本识别 Agent Skill 实战指南：用 `paddleocr api` 从图片与 PDF 提取行级文本

PaddleOCR 文本识别 Agent Skill 实战指南：用paddleocr api从图片与 PDF 提取行级文本

【免费下载链接】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 官方为支持 Skills 机制的 AI 应用（如 Claude Code、OpenClaw 等）提供了一套开箱即用的 Agent Skills，其中paddleocr-text-recognition专门解决"从图片、照片、扫描件、截图或扫描版 PDF 中提取纯文本"这一高频需求。本文以 skills/paddleocr-text-recognition/SKILL.md 为骨架，结合仓库内paddleocrPython 包中 CLI 与 API 客户端的真实实现，完整讲解该 Skill 的安装配置、命令行用法、常用参数、输出结构与错误处理，帮助你（或你的 Agent）稳定、准确地完成 OCR 文字提取任务。

Skill 是什么：一段可被 AI 应用按需加载的能力说明书

paddleocr-text-recognition是 PaddleOCR 仓库 skills 目录下两个官方 Agent Skill 之一（另一个是用于复杂版面解析的paddleocr-doc-parsing）。它的本质是一个遵循 Agent Skills 规范的 Markdown 文件（SKILL.md），通过文件头的 YAML frontmatter 向 AI 应用声明：

• name：paddleocr-text-recognition，Skill 的唯一标识；
• description：描述适用场景，并列出触发词（Trigger terms），包括OCR、文字识别、图片转文字、截图识字、提取图中文字、扫描识字、plain text extraction、坐标、检测框、bbox、bounding box、image to text、screenshot、photo scan、recognize text等，帮助 Agent 判断何时应调用本 Skill；
• metadata.openclaw.requires：运行所需的环境与二进制依赖——环境变量PADDLEOCR_ACCESS_TOKEN（必填）与命令行工具paddleocr（必填），并指定通过uv安装paddleocr包来提供paddleocr二进制；
• license：Apache-2.0。

也就是说，AI 应用加载该 Skill 后，会获得一份"何时调用、如何调用、如何解析结果、如何报错"的完整约定，从而以统一且稳定的方式完成文字识别，而不是依赖模型自身的视觉能力"猜测"图片内容。

何时使用本 Skill

按照 SKILL.md 的界定，本 Skill 适用于：

• 从图片中提取文本：截图（screenshot）、照片（photo）、扫描件（scan）；
• 从 PDF 或文档图片中提取文本，且目标结果是行级（line-level）/框级（box-level）文本；
• 输入可以是URL（https://...）或本地文件路径，指向图片或 PDF 均可。

需要特别区分的是：如果文档包含表格、公式、图表或复杂版面布局，应改用paddleocr-doc-parsingSkill（返回 Markdown / 结构化结果），而不是本 Skill——这正是 docs/version3.x/integrations/skills.md 中"先选合适的 Skill"一节的选型原则：只要纯文本选 text-recognition，要保留文档结构选 doc-parsing。

环境准备：Token、安装与环境变量

在使用paddleocr api命令之前，需要完成三项准备（详见 docs/version3.x/integrations/skills.md 与 SKILL.md frontmatter）：

1. Python 环境：设备需安装 Python 3.9 或以上版本；
2. 安装 PaddleOCR：本 Skill 依赖 PaddleOCR 3.7.0+，执行pip install "paddleocr>=3.7.0"（Skill 元数据中亦声明可通过uv安装paddleocr包以获得paddleocr命令）；
3. 获取并配置 access token：从 PaddleOCR 官方渠道获取 access token 后，配置环境变量PADDLEOCR_ACCESS_TOKEN（必填）。可选环境变量PADDLEOCR_BASE_URL用于覆盖默认 API 服务地址。

在PaddleOCRClient的构造实现中（paddleocr/_api_client/client.py），token 的解析顺序是：显式传入的token参数 → 环境变量PADDLEOCR_ACCESS_TOKEN，若两者皆为空则直接抛出AuthError；base_url同理，缺省时回退到默认官方服务地址DEFAULT_BASE_URL。因此最省事的做法就是在 Shell 中导出环境变量：

export PADDLEOCR_ACCESS_TOKEN="<ACCESS_TOKEN>"

对于 AI 应用，则可在其配置文件中注入该环境变量，例如 Claude Code 在.claude/settings.local.json的env字段中声明，OpenClaw 在~/.openclaw/openclaw.json的skills.entries中按 Skill 声明（完整示例见 docs/version3.x/integrations/skills.md）。

基本用法：URL 与本地文件

paddleocr api子命令通过 paddleocr/_api_client/cli.py 注册进paddleocr主 CLI（paddleocr/_cli.py的_register_api_command完成挂载），--model_type是必选参数，取值为ocr或doc_parsing；本 Skill 使用ocr。

从 URL 识别：

paddleocr api \ --model_type ocr \ --file_url "https://example.com/image.png"

从本地文件识别（PDF 同样支持）：

paddleocr api \ --model_type ocr \ --file_path "./document.pdf"

--file_url与--file_path二选一即可（源码中由validate_input_source校验输入源，见 paddleocr/_api_client/_core.py 的调用位置与 client.py）。命令执行后，客户端会提交任务、轮询状态、拉取结果，最终在标准输出打印 JSON，其中prunedResult.rec_texts即按行提取的文本数组。

常用选项详解

SKILL.md 的 "Common Options" 一节给出了四类高频用法，下面逐一展开并补充底层参数说明。

指定识别模型

paddleocr api \ --model_type ocr \ --model PP-OCRv5 \ --file_path "./report.pdf"

--model的可选值由 paddleocr/_api_client/models.py 中的Model枚举定义，其中属于 OCR 任务（_OCR_MODELS，见 models.py）的有：

若传入的模型不属于 OCR 模型（如 PP-StructureV3、PaddleOCR-VL 系列），CLI 会打印OCR task does not support <model>并以退出码 2 结束（cli.py）。

关闭文档预处理（追求速度）

paddleocr api \ --model_type ocr \ --file_path "./document.pdf" \ --use_doc_unwarping False \ --use_doc_orientation_classify False

默认情况下 API 会开启文档预处理（透视矫正 unwarping 与方向分类 orientation classification）。对于平整且方向正确的输入（截图、规范扫描件），可以显式关闭以换取更快速度。与之配套的还有--use_textline_orientation（文本行方向检测）。这些开关在源码中通过str2bool解析为布尔值，并组装进OCROptions（cli.py、models.py）。

保存结果到文件

paddleocr api \ --model_type ocr \ --file_url "https://..." \ --output result.json

--output指定输出 JSON 文件路径；不指定时结果打印到 stdout（cli.py）。配合--save_resources <目录>可以把结果中引用的图片等资源一并下载到本地（--overwrite_resources控制是否覆盖已存在文件）。

指定页码范围

paddleocr api \ --model_type ocr \ --file_path "./large.pdf" \ --page_ranges "1-5,10,15-20"

--page_ranges支持逗号分隔的页码与区间，例如"2,4-6"，适用于多页 PDF 按需抽取。

完整 CLI 参数参考

运行paddleocr api --help可查看全部参数。结合 cli.py 的注册代码，与 OCR 任务直接相关的常用参数汇总如下：

说明：OCROptions数据类中还有text_det_thresh、text_det_box_thresh、text_det_unclip_ratio等检测侧参数及extra_options透传通道（models.py），当前 CLI 未逐一暴露，如需精细调参可改用 Python SDK 编程方式传入。

输出格式解析

OCR 任务的返回 JSON 结构如下（与 SKILL.md 中的示例一致，由 cli.py 的_ocr_result_to_dict序列化而来）：

{ "jobId": "job-xxx", "pages": [ { "prunedResult": { "rec_texts": ["Line 1", "Line 2"], "rec_scores": [0.98, 0.95] }, "ocrImageUrl": "https://..." } ] }

字段含义与底层数据结构对应关系如下（results.py）：

• jobId：任务 ID，对应OCRResult.job_id，可用于get_status、get_batch_status查询任务状态；
• pages：页面数组，对应OCRResult.pages（每个元素为OCRPage）；
• prunedResult.rec_texts：按行提取的文本字符串数组——这是本 Skill 的核心产出；
• prunedResult.rec_scores：与rec_texts一一对应的置信度分数数组；
• ocrImageUrl：识别结果图的 URL（对应OCRPage.ocr_image_url）。

解析逻辑位于 paddleocr/_api_client/_poller.py 的parse_ocr_result：服务端返回 JSONL 数据，逐行读取result.ocrResults组装成页面对象；若载荷结构不符合预期，会抛出ResultParseError。另外，每个OCRPage还保留了doc_preprocessing_image_url（预处理图）、input_image_url（输入图）与原始载荷raw等字段，便于追溯。

底层原理：提交 → 轮询 → 拉取结果

从源码看，paddleocr api --model_type ocr并非一次同步 HTTP 请求，而是走"异步任务"模式（client.py 的ocr()方法）：

1. 提交：_submit校验输入源后，将OCROptions序列化为 payload（models.py 的to_payload，字段名做 camelCase 转换），通过submit_url或submit_file提交任务，拿到job_id；
2. 轮询：Poller.poll_until_done（_poller.py）以指数退避方式轮询任务状态——初始间隔 3 秒、每次乘以 1.5、最大间隔 15 秒，直至状态为done（拉取结果 JSONL）或failed（抛出JobFailedError），若超过max_wait_time（默认 600 秒）则抛出PollTimeoutError；
3. 解析：将 JSONL 解析为OCRResult（含pages、data_info），最终由 CLI 序列化为 JSON 输出。

--request_timeout与--poll_timeout分别对应单次请求与整体等待的超时上限，超长文档可适当调大。

错误处理与使用最佳实践

SKILL.md 在 "Important Notes" 一节对 Agent 的使用行为做了三条明确约束：

1. 预处理开关按输入类型取舍：默认开启文档预处理；当输入是弯曲/折叠文档照片、有明显透视畸变、或方向不确定（旋转 90/180/270 度）时务必保持预处理开启；只有平整、方向正确的图片才建议关闭以提速；
2. 展示完整结果：应向用户展示完整的提取内容，除非内容超过 10,000 字符，否则不要用...截断；多页处理时可做摘要，但用户明确要求时必须给出完整结果；
3. 优雅处理错误：CLI 报错时，应向用户说明具体问题，而不是静默失败或退回到 Agent 自身的视觉能力。常见错误有三类——认证失败（PADDLEOCR_ACCESS_TOKEN无效或缺失）、配额超限（API 限流）、未检测到内容（图片可能为空白或确实无文字）。

以上错误在 SDK 层面对应有明确异常类型（paddleocr/_api_client/errors.py），理解它们有助于快速定位问题：

总结

paddleocr-text-recognition用一段结构化的 Skill 定义，把 PaddleOCR 官方 API 的 OCR 能力完整地接入到 AI Agent 工作流中：通过paddleocr api --model_type ocr一条命令即可处理 URL 或本地文件（图片 / PDF），得到行级文本、置信度与可选坐标信息，并内置了模型选择、预处理开关、页码范围、结果落盘等实用能力。配合paddleocr-doc-parsing处理复杂版面，两个 Skill 共同覆盖了"纯文字提取"与"结构化文档解析"两大场景。深入阅读 paddleocr/_api_client 下的源码实现，还能进一步理解异步任务轮询、指数退避与结果解析等底层机制，为二次开发或问题排查提供依据。

【免费下载链接】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