178 lines
5.5 KiB
Markdown
178 lines
5.5 KiB
Markdown
# PaddleOCR 图文识别技能
|
||
|
||
`OCR` `文字识别` `文档解析` `PaddleOCR` `AI工具`
|
||
|
||
# PaddleOCR 技能
|
||
|
||
[English](./README.md) | [简体中文](./README_cn.md)
|
||
|
||
本目录包含官方 PaddleOCR Agent 技能，可集成到 Claude Code 等 AI 应用中，实现图片/PDF 的 OCR 文字提取和版面感知的文档解析。
|
||
|
||
## 包含的技能
|
||
|
||
- `paddleocr-text-recognition`：从图片/PDF 中提取文字。
|
||
- `paddleocr-doc-parsing`：文档解析，将图片/PDF 转换为 Markdown。
|
||
|
||
## 前置条件
|
||
|
||
1. 运行技能的设备上需安装 Python 3.8 或更高版本。
|
||
2. 这些技能依赖 PaddleOCR 官方 API，需要 API 凭据。访问 [PaddleOCR 官网](https://www.paddleocr.com)，点击 **API**，选择所需模型，复制 `API_URL` 和 `Token`，分别对应 API 地址和用于认证的访问令牌。各技能支持的模型如下：
|
||
- `paddleocr-text-recognition`：`PP-OCRv5`
|
||
- `paddleocr-doc-parsing`：`PP-StructureV3`、`PaddleOCR-VL`、`PaddleOCR-VL-1.5`
|
||
|
||
## 在 AI 应用中使用
|
||
|
||
> 以下说明涵盖两个技能，按需安装和配置所需技能即可。
|
||
|
||
### 安装到 AI 应用
|
||
|
||
#### 方式一：通过 `skills` CLI 安装
|
||
|
||
`skills` CLI 可将技能全局安装到设备上，供所有 AI 应用使用。需要安装 [Node.js](https://nodejs.org/en/download)。
|
||
|
||
```shell
|
||
npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-text-recognition -y
|
||
npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-doc-parsing -y
|
||
```
|
||
|
||
> 本仓库体积较大，网络较慢时 `npx skills add` 可能超时。若出现此问题，请先在本地克隆仓库，再从本地路径安装：
|
||
>
|
||
> ```shell
|
||
> git clone https://github.com/PaddlePaddle/PaddleOCR.git
|
||
> npx skills add ./PaddleOCR/skills/paddleocr-text-recognition
|
||
> ```
|
||
|
||
#### 方式二：通过 `clawhub`（OpenClaw）安装
|
||
|
||
```shell
|
||
clawhub install paddleocr-text-recognition
|
||
clawhub install paddleocr-doc-parsing
|
||
```
|
||
|
||
详见 [OpenClaw 技能文档](https://docs.openclaw.ai/tools/skills)。
|
||
|
||
#### 方式三：手动安装
|
||
|
||
如以上方式不可用，可克隆仓库后手动将技能目录复制到 AI 应用所需位置（需安装 [Git](https://git-scm.com/downloads)）：
|
||
|
||
```shell
|
||
git clone https://github.com/PaddlePaddle/PaddleOCR.git
|
||
```
|
||
|
||
克隆完成后，技能源码位于 `PaddleOCR/skills` 目录下。请参考对应 AI 应用的文档完成安装：
|
||
|
||
- Claude Code：<https://code.claude.com/docs/en/skills>
|
||
- claude.ai：<https://support.claude.com/en/articles/12512180-use-skills-in-claude>
|
||
- OpenClaw：<https://docs.openclaw.ai/tools/skills>
|
||
|
||
### 配置环境变量
|
||
|
||
安装完成后，需配置必要的环境变量以使技能正常工作。各技能所需变量如下：
|
||
|
||
| 技能 | 必填 | 可选 |
|
||
| --- | --- | --- |
|
||
| `paddleocr-text-recognition` | `PADDLEOCR_OCR_API_URL`（API 地址）、`PADDLEOCR_ACCESS_TOKEN`（访问令牌） | `PADDLEOCR_OCR_TIMEOUT`（API 请求超时时间） |
|
||
| `paddleocr-doc-parsing` | `PADDLEOCR_DOC_PARSING_API_URL`（API 地址）、`PADDLEOCR_ACCESS_TOKEN`（访问令牌） | `PADDLEOCR_DOC_PARSING_TIMEOUT`（API 请求超时时间） |
|
||
|
||
以下为部分 AI 应用的配置方式：
|
||
|
||
- **Claude Code**：在项目的 `.claude/settings.local.json` 中添加 `env` 字段：
|
||
|
||
```json
|
||
{
|
||
"env": {
|
||
"PADDLEOCR_ACCESS_TOKEN": "<ACCESS_TOKEN>",
|
||
"PADDLEOCR_OCR_API_URL": "<OCR_API_URL>",
|
||
"PADDLEOCR_DOC_PARSING_API_URL": "<DOC_PARSING_API_URL>"
|
||
}
|
||
}
|
||
```
|
||
|
||
- **OpenClaw**：在 `~/.openclaw/openclaw.json` 中添加技能配置：
|
||
|
||
```json
|
||
{
|
||
"skills": {
|
||
"entries": {
|
||
"paddleocr-text-recognition": {
|
||
"enabled": true,
|
||
"env": {
|
||
"PADDLEOCR_OCR_API_URL": "<OCR_API_URL>",
|
||
"PADDLEOCR_ACCESS_TOKEN": "<ACCESS_TOKEN>"
|
||
}
|
||
},
|
||
"paddleocr-doc-parsing": {
|
||
"enabled": true,
|
||
"env": {
|
||
"PADDLEOCR_DOC_PARSING_API_URL": "<DOC_PARSING_API_URL>",
|
||
"PADDLEOCR_ACCESS_TOKEN": "<ACCESS_TOKEN>"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 使用示例
|
||
|
||
配置完成后，用自然语言描述 OCR 或文档解析任务，并提供文件 URL 或本地路径，AI 应用即可调用对应技能。
|
||
|
||
**paddleocr-text-recognition**
|
||
|
||
URL 示例：
|
||
|
||
```text
|
||
提取此文件中的所有文字：https://example.com/invoice.jpg
|
||
```
|
||
|
||
本地文件示例：
|
||
|
||
```text
|
||
提取本地文件 C:\docs\invoice.pdf 中的所有文字
|
||
```
|
||
|
||
**paddleocr-doc-parsing**
|
||
|
||
URL 示例：
|
||
|
||
```text
|
||
解析此 PDF 并返回正文内容及所有表格：https://example.com/report.pdf
|
||
```
|
||
|
||
本地文件示例：
|
||
|
||
```text
|
||
解析本地文件 C:\docs\report.pdf 并返回完整结构化输出。
|
||
```
|
||
|
||
## 本地测试
|
||
|
||
本节介绍如何在本地运行冒烟测试，以验证技能是否正常工作。
|
||
|
||
> 以下示例涵盖两个技能，按需运行对应命令即可。
|
||
|
||
请确保当前工作目录为包含本文件的目录。
|
||
|
||
1. 安装依赖。
|
||
|
||
```shell
|
||
python -m pip install -r paddleocr-text-recognition/scripts/requirements.txt
|
||
python -m pip install -r paddleocr-doc-parsing/scripts/requirements.txt
|
||
# 可选：仅在使用文档文件优化功能时需要
|
||
python -m pip install -r paddleocr-doc-parsing/scripts/requirements-optimize.txt
|
||
```
|
||
|
||
2. 配置环境变量（变量列表见[配置环境变量](#配置环境变量)）。
|
||
|
||
```shell
|
||
export PADDLEOCR_OCR_API_URL="<OCR_API_URL>"
|
||
export PADDLEOCR_ACCESS_TOKEN="<ACCESS_TOKEN>"
|
||
export PADDLEOCR_DOC_PARSING_API_URL="<DOC_PARSING_API_URL>"
|
||
```
|
||
|
||
3. 运行冒烟测试脚本。
|
||
|
||
```shell
|
||
python paddleocr-text-recognition/scripts/smoke_test.py
|
||
python paddleocr-doc-parsing/scripts/smoke_test.py
|
||
``` |