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/PaddleOCRPaddleOCR 官方为支持 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 应用声明namepaddleocr-text-recognitionSkill 的唯一标识description描述适用场景并列出触发词Trigger terms包括OCR、文字识别、图片转文字、截图识字、提取图中文字、扫描识字、plain text extraction、坐标、检测框、bbox、bounding box、image to text、screenshot、photo scan、recognize text等帮助 Agent 判断何时应调用本 Skillmetadata.openclaw.requires运行所需的环境与二进制依赖——环境变量PADDLEOCR_ACCESS_TOKEN必填与命令行工具paddleocr必填并指定通过uv安装paddleocr包来提供paddleocr二进制licenseApache-2.0。也就是说AI 应用加载该 Skill 后会获得一份何时调用、如何调用、如何解析结果、如何报错的完整约定从而以统一且稳定的方式完成文字识别而不是依赖模型自身的视觉能力猜测图片内容。何时使用本 Skill按照 SKILL.md 的界定本 Skill 适用于从图片中提取文本截图screenshot、照片photo、扫描件scan从 PDF 或文档图片中提取文本且目标结果是行级line-level/框级box-level文本输入可以是URLhttps://...或本地文件路径指向图片或 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 frontmatterPython 环境设备需安装 Python 3.9 或以上版本安装 PaddleOCR本 Skill 依赖 PaddleOCR 3.7.0执行pip install paddleocr3.7.0Skill 元数据中亦声明可通过uv安装paddleocr包以获得paddleocr命令获取并配置 access token从 PaddleOCR 官方渠道获取 access token 后配置环境变量PADDLEOCR_ACCESS_TOKEN必填。可选环境变量PADDLEOCR_BASE_URL用于覆盖默认 API 服务地址。在PaddleOCRClient的构造实现中paddleocr/_api_client/client.pytoken 的解析顺序是显式传入的token参数 → 环境变量PADDLEOCR_ACCESS_TOKEN若两者皆为空则直接抛出AuthErrorbase_url同理缺省时回退到默认官方服务地址DEFAULT_BASE_URL。因此最省事的做法就是在 Shell 中导出环境变量export PADDLEOCR_ACCESS_TOKENACCESS_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主 CLIpaddleocr/_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的有模型值说明PP-OCRv5PP-OCRv5 通用识别模型PP-OCRv5-latinPP-OCRv5 拉丁语系变体PP-OCRv6PP-OCRv6 模型CLI 未显式指定时的默认值见 cli.py 与 client.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解析为布尔值并组装进OCROptionscli.py、models.py。保存结果到文件paddleocr api \ --model_type ocr \ --file_url https://... \ --output result.json--output指定输出 JSON 文件路径不指定时结果打印到 stdoutcli.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 任务直接相关的常用参数汇总如下参数类型/取值默认值作用--model_typeocr/doc_parsing必填任务类型--modelModel枚举值PP-OCRv6识别模型--file_urlstr无远程文件 URL--file_pathstr无本地文件路径--base_urlstr环境变量/官方服务API 服务地址--tokenstr环境变量PADDLEOCR_ACCESS_TOKEN访问令牌--outputstrstdout结果 JSON 输出路径--request_timeoutfloat300.0单次 HTTP 请求超时秒--poll_timeoutfloat600.0等待远程任务完成的整体超时秒--page_rangesstr无页码区间如2,4-6--batch_idstr无批量任务标识用于查询相关任务--use_doc_orientation_classifyTrue/False默认开启文档方向分类预处理--use_doc_unwarpingTrue/False默认开启文档透视矫正预处理--use_textline_orientationTrue/False无文本行方向检测--text_det_limit_side_lenint无文本检测的图片边长限制--text_det_limit_typemin/max无边长限制类型--text_rec_score_threshfloat无文本识别结果置信度阈值--visualizeTrue/False无输出可视化结果图--save_resourcesstr无保存结果引用资源的目录--overwrite_resources开关关覆盖已存在的资源文件说明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.pyjobId任务 ID对应OCRResult.job_id可用于get_status、get_batch_status查询任务状态pages页面数组对应OCRResult.pages每个元素为OCRPageprunedResult.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()方法提交_submit校验输入源后将OCROptions序列化为 payloadmodels.py 的to_payload字段名做 camelCase 转换通过submit_url或submit_file提交任务拿到job_id轮询Poller.poll_until_done_poller.py以指数退避方式轮询任务状态——初始间隔 3 秒、每次乘以 1.5、最大间隔 15 秒直至状态为done拉取结果 JSONL或failed抛出JobFailedError若超过max_wait_time默认 600 秒则抛出PollTimeoutError解析将 JSONL 解析为OCRResult含pages、data_info最终由 CLI 序列化为 JSON 输出。--request_timeout与--poll_timeout分别对应单次请求与整体等待的超时上限超长文档可适当调大。错误处理与使用最佳实践SKILL.md 在 Important Notes 一节对 Agent 的使用行为做了三条明确约束预处理开关按输入类型取舍默认开启文档预处理当输入是弯曲/折叠文档照片、有明显透视畸变、或方向不确定旋转 90/180/270 度时务必保持预处理开启只有平整、方向正确的图片才建议关闭以提速展示完整结果应向用户展示完整的提取内容除非内容超过 10,000 字符否则不要用...截断多页处理时可做摘要但用户明确要求时必须给出完整结果优雅处理错误CLI 报错时应向用户说明具体问题而不是静默失败或退回到 Agent 自身的视觉能力。常见错误有三类——认证失败PADDLEOCR_ACCESS_TOKEN无效或缺失、配额超限API 限流、未检测到内容图片可能为空白或确实无文字。以上错误在 SDK 层面对应有明确异常类型paddleocr/_api_client/errors.py理解它们有助于快速定位问题异常类型触发场景AuthErrorToken 缺失、无效或过期HTTP 401/403RateLimitError每日配额超限HTTP 429ServiceUnavailableError服务过载或网关超时HTTP 503/504InvalidRequestError请求参数非法HTTP 400JobFailedError服务端任务执行失败PollTimeoutError轮询等待任务完成超时ResultParseError返回载荷无法解析为预期结果类型总结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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考