企业官网建设流程全解析

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

这篇文章帮你在支持 Skills 的 AI 应用里，装好并配好 PaddleOCR 的两个官方 Agent Skills——文字识别与文档解析，再用一份真实文件跑通一次完整任务。前提：执行机装有 Python 3.9+，主路径安装需要 Node.js，且已拿到百度 AI Studio 的 access token。

先定目标：只取文字，还是连结构一起要

装之前先选 Skill，两者只装你需要的：

判断标准：目标是纯文本就选前者；文档含表格、公式或复杂版面就选后者。识别 Skill 的 SKILL.md 也明确要求不要处理含表格、公式或复杂版面的文档，两个 Skill 的完整规则在 skills 目录 下各自的 SKILL.md 文件里。

开工前备齐三样东西：Python、paddleocr 包、AI Studio token

1. 确认执行 Skill 的设备已安装 Python 3.9 或以上版本。Skill 的命令最终都落在paddleocrCLI 上，跑不了 Python 就跑不了任务。

2. 安装 PaddleOCR 3.7.0 及以上版本，它提供paddleocrCLI：

   pip install "paddleocr>=3.7.0"

   注意：paddleocr api是把文件提交到官方托管服务再等结果，不做本地推理，所以无需 GPU，也不用装额外依赖组。

3. 获取 access token：打开百度 AI Studio 账户设置中的 Access Token 页面（accessToken 入口），复制 token 备用。

安装：主路径一条命令，慢网改走本地克隆

主路径：npx skills 全局安装

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

只装其中一个 Skill 时，保留对应那条命令即可。

可选分支：网络慢或超时，先克隆仓库再本地安装

PaddleOCR 仓库较大，网络慢的环境下npx skills add可能因超时失败。遇到这种情况，先把仓库克隆到本地目录，再从本地路径装：

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

仓库里的skills/目录就是两个 Skill 的源码所在。

兜底：OpenClaw 走 clawhub，其余环境手动拷贝

如果你用 OpenClaw，安装位置与规则以其官方 Skills 文档为准，直接执行：

clawhub install paddleocr-text-recognition clawhub install paddleocr-doc-parsing

以上都不适用时：克隆仓库，把PaddleOCR/skills下对应的 Skill 目录拷贝到你 AI 应用指定的位置，具体拷贝到哪份，以该应用的安装文档为准（Claude Code、claude.ai、OpenClaw 各自有 Skills 安装说明）。

配置：PADDLEOCR_ACCESS_TOKEN 填进哪

按官方文档，环境变量只有两个：

• 必填PADDLEOCR_ACCESS_TOKEN（access token）。两个 Skill 的 frontmatter 都把它声明为必需环境变量（primaryEnv），缺失时 Skill 不会正确工作。
• 可选PADDLEOCR_BASE_URL（API base URL）。不改则默认使用官方服务地址。

部分应用的填法：

Claude Code：在项目根目录的.claude/settings.local.json里加env字段（<ACCESS_TOKEN>换成你在 AI Studio 拿到的 token）：

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

OpenClaw：在~/.openclaw/openclaw.json中为每个 Skill 置enabled: true并在env里填 token，装了两个就写两条：

{ "skills": { "entries": { "paddleocr-text-recognition": { "enabled": true, "env": { "PADDLEOCR_ACCESS_TOKEN": "<ACCESS_TOKEN>" } } } } }

应用不在上述范围时，直接把 token 以环境变量PADDLEOCR_ACCESS_TOKEN提供给它即可；单次调用也可以用--token参数显式传入。

调用：一句话让 AI 应用替你跑 paddleocr api

配置完成后，用自然语言描述任务并附上文件 URL 或本地路径。官方文档给出的示例提示词：

提取这个文件中的全部文本：https://example.com/invoice.jpg

提取本地文件 C:\docs\invoice.pdf 中的全部文本。

解析这个 PDF，并返回主体内容和全部表格：https://example.com/report.pdf

Skill 内部实际执行的是paddleocr api命令，理解其行为或手动验证时可以直接跑：

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

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

关键参数行为：--model_type必填，只接受ocr和doc_parsing两个值；--file_url与--file_path二选一，分别对应文件 URL 与本地路径。完整参数列表以paddleocr api --help的输出为准，详见官方 CLI 文档。

验证：先核对 JSON 字段，再认三种失败信号

命令成功时输出格式化 JSON。

文字识别（--model_type ocr）包含jobId和每页的prunedResult、ocrImageUrl，其中prunedResult内含rec_texts（行级文本）与rec_scores（置信度分数）：

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

文档解析（--model_type doc_parsing）包含jobId和每页的markdownText、markdownImages、outputImages：

{ "jobId": "job-xxx", "pages": [ { "markdownText": "# Title\n\nContent...", "markdownImages": { "img1": "https://..." }, "outputImages": { "layout1": "https://..." } } ] }

核对方法：看pages是否覆盖目标页码、rec_texts/markdownText是否与文档实际内容一致。若用--output指定了文件，CLI 会写入该文件并打印保存位置；未指定时打印到标准输出。

出错时信息进标准错误流并返回非零退出码，据此可判定失败。SKILL.md 列出的常见错误有三类：

1. 认证错误：PADDLEOCR_ACCESS_TOKEN无效或缺失——检查环境变量是否配置、token 是否来自 AI Studio 且未过期。
2. 配额错误：API 限流或配额超出。
3. 未检测到内容：图片可能是空白页或不含文字。

规则：CLI 返回错误时，向用户说明具体问题，不要静默失败，也不要回退到应用自身的视觉能力。

边界：哪些文档别用识别 Skill，预处理何时关

• paddleocr-text-recognition不适用于含表格、公式、图表或复杂版面的文档，这类任务改用paddleocr-doc-parsing。

• 结果展示规则：向用户展示完整提取内容，除非内容超过 10,000 字符才允许省略。

• Skill 依赖paddleocrCLI（由paddleocr>=3.7.0提供），CLI 默认读取PADDLEOCR_ACCESS_TOKEN，也可用--token显式传入。

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 度）。

验收标准

拿一份你手头的真实 PDF 或图片，按上文提示词跑一遍：输出中出现与文档实际内容一致的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