让 AI 应用稳定做 OCR 和文档解析：PaddleOCR Agent Skills 安装完整指南

让 AI 应用稳定做 OCR 和文档解析：PaddleOCR Agent Skills 安装完整指南

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR

PaddleOCR 是一个轻量 OCR 工具箱，能把图片或 PDF 变成结构化数据，支持 100 多种语言。它的官方 Agent Skills 把"什么时候该识别、怎么调、结果怎么处理"打包成可按需加载的模块，装进支持 Skills 的 AI 应用（Claude Code、OpenClaw 等）后，你用一句自然语言就能让 AI 完成图片转文字、PDF 转 Markdown。本文带你把这两个 Skill 装好、配上 token，并看懂输出判断链路是否打通。

PaddleOCR Skill 怎么选：文字识别和文档解析用哪个

先问自己一个问题：你要的是"文字"，还是"结构"？

• 只要行级纯文本，附带检测框和置信度——截图、名片、普通扫描件，选paddleocr-text-recognition。
• 文档里有表格、公式、图表、多栏排版，或者你想要 Markdown 输出——发票、财报、论文，选paddleocr-doc-parsing。

一句话判断：目标是纯文本就用文字识别；要保留版面结构就用文档解析。paddleocr-text-recognition的 SKILL.md 里明确写了，含表格、公式、复杂版面的文档不要交给它。

安装前环境自检：先过三道关

安装 Skill 之前，先确认三件事，缺一样后面都会卡住：

1. Python 版本：执行python --version，看到 3.9 或更高就行。

2. 装好 PaddleOCR 本体：

   pip install "paddleocr>=3.7.0"

   这一步给你paddleocr命令行。Skill 内部调用的就是paddleocr api子命令，它把文件提交到官方托管服务、等任务跑完、打印结果——不跑本地推理，所以不需要 GPU，也不需要额外依赖。

3. 拿到 access token：登录百度 AI Studio，在账户设置的 accessToken 入口获取。

PaddleOCR Skill 安装三步：按你的 AI 应用挑一条

主路径：skillsCLI 全局安装（需要已装 Node.js）。命令会装到设备全局，装完各 AI 应用都能用：

npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-text-recognition -y npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-doc-parsing -y

只装一个 Skill 就保留对应那一行。这里有个高频坑：PaddleOCR 仓库体积大，网络慢时npx skills add容易超时失败。遇到就换本地路径安装——先把仓库克隆下来，再指向本地 skills 目录：

git clone https://gitcode.com/GitHub_Trending/pa/PaddleOCR npx skills add ./PaddleOCR/skills/paddleocr-text-recognition

skills/目录下就是两个 Skill 的源码，装哪个拷哪条。

其他两条路，看你的 AI 应用：

• 用 OpenClaw 的话：clawhub install paddleocr-text-recognition（文档解析同理），安装位置规则以 OpenClaw 官方文档为准。
• 以上都不适用：克隆仓库后，把skills/下对应目录手动拷到你 AI 应用指定的位置，具体位置参考该应用的 Skills 安装说明。

更多细节见 官方 skills 文档。

PaddleOCR access token 怎么配最快

环境变量只有一个必填：PADDLEOCR_ACCESS_TOKEN。可选的PADDLEOCR_BASE_URL用来改 API 服务地址，不配就走官方默认服务。

不同 AI 应用的填法：

• Claude Code：在项目根目录的.claude/settings.local.json加env字段，把<ACCESS_TOKEN>换成你的 token：

  { "env": { "PADDLEOCR_ACCESS_TOKEN": "<ACCESS_TOKEN>" } }

• OpenClaw：在~/.openclaw/openclaw.json的skills.entries里给每个 Skill 加"enabled": true和env中的 token，结构同上。

• 其他应用：直接把PADDLEOCR_ACCESS_TOKEN作为环境变量提供给应用即可；也可以不配环境变量，在单次调用时用--token参数显式传入。

用自然语言触发识别：怎么开口

配置完成后，直接用自然语言说任务，附上文件 URL 或本地路径。两个 Skill 的开口方式：

• 文字识别：提取这个文件中的全部文本：https://example.com/invoice.jpg，本地文件可以说提取本地文件 C:\docs\invoice.pdf 中的全部文本。
• 文档解析：解析这个 PDF，并返回主体内容和全部表格：https://example.com/report.pdf，或者解析本地文件 C:\docs\report.pdf，并返回完整结构化结果。

上面的 URL 和路径都是示例，换成你自己的。AI 应用背后实际执行的是paddleocr api命令，比如最小形态：

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

--model_type必填，取值ocr或doc_parsing；--file_url和--file_path二选一。想手动验证 Skill 的行为，可以照这条命令自己跑一遍，完整参数用paddleocr api --help查看。

怎么判断 PaddleOCR API 调用成功：看输出两个字段

paddleocr api成功时输出格式化 JSON，判断标准就两条：

• 文字识别：JSON 里有jobId和pages，每页的prunedResult中能看到rec_texts（行级文本）和rec_scores（置信度）。把rec_texts和文档原文逐行对一遍，内容对得上，说明链路通了。
• 文档解析：pages中每页有markdownText、markdownImages、outputImages，检查markdownText里的标题、段落、表格是否和原文一致。

指定--output result.json时，结果写入该文件并打印保存位置；不指定就打印到标准输出。

PaddleOCR 常见错误排查：token、配额、空白页三类

命令失败时，错误信息走标准错误流、退出码非零，这是判断调用失败的直接信号。SKILL.md 列出的三类高频错误：

• 🔑认证错误：PADDLEOCR_ACCESS_TOKEN缺失、无效或过期。先查环境变量配没配，token 是否来自 AI Studio 且没过期。
• 配额错误：API 限流或配额超出，稍后重试或检查账户配额。
• 未检测到内容：图片可能是空白页或不含文字，换一个有字的输入试试。

另有一条处理规则要留意：CLI 返回错误时，应该把具体问题告诉用户，而不是静默失败或悄悄退回 AI 应用自己的视觉能力。

结果慢？看输入长什么样。API 默认开着文档预处理（扭曲矫正use_doc_unwarping和方向分类use_doc_orientation_classify）。输入是平整、方向正确的截图或规范扫描件时，可以关掉提速：

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

但输入是弯曲或折叠文档的照片、有明显透视变形、方向不确定（旋转了 90/180/270 度）时，保持默认，别关。

PaddleOCR Skill 使用边界：两条红线

• 含表格、公式、图表或复杂版面的文档，别丢给paddleocr-text-recognition，交给paddleocr-doc-parsing。
• 向用户展示完整提取内容，内容超过 10,000 字符才允许省略。

底层依赖再确认一遍：Skill 调的是paddleocrCLI（paddleocr>=3.7.0提供），CLI 默认读PADDLEOCR_ACCESS_TOKEN环境变量，也支持--token显式传入。

最后拿一份手头的真实 PDF 或图片走一遍：把上面任一句自然语言提示丢给 AI 应用，输出 JSON 里出现与文档对得上的rec_texts，或markdownText与原文一致，整条链路就算真正跑通了。

【免费下载链接】PaddleOCRTurn any PDF or image document into structured data for your AI. A powerful, lightweight OCR toolkit that bridges the gap between images/PDFs and LLMs. Supports 100+ languages.项目地址: https://gitcode.com/GitHub_Trending/pa/PaddleOCR