# 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
   ```