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 provided by user" --pretty
   

   或用于本地文件：

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

   性能说明：解析时间随文档复杂度而变化。单页图像通常需要 1-3 秒；大型 PDF（50+ 页）可能需要几分钟。请留出充足时间，不要过早认为发生了超时。

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

   • 如果省略 --output，脚本会自动将文件保存到系统临时目录下
   • 默认路径格式：<system-temp>/paddleocr/text-recognition/results/result_<timestamp>_<id>.json
   • 如果提供 --output，则会覆盖默认的临时文件保存位置
   • 如果提供 --stdout，则会将 JSON 输出到 stdout，且不保存文件
   • 在保存模式下，脚本会将保存的绝对路径打印到 stderr：Result saved to: /absolute/path/...
   • 在默认/自定义保存模式下，回复前先读取并解析已保存的 JSON 文件
   • 仅在明确需要跳过文件持久化时使用 --stdout

3. 解析 JSON 响应：

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

4. 向用户呈现结果：

   • 以易读的格式显示提取出的文本
   • 如果文本为空，图像可能不含文本
   • 在保存模式下，务必告知用户保存的文件路径，并说明其中包含完整的原始 JSON

提取后可以做什么

识别出文本后，常见的后续步骤包括：

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

完整显示输出

始终向用户显示完整的识别文本。用户通常需要完整内容用于后续处理——截断内容会悄无声息地丢失他们可能不会察觉的数据。

• 显示完整的 text 字段，无论内容有多长
• 不要使用“以下是摘要”或“文本开头是……”之类的说法
• 除非文本确实超出合理的显示限制（>10,000 字符），否则不要用“...”截断

示例 - 正确：

User: "Extract the text from this image"
Agent: I've extracted the text from the image. Here's the complete content:

[Display the entire text here]

示例 - 错误：

User: "Extract the text from this image"
Agent: I found some text in the image. Here's a preview:
"The quick brown fox..." (truncated)

了解输出

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

完整架构和字段级详情请参阅 references/output_schema.md。

原始结果位置（默认）：脚本通过 stderr 打印的临时文件路径

替代方案：paddleocr CLI

此镜像默认使用打包的 scripts/ocr_caller.py。上游 PaddleOCR 项目（自 PR #18090 起，2026-06-03）也提供了可直接调用同一 API 的官方 CLI。如果已安装 paddleocr 包，可将其作为直接替代方案使用，无需 uv run 或本地脚本。

安装（仅需一次）：

pip install "paddleocr>=3.7.0"

环境：CLI 只需要 PADDLEOCR_ACCESS_TOKEN。它会在内部解析 API 端点，因此使用 CLI 时不需要设置 PADDLEOCR_OCR_API_URL（脚本仍需要该 URL）。

基本 OCR：

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

# From local file
paddleocr api --model_type ocr --file_path "./document.pdf"

常用选项：

# Specific model
paddleocr api --model_type ocr --model PP-OCRv5 --file_path "./report.pdf"

# Disable preprocessing (faster, for flat/well-oriented images)
paddleocr api --model_type ocr --file_path "./document.pdf" \
  --use_doc_unwarping False --use_doc_orientation_classify False

# Page ranges
paddleocr api --model_type ocr --file_path "./large.pdf" --page_ranges "1-5,10,15-20"

# Save result to file
paddleocr api --model_type ocr --file_url "https://..." --output result.json

CLI 输出格式——与脚本信封不同：

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

CLI 会将 {jobId, pages:[...]} 打印到 stdout。它不会将响应包装在脚本的 {ok, text, result, error} 信封中，不会自动保存到临时文件，也不会为你拼接 text。如果切换使用方式，请相应更新解析逻辑。

脚本与 CLI——一览：

	脚本（默认）	paddleocr CLI（替代方案）
安装	uv 解析 PEP 723 内联依赖	pip install "paddleocr>=3.7.0"
所需环境变量	PADDLEOCR_OCR_API_URL + PADDLEOCR_ACCESS_TOKEN	仅需 PADDLEOCR_ACCESS_TOKEN
入口	uv run scripts/ocr_caller.py ...	paddleocr api --model_type ocr ...
输出	{ok, text, result, error} 信封，自动保存到临时文件	{jobId, pages:[...]}，输出到 stdout
结果位置	stderr 打印的路径（或 --output/--stdout）	stdout（或 --output）
最适用于	Skills 运行环境、适合离线使用、无需额外安装	已安装 paddleocr，希望使用上游规范流程

运行 paddleocr api --help 查看完整选项列表。

使用示例

示例 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 配置：请用户确认，然后重试。
   • 用户在聊天中粘贴凭据：提醒用户凭据可能会保存在对话记录中，帮助用户使用宿主的标准配置方法保存凭据，然后重试。

错误处理

所有错误均以 JSON 格式返回，且包含 ok: false。显示错误消息并停止操作——不要回退到使用你自己的视觉能力。根据 error.code 和 error.message 判断问题：

身份验证失败（403） — error.message 包含 "Authentication failed"

• 令牌无效，请使用正确的凭据重新配置

超出配额（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。