paddleocr-text-recognition

PaddleOCR 文字识别技能

何时使用此技能

触发关键词（路由）：中英文双语触发词已在上方 YAML description 中列出——使用该字段进行发现和路由。

使用此技能的场景：

• 从图片（截图、照片、扫描件）中提取文字
• 从 PDF 或文档图片中提取文字，目标是行/框级别文本，而非恢复表格网格、公式或完整阅读顺序布局
• 从指向图片/PDF 的 URL 或本地文件中提取文字

不要用于：

• 可直接作为文本读取的纯文本文件、代码文件或 Markdown 文档
• 包含表格、公式、图表或复杂布局的文档——请使用文档解析技能
• 不涉及图片转文字的任务

安装

脚本内联声明依赖（PEP 723）。无需单独安装步骤——uv 会自动解析依赖：

uv run scripts/ocr_caller.py --help

如何使用此技能

工作目录：以下所有 uv run scripts/... 命令均需在此技能根目录（包含本 SKILL.md 文件的目录）下运行。

基本工作流程

1. 确定输入来源：

   • 用户提供 URL：使用 --file-url 参数
   • 用户提供本地文件路径：使用 --file-path 参数

2. 执行 OCR：

   uv run scripts/ocr_caller.py --file-url "用户提供的URL" --pretty
   

   或对于本地文件：

   uv run scripts/ocr_caller.py --file-path "文件路径" --pretty
   

   性能说明：解析时间随文档复杂度增加。单页图片通常 1-3 秒完成；大型 PDF（50 页以上）可能需要几分钟。请预留足够时间，不要过早假设超时。

   默认行为：将原始 JSON 保存到临时文件：

   • 如果省略 --output，脚本自动保存到系统临时目录下
   • 默认路径模式：<system-temp>/paddleocr/text-recognition/results/result_<timestamp>_<id>.json
   • 如果提供 --output，则覆盖默认临时文件路径
   • 如果提供 --stdout，JSON 输出到标准输出，不保存文件
   • 在保存模式下，脚本在标准错误输出打印绝对保存路径：Result saved to: /absolute/path/...
   • 在默认/自定义保存模式下，读取并解析保存的 JSON 文件后再响应
   • 仅在明确希望跳过文件持久化时使用 --stdout

3. 解析 JSON 响应：

   • 在默认/自定义保存模式下，从脚本显示的保存文件路径加载 JSON
   • 检查 ok 字段：true 表示成功，false 表示错误
   • 提取文本：text 字段包含所有识别出的文字
   • 如果使用 --stdout，直接解析标准输出的 JSON
   • 处理错误：如果 ok 为 false，显示 error.message

4. 向用户展示结果：

   • 以可读格式显示提取的文本
   • 如果文本为空，图片可能不含文字
   • 在保存模式下，始终告知用户保存的文件路径以及完整原始 JSON 可在该处获取

提取后的操作

获得识别文本后的常见后续步骤：

• 保存到文件：将 text 字段写入 .txt 或 .md 文件
• 搜索内容：在保存的输出文件中搜索关键词
• 输入其他流程：text 字段是干净的纯文本，可直接用于下游处理
• 结果不佳：重试前请参阅下方“提高结果质量的技巧”

完整输出展示

始终向用户展示完整的识别文本。用户通常需要完整内容用于下游使用——截断会静默丢失数据，用户可能未注意到缺失。

• 显示整个 text 字段，无论多长
• 不要使用“以下是摘要”或“文本以……开头”等表述
• 不要用“...”截断，除非文本确实超过合理显示限制（>10,000 字符）

示例 - 正确：

用户：“从这张图片中提取文字”
智能体：我已从图片中提取文字。以下是完整内容：

[在此处显示完整文本]

示例 - 错误：

用户：“从这张图片中提取文字”
智能体：我在图片中找到了一些文字。以下是预览：
“敏捷的棕色狐狸……”（截断）

理解输出

脚本返回一个包含 ok、text、result 和 error 字段的 JSON 信封。使用 text 获取识别内容；result 包含用于调试的原始 API 响应。

完整模式和字段级详情请参见 references/output_schema.md。

原始结果位置（默认）：脚本在标准错误输出打印的临时文件路径

使用示例

示例 1：URL OCR

uv run scripts/ocr_caller.py --file-url "https://example.com/invoice.jpg" --pretty

示例 2：本地文件 OCR

uv run scripts/ocr_caller.py --file-path "./document.pdf" --pretty

示例 3：指定文件类型的 OCR

uv run scripts/ocr_caller.py --file-url "https://example.com/input" --file-type 1 --pretty

• --file-type 0：PDF
• --file-type 1：图片
• 如果省略，则根据文件扩展名自动检测。对于本地文件，需要识别的扩展名（.pdf、.png、.jpg、.jpeg、.bmp、.tiff、.tif、.webp）；否则请显式传递 --file-type。对于扩展名无法识别的 URL，服务会尝试推断。

示例 4：打印 JSON 而不保存

uv run scripts/ocr_caller.py --file-url "https://example.com/input" --stdout --pretty

首次配置

当 API 未配置时，脚本输出：

{
  "ok": false,
  "text": "",
  "result": null,
  "error": {
    "code": "CONFIG_ERROR",
    "message": "PADDLEOCR_OCR_API_URL not configured. Get your API at: https://paddleocr.com"
  }
}

配置流程：

1. 向用户显示确切的错误信息。

2. 引导用户获取凭证：访问 PaddleOCR 网站，点击 API，选择 PP-OCRv5 模型，选择语言，然后复制 API_URL 和 Token。它们对应以下环境变量：

   • PADDLEOCR_OCR_API_URL — 以 /ocr 结尾的完整端点 URL
   • PADDLEOCR_ACCESS_TOKEN — 40 位字母数字字符串

   可选配置 PADDLEOCR_OCR_TIMEOUT 用于请求超时。建议使用宿主应用的标准配置方法，而非在聊天中粘贴凭证。

3. 应用凭证——以下之一：

   • 用户已通过宿主 UI 配置：请用户确认，然后重试。
   • 用户在聊天中粘贴凭证：警告凭证可能存储在对话历史中，帮助用户使用宿主的标准配置方法持久化凭证，然后重试。

错误处理

所有错误均返回 ok: false 的 JSON。显示错误信息并停止——不要回退到自身的视觉能力。根据 error.code 和 error.message 识别问题：

认证失败（403）——error.message 包含 "Authentication failed"

• Token 无效，请重新配置正确的凭证

配额超限（429）——error.message 包含 "API rate limit exceeded"

• 每日 API 配额已用尽，通知用户等待或升级

不支持的格式——error.message 包含 "Unsupported file format"

• 文件格式不支持，请转换为 PDF/PNG/JPG

未检测到文字：

• text 字段为空
• 图片可能为空白、损坏或不含文字

提高结果质量的技巧

如果识别质量不佳：

• 低分辨率：提供更高分辨率的图片（≥300 DPI 对大多数印刷文本效果良好）
• 背景嘈杂：更干净的扫描件或截图通常比手机照片效果更好
• 检查置信度：原始 JSON（result.result.ocrResults[n].prunedResult.rec_scores）显示每行置信度分数——低值标识需要复核的不确定区域

参考文档

• references/output_schema.md — 完整输出模式、字段描述和命令示例

注意：模型版本、能力和支持的文件格式由您的 API 端点（PADDLEOCR_OCR_API_URL）及其官方 API 文档决定。

测试技能

要验证技能是否正常工作：

uv run scripts/smoke_test.py
uv run scripts/smoke_test.py --skip-api-test
uv run scripts/smoke_test.py --test-url "https://..."

第一种形式测试配置和 API 连通性。--skip-api-test 仅检查配置。--test-url 覆盖默认的示例图片 URL。