# ppocrv5-api-skill

> 此技能用于从图片或PDF中提取文字。当用户需要OCR识别图像内容（截图、照片、扫描件、 发票、表单等）或从图片URL中读取文本时触发。不适用于纯文本文件或代码文件。

- Author: Aidenwu0209
- Repository: Aidenwu0209/ppocrv5-api-skill
- Version: 20260124114033
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/Aidenwu0209/ppocrv5-api-skill
- Web: https://mule.run/skillshub/@@Aidenwu0209/ppocrv5-api-skill~ppocrv5-api-skill:20260124114033

---

---
name: ppocrv5-api-skill
description: >
  此技能用于从图片或PDF中提取文字。当用户需要OCR识别图像内容（截图、照片、扫描件、
  发票、表单等）或从图片URL中读取文本时触发。不适用于纯文本文件或代码文件。
---

# PP-OCRv5 API 技能

通过 Paddle AI Studio PP-OCRv5 API 从图片和 PDF 中提取文字。

## 路径约定

此技能的脚本位于 `scripts/` 目录下。执行命令时：

1. 使用 Glob 工具定位 `ocr_caller.py` 的绝对路径
2. 所有路径参数使用绝对路径
3. 输出文件保存到 skill 目录下

```
Glob(pattern="**/ppocrv5-api-skill/scripts/ocr_caller.py")
```

## 工作流程

### 步骤 1：定位并验证输入文件

使用 Glob 搜索用户提到的文件：

```
Glob(pattern="**/*关键词*", path="可能的目录")
```

若用户未提供路径，要求用户明确指定。

### 步骤 2：执行 OCR

**命令格式（所有参数使用绝对路径）：**

```bash
python "脚本绝对路径\ocr_caller.py" --file-path "文件绝对路径" --auto-output --pretty
```

**URL 输入：**

```bash
python "脚本绝对路径\ocr_caller.py" --file-url "https://..." --auto-output --pretty
```

**关键参数：**
- `--auto-output` — 自动生成输出路径：`output/日期/文件名_时分秒.json`
- `--pretty` — 格式化 JSON 输出

**中文文件名：** 脚本会自动处理中文文件名（复制到临时目录，OCR 完成后自动清理），无需手动操作。

**输出目录结构：**
```
ppocrv5-api-skill/
└── output/
    └── 2026-01-23/
        ├── 简历_104531.json
        ├── 发票_112045.json
        └── scan_143022.json
```

**避免以下错误用法：**
- `cd 目录 && python script.py` — Windows 下反斜杠会被吃掉

### 步骤 3：提取识别文本

**输出文件位置：** 使用 `--auto-output` 后，结果保存在 `output/日期/` 目录。从命令日志中查找 `结果已保存到:` 获取完整路径。

**【禁止】不要使用 Read 读取 OCR 结果文件** — 文件通常很大（数千行），会超过 token 限制并显示红色错误。

**【必须】始终使用 Grep 提取文本内容：**

```
Grep(pattern="\"rec_texts\"", path="输出文件路径.json", output_mode="content", -A=1)
```

这会返回所有 `rec_texts` 数组，包含识别的文本行。

**解析示例（仅供理解，无需执行）：**

```python
if result["errorCode"] != 0:
    # 处理错误: result["errorMsg"]
    return

all_text = []
for page in result["result"]["ocrResults"]:
    texts = page["prunedResult"]["rec_texts"]
    all_text.extend(texts)

full_text = "\n".join(all_text)
```

### 步骤 4：展示结果

**【强制要求】完整输出所有识别文本**

向用户展示 OCR 结果时，必须遵守以下规则：

1. **完整输出** — 输出所有识别到的文本，一字不漏
2. **禁止省略** — 不得使用 "..." 省略中间内容
3. **禁止截断** — 不得只显示前 N 行或后 N 行
4. **禁止摘要** — 不得生成内容概括或总结
5. **禁止缩减** — 即使文本很长（数千行），也必须全部显示

**正确做法：**
```
以下是识别到的完整内容：

第一行文本
第二行文本
第三行文本
...（实际输出所有行，这里的...只是示例）
最后一行文本

完整 JSON 已保存到：output/2026-01-23/简历_104531.json
```

**错误做法（禁止）：**
```
识别到 500 行文本，以下是摘要：...     ← 禁止
前 10 行：... 后 10 行：...            ← 禁止
内容较长，已保存到文件，请自行查看     ← 禁止
```

**最后告知用户 JSON 文件的保存位置。**

## 错误处理

| 错误现象 | 原因 | 解决方法 |
|---------|------|---------|
| 路径无反斜杠 | 使用了 `cd &&` | 改用绝对路径直接调用 |
| 文件名 `◆◆◆` 乱码 | 中文文件名（旧版本） | 更新脚本，现已自动处理 |
| 终端日志 `◆◆◆` 乱码 | Windows GBK 编码 | 已修复，或设置 `PYTHONIOENCODING=utf-8` |
| `exceeds maximum allowed tokens` | 结果文件太大 | 用 Grep 提取 rec_texts，不要用 Read |
| `API_URL not configured` | 缺少配置 | 运行 `scripts/configure.py` |
| `errorCode: 403` | Token 无效 | 重新配置凭据 |
| `errorCode: 429` | 配额超限 | 等待或升级配额 |
| `rec_texts` 为空 | 图片无文本 | 告知用户未检测到文本 |

## 首次配置

若出现配置错误，运行配置脚本：

```bash
python "脚本目录\configure.py"
```

按提示输入 API_URL 和 PADDLE_OCR_TOKEN。

验证配置：

```bash
python "脚本目录\smoke_test.py"
```

## 模式选择

| 模式 | 适用场景 | 参数 |
|------|---------|------|
| auto | 自适应质量（默认推荐） | 无需指定 |
| fast | 清晰扫描件、截图 | `--mode fast` |
| quality | 照片、手写、模糊文档 | `--mode quality` |

## 响应格式

```json
{
  "errorCode": 0,
  "errorMsg": "",
  "logId": "xxx",
  "result": {
    "ocrResults": [{
      "prunedResult": {
        "rec_texts": ["第一行", "第二行"],
        "rec_scores": [0.98, 0.95],
        "rec_boxes": [[x1,y1,x2,y2], ...]
      }
    }]
  }
}
```

## 高级选项

```bash
--max-attempts 2          # 最大尝试次数（默认3）
--quality-target 0.80     # 目标质量分数（默认0.72）
--budget-ms 15000         # 时间预算毫秒（默认25000）
--return-raw-provider     # 包含原始提供商响应
--visualize               # 请求检测区域可视化
```

## 参考文档

深入了解时加载：
- `references/agent_policy.md` — Auto 模式策略和质量评分
- `references/provider_api.md` — API 详细文档