PaddleOCR Agent Skills 安装与使用指南让 AI 应用原生获得 OCR 与文档解析能力【免费下载链接】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 官方 Agent Skills 将 OCR 文字识别与文档解析的触发规则、调用步骤、配置要求和结果处理最佳实践打包为可按需加载的模块化能力帮助支持 Skills 的 AI 应用如 Claude Code、claude.ai、OpenClaw 等更稳定地完成文字识别与版面解析任务。本文以仓库内的docs/version3.x/integrations/skills.md为主干结合skills/目录下两个 Skill 的完整定义与paddleocrCLI 的源码实现系统讲解 Skill 的选择、安装、环境变量配置、自然语言调用方式、底层执行机制与结果处理规范读完即可在 AI 应用中集成官方 OCR / 文档解析能力。一、为什么需要 Agent Skills传统的 OCR 调用方式需要开发者自己编写脚本、处理鉴权、拼接参数并解析返回结果。Agent Skills 则把这些环节抽象为「按需加载的模块化能力」Skill 的SKILL.md文件中写明了触发条件trigger terms、调用命令paddleocr api、常用参数、输出格式与错误处理最佳实践。AI 应用加载 Skill 后用户只需用自然语言描述任务模型便会自动路由到正确的 Skill 并执行标准调用。从仓库结构看两个官方 Skill 位于 skills/paddleocr-text-recognition/SKILL.md 与 skills/paddleocr-doc-parsing/SKILL.md其目录说明见 skills/README_cn.md完整安装文档即本文所依据的 docs/version3.x/integrations/skills.md。二、先选择合适的 Skill在安装之前先根据任务需求确定使用哪一个 Skill。官方文档给出的选择依据如下需求推荐 Skill输出只想提取图片或 PDF 中的纯文本paddleocr-text-recognition行级文本及对应边界框和置信度分数需要保留标题、段落、表格、公式等文档结构paddleocr-doc-parsingMarkdown / 结构化结果三、两个官方 Skill 详解3.1paddleocr-text-recognition文字识别用于识别图片、扫描件与 PDF 中的文字输出精确的机器可读字符串包含行级文本以及可选的边界框bbox坐标。根据 SKILL.md 中的定义该 Skill 适用于从图片截图、照片、扫描件中提取文本从 PDF 或文档图片中提取行级 / 框级文本处理指向图片或 PDF 的 URL 或本地文件。其触发词Trigger terms覆盖中英文场景OCR、文字识别、图片转文字、截图识字、提取图中文字、扫描识字、识字、纯文字、plain text extraction、坐标、检测框、bbox、bounding box、image to text、screenshot、photo scan、recognize text 等。Skill 元数据同时声明了对paddleocr二进制与PADDLEOCR_ACCESS_TOKEN环境变量的依赖。注意需要保留表格、公式、图表或复杂版面结构时不要使用该 Skill应改用文档解析 Skill。3.2paddleocr-doc-parsing文档解析用于解析复杂文档版面并转换为 Markdown 或结构化结果。根据 SKILL.md该 Skill 适用于含表格的文档发票、财报、电子表格含数学公式的文档学术论文、科学文档含图表与示意图的文档多栏排版文档报纸、杂志、宣传册需要版面分析layout analysis的复杂文档结构。其输出能力包括单元格级精度的表格提取、公式转 LaTeX、图形 / 印章 / 图表识别、页眉页脚处理、多栏版面与正确阅读顺序还原。触发词包括文档解析、版面分析、版面还原、表格提取、公式识别、多栏排版、扫描件结构化、发票、财报、复杂 PDF、PDF转Markdown、图表、阅读顺序、reading order、formula、LaTeX、layout parsing、structure extraction、PP-StructureV3、PaddleOCR-VL 等。四、安装前准备Python 版本执行 Skill 的设备需安装 Python 3.9 或以上版本。PaddleOCR 版本Skills 依赖 PaddleOCR 3.7.0安装命令pip install paddleocr3.7.0获取 access token访问 AI Studio 的 Access Token 页面https://aistudio.baidu.com/account/accessToken获取后续配置到环境变量中。五、安装到 AI 应用以下说明涵盖两个 Skill只需安装并配置自己需要的那个即可。仓库提供了三种安装方式。方式一通过skillsCLI 安装skillsCLI 可将 Skill 全局安装到设备上安装后各 AI 应用均可使用。使用前需要先安装 Node.js。npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-text-recognition -y npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-doc-parsing -y网络超时处理由于 PaddleOCR 仓库较大在网络较慢的环境下npx skills add可能因超时而失败。如遇此情况可先将仓库克隆到本地再从本地路径安装git clone https://gitcode.com/paddlepaddle/PaddleOCR.git npx skills add ./PaddleOCR/skills/paddleocr-text-recognition npx skills add ./PaddleOCR/skills/paddleocr-doc-parsing方式二通过clawhub安装OpenClawOpenClaw 用户可通过clawhub安装clawhub install paddleocr-text-recognition clawhub install paddleocr-doc-parsing方式三手动安装如果上述方式不适用也可以先克隆仓库再手动将 Skill 目录拷贝到 AI 应用指定的位置git clone https://gitcode.com/paddlepaddle/PaddleOCR.gitSkill 源码位于仓库的skills目录即skills/paddleocr-text-recognition/与skills/paddleocr-doc-parsing/。手动安装时请参考所用 AI 应用的 Skills 安装文档例如 Claude Code、claude.ai、OpenClaw 官方文档中关于 Skills 的章节。六、配置环境变量安装完成后需要配置如下环境变量必填PADDLEOCR_ACCESS_TOKENaccess token可选PADDLEOCR_BASE_URLAPI base URL不配置时默认使用官方服务获取 access token 的方式同上访问 AI Studio 的 Access Token 页面。部分 AI 应用的配置方式如下Claude Code在项目的.claude/settings.local.json中添加env字段{ env: { PADDLEOCR_ACCESS_TOKEN: ACCESS_TOKEN } }OpenClaw在~/.openclaw/openclaw.json中添加 Skill 配置{ skills: { entries: { paddleocr-text-recognition: { enabled: true, env: { PADDLEOCR_ACCESS_TOKEN: ACCESS_TOKEN } }, paddleocr-doc-parsing: { enabled: true, env: { PADDLEOCR_ACCESS_TOKEN: ACCESS_TOKEN } } } } }从源码看这两个环境变量的读取逻辑位于 paddleocr/_api_client/client.pyPaddleOCRClient构造时优先使用显式传入的token/base_url参数否则回退到PADDLEOCR_ACCESS_TOKEN环境变量base URL 则依次尝试显式参数、PADDLEOCR_BASE_URL环境变量最后才使用内置的默认官方服务地址。若 token 缺失客户端会直接抛出鉴权错误AuthError这就是配置缺失时 Skill 会报「Authentication: token invalid or missing」的原因。七、使用示例配置完成后可以直接用自然语言描述任务并附上文件 URL 或本地路径让 AI 应用调用对应 Skill。例如paddleocr-text-recognition解析 URL 示例提取这个文件中的全部文本https://example.com/invoice.jpg解析本地文件示例提取本地文件 C:\docs\invoice.pdf 中的全部文本。paddleocr-doc-parsing解析 URL 示例解析这个 PDF并返回主体内容和全部表格https://example.com/report.pdf解析本地文件示例解析本地文件 C:\docs\report.pdf并返回完整结构化结果。八、Skill 背后的命令paddleocr api两个 Skill 最终都通过paddleocr api子命令调用 PaddleOCR 官方云端 API。该子命令在 paddleocr/_cli.py 中注册具体参数定义位于 paddleocr/_api_client/cli.py。--model_type为必选参数取值只能是ocr或doc_parsing与两个 Skill 一一对应。8.1 基本调用OCR 基本调用URL 输入paddleocr api \ --model_type ocr \ --file_url https://example.com/image.pngOCR 基本调用本地文件输入paddleocr api \ --model_type ocr \ --file_path ./document.pdf文档解析基本调用URL 输入paddleocr api \ --model_type doc_parsing \ --file_url https://example.com/report.pdf文档解析基本调用本地文件输入paddleocr api \ --model_type doc_parsing \ --file_path ./document.pdf8.2 常用参数详解结合 SKILL.md 与 cli.py 中的定义常用参数如下参数说明--model_type必填任务类型ocr或doc_parsing--model模型名称如PP-OCRv5、PP-StructureV3不指定时使用默认模型--file_url待处理文件的 URL--file_path待处理文件的本地路径--base_urlAPI 服务 base URL覆盖环境变量PADDLEOCR_BASE_URL--tokenaccess token覆盖环境变量PADDLEOCR_ACCESS_TOKEN--output输出 JSON 文件路径缺省时打印到 stdout--page_ranges要解析的页码范围如1-5,10,15-20或2,4-6--request_timeout单次 HTTP 请求超时秒默认 300.0--poll_timeout等待远程任务完成的总超时秒默认 600.0--save_resources保存结果引用资源的目录--overwrite_resources保存资源时覆盖已有文件--batch_id可选的批量标识用于查询相关任务--visualize是否生成结果可视化图片True/False--prettify_markdown是否美化 Markdown 输出doc_parsingTrue/False--use_doc_orientation_classify是否启用文档方向分类预处理True/False--use_doc_unwarping是否启用文档拉平去畸变预处理True/False--use_textline_orientation是否启用文本行方向检测OCRTrue/False--text_det_limit_side_len文本检测的图片边长限制--text_det_limit_type边长限制类型min或max--text_rec_score_thresh文本识别结果的置信度阈值文档解析专属开关doc_parsing模式见 cli.py参数说明--use_layout_detection是否启用版面检测--use_seal_recognition是否启用印章识别--use_table_recognition是否启用表格识别PP-StructureV3--use_formula_recognition是否启用公式识别PP-StructureV3--use_chart_recognition是否启用图表识别8.3 指定模型的调用示例指定模型做 OCR来自 SKILL.mdpaddleocr api \ --model_type ocr \ --model PP-OCRv5 \ --file_path ./report.pdf指定模型做文档解析来自 SKILL.mdpaddleocr api \ --model_type doc_parsing \ --model PP-StructureV3 \ --file_path ./report.pdf指定页码范围与输出文件paddleocr api \ --model_type ocr \ --file_path ./large.pdf \ --page_ranges 1-5,10,15-20 paddleocr api \ --model_type doc_parsing \ --file_url https://... \ --output result.json \ --save_resources ./resources paddleocr api \ --model_type doc_parsing \ --file_path ./document.pdf \ --prettify_markdown True8.4 支持的模型清单从 paddleocr/_api_client/models.py 的Model枚举可以看到当前 CLI 支持的模型OCR 任务PP-OCRv5、PP-OCRv5-latin、PP-OCRv6其中PP-OCRv6是ocr模式的默认模型见 cli.py文档解析任务PP-StructureV3、PaddleOCR-VL、PaddleOCR-VL-1.5、PaddleOCR-VL-1.6默认模型为PaddleOCR-VL-1.6见 cli.py。源码中通过is_ocr_model/is_vl_model对模型与任务类型做了匹配校验如果为ocr任务指定了不支持的非 OCR 模型CLI 会直接报错退出见 cli.py文档解析模式下若指定的是 VL 系列模型则使用PaddleOCRVLOptions包含layout_threshold、temperature、top_p、max_new_tokens等生成式参数否则使用PPStructureV3Options见 models.py。九、关闭预处理的加速用法两个 Skill 都重点强调了「预处理开关」的用法。默认情况下API 会启用文档预处理拉平去畸变 方向分类。对于平整、方向正确的图片截图、规范扫描件可以关闭预处理以加快速度# 关闭预处理更快适用于平整/方向正确的图片 paddleocr api \ --model_type ocr \ --file_path ./document.pdf \ --use_doc_unwarping False \ --use_doc_orientation_classify False paddleocr api \ --model_type doc_parsing \ --file_path ./document.pdf \ --use_doc_unwarping False \ --use_doc_orientation_classify False建议保持预处理开启的场景输入是弯曲或折叠文档的照片文档存在明显的透视畸变方向不确定可能旋转了 90/180/270 度。从 CLI 源码看这些布尔参数通过str2bool解析见 cli.py并分别注入OCROptions/PPStructureV3Options/PaddleOCRVLOptions最终随请求 payload 以驼峰命名snake_to_camel发送给服务端见 models.py。十、输出格式与结果保存10.1 OCR 输出格式ocr任务返回每个页面的行级文本、置信度分数与 OCR 可视化图片 URL结构定义见 paddleocr/_api_client/results.py 与 cli.py{ jobId: job-xxx, pages: [ { prunedResult: { rec_texts: [Line 1, Line 2], rec_scores: [0.98, 0.95] }, ocrImageUrl: https://... } ] }10.2 文档解析输出格式doc_parsing任务返回每页的 Markdown 文本、Markdown 图片映射与版面可视化图片 URL见 results.py 与 cli.py{ jobId: job-xxx, pages: [ { markdownText: # Title\n\nContent..., markdownImages: { img1: https://..., img2: https://... }, outputImages: { layout1: https://... } } ] }10.3 结果与资源的落盘保存CLI 提供两个层面的保存能力--output result.json将完整 JSON 结果写入文件缺省时打印到 stdout--save_resources ./resources将结果中引用的资源如 Markdown 图片、版面可视化图下载到本地目录--overwrite_resources可控制是否覆盖已有文件。落盘逻辑由save_ocr_result_resources/save_document_parsing_result_resources实现见 cli.py。十一、底层执行机制异步任务与轮询从 paddleocr/_api_client/client.py 的类注释可以看出PaddleOCRClient是一个「同步阻塞客户端内部封装了异步任务 API」执行链路为提交submit→ 轮询poll→ 获取结果fetch。具体到ocr()与parse_document()方法见 client.py流程如下解析并校验模型resolve_ocr_model/resolve_document_model校验输入来源validate_input_sourcefile_url与file_path必须二选一见 client.py构造选项 payloadoptions.to_payload()未传选项时使用default_payload(model)通过submit_urlURL 输入或submit_file本地文件上传提交任务拿到job_id由Poller以poll_timeout默认 600 秒为总上限轮询任务状态直到完成解析 JSONL 结果数据封装为OCRResult/DocParsingResult。这也解释了 CLI 参数中--request_timeout单次 HTTP 请求超时与--poll_timeout等待任务完成的总超时的区别前者控制每次请求的等待后者控制整个异步任务的等待上限。十二、结果展示与错误处理的最佳实践两个 Skill 的Important Notes部分对 AI 应用的输出行为提出了明确规范这也是接入方应该遵守的约定展示完整结果始终向用户展示完整的提取内容除非内容超过 10,000 字符否则不要用...截断处理多页文档时可在必要时总结但用户明确要求时需提供完整结果。优雅处理错误当 CLI 返回错误时应告知用户具体问题而不是静默失败或退回到模型自身的视觉能力。常见错误类型包括鉴权错误PADDLEOCR_ACCESS_TOKEN无效或缺失对应源码中 token 缺失时的AuthError配额错误API 限流rate limit exceeded未检测到内容图片可能为空白或不含文字No content detected。从源码实现看CLI 的错误处理策略是客户端构造失败、请求异常均打印错误信息到 stderr 并以非零状态码退出见 [cli.py](https://link.gitcode.com/i/64adb104b5a1fe5a5009b37ff9fed5ce#L219-L223, L314-L316)因此 Skill 接入方可以直接依据退出码与 stderr 文案向用户反馈。十三、进一步探索查看两个 Skill 的完整定义skills/paddleocr-text-recognition/SKILL.md、skills/paddleocr-doc-parsing/SKILL.md查看 Skills 目录说明skills/README_cn.md查看paddleocr api全部参数运行paddleocr api --help阅读 CLI 参数与执行逻辑paddleocr/_api_client/cli.py阅读模型枚举、任务类型与选项校验paddleocr/_api_client/models.py阅读同步客户端与异步任务轮询机制paddleocr/_api_client/client.py、paddleocr/_api_client/poller.py阅读结果数据结构paddleocr/_api_client/results.py了解更多云端 API 能力与 CLI 用法可参考仓库内 version3.x 文档中关于 PaddleOCR 官方 API 的章节paddleocr api --help亦有指引。【免费下载链接】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），仅供参考