AI Skills
paddleocr-text-recognition

paddleocr-text-recognition

當使用者想要從圖片、照片、掃描檔、螢幕截圖或掃描的 PDF 中提取文字時，使用此技能。回傳精確的機器可讀字串，包含行級文字與可選的邊界框座標。對 CJK（中日韓）、小字體及手寫文字有高準確度。觸發詞：OCR、文字識別、圖片轉文字、截圖識字、提取圖中文字、掃描識字、識字、純文字、plain text extraction、座標、檢測框、bbox、bounding box、image to text、screenshot、photo scan、recognize text。

32星標
3分支
更新於 2026/5/6
獲取技能源代碼

相關技能

recsys-pipeline-architect24萬academy-guide17萬para-memory-files8萬
SKILL.md
唯讀
名稱
paddleocr-text-recognition
描述

當使用者想要從圖片、照片、掃描檔、螢幕截圖或掃描的 PDF 中提取文字時，使用此技能。回傳精確的機器可讀字串，包含行級文字與可選的邊界框座標。對 CJK（中日韓）、小字體及手寫文字有高準確度。觸發詞：OCR、文字識別、圖片轉文字、截圖識字、提取圖中文字、掃描識字、識字、純文字、plain text extraction、座標、檢測框、bbox、bounding box、image to text、screenshot、photo scan、recognize text。

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 字元），否則請勿以「...」截斷

範例 - 正確：

使用者：「從這張圖片提取文字」
助理：我已從圖片中提取文字。以下是完整內容：

[在此顯示完整文字]

範例 - 錯誤：

使用者：「從這張圖片提取文字」
助理：我在圖片中找到一些文字。以下是預覽：
「The quick brown fox...」（截斷）

理解輸出

腳本回傳一個 JSON 封套，包含 ok、text、result 和 error 欄位。使用 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。