PaddleOCR 中文文件解析技能

專業級中文文件 OCR 技能。基於百度飛槳引擎，支援文件解析和文字識別兩大核心能力，中文場景準確率業界領先。

快速判斷：用哪個模式？

特徵判斷規則：

• 有表格/公式/多欄排版 → 文件解析 (doc-parse)
• 純文字截圖/簡單圖片 → 文字識別 (text-recog)
• 多檔案 → 批次處理 (batch)

安裝與配置

1. 安裝依賴

python scripts/install_deps.py

可選依賴（表格匯出、PDF分頁）：

python scripts/install_deps.py --with-optional

2. 獲取 PaddleOCR API 憑證

在 paddleocr.com 註冊賬號，進入 API 頁面獲取：

• API Key 和 Secret Key（用於生成 access_token）
• 或直接獲取 access_token

3. 配置憑證

方法一：環境變數（推薦）

export PADDLEOCR_TOKEN="your_access_token_here"

方法二：配置檔案 (~/.paddleocr/config.json)

{
  "access_token": "your_token",
  "default_language": "ch"
}

詳見 references/api_reference.md 的 Token Management 章節。

能力一：文件解析 (Document Parsing)

完整文件理解，保留所有結構。

CLI 使用

# 基本用法 - 輸出到終端
python scripts/paddleocr_api.py doc-parse invoice.jpg

# 儲存為 Markdown 檔案
python scripts/paddleocr_api.py doc-parse report.pdf -o report.md --json-output report.json

# 中英混合文件
python scripts/paddleocr_api.py doc-parse paper.pdf --language ch_en

# 完整引數
python scripts/paddleocr_api.py doc-parse contract.pdf \
  --token "your_token" \
  --language ch \
  --format both \
  --output contract.md \
  --json-output contract.json \
  --timeout 180

Python API

from scripts.paddleocr_api import parse_document

result = parse_document(
    "invoice.jpg",
    access_token="your_token",  # 或設定 PADDLEOCR_TOKEN 環境變數
    language="ch",
    output_format="markdown"
)

if result["success"]:
    print(result["text"])          # Markdown 格式文本
    print(result["tables"])        # 提取的表格資料
    print(result["formulas"])      # LaTeX 格式公式
    print(result["layout"])        # 版面分析結果

返回結果說明

適用場景

• 發票/財務報告 → 表格完整保留
• 學術論文 → 公式以 LaTeX 輸出
• 合同/法律文件 → 條款結構保留
• 多欄排版 → 自動版面分析
• 含圖表的文件 → 圖表區域單獨標註

能力二：文字識別 (Text Recognition)

快速準確的文本提取，返回結構化 JSON。

CLI 使用

# 基本用法
python scripts/paddleocr_api.py text-recog photo.jpg

# 儲存結果
python scripts/paddleocr_api.py text-recog scan.png -o text.txt --json-output result.json

# 英文識別
python scripts/paddleocr_api.py text-recog english_doc.jpg --language en

Python API

from scripts.paddleocr_api import recognize_text

result = recognize_text(
    "screenshot.png",
    access_token="your_token",
    language="ch",
    detect_direction=True
)

if result["success"]:
    print(result["text"])           # 純文本（換行分隔）
    for word in result["words"]:    # 逐詞結果
        print(f"  [{word['bbox']}] {word['text']}")

返回結果說明

適用場景

• 截圖文字提取
• 照片/掃描件快速 OCR
• 簡單文件純文本提取
• 需要結構化 JSON 的二次開發

能力三：批次處理

# CLI 批次處理
python scripts/paddleocr_api.py batch page1.jpg page2.jpg page3.jpg --mode parse -d ./results

# 併發處理（Unix/macOS 下可用萬用字元，Windows 下請用具體檔名）
python scripts/paddleocr_api.py batch *.jpg --mode parse --workers 5

# Python API
from scripts.paddleocr_api import batch_process

results = batch_process(
    ["page1.jpg", "page2.jpg", "page3.jpg"],
    mode="parse",                    # "parse" 或 "recognize"
    output_dir="./ocr_results",      # 結果儲存目錄
    language="ch",
    max_workers=3,                   # 併發執行緒數
)

# 每個檔案生成 {filename}.parse.json 或 {filename}.recognize.json

能力四：表格匯出

將文件解析結果中的表格匯出為 Excel 或 CSV。

# 匯出為 Excel（預設），每張表一個 Sheet
python scripts/table_exporter.py result.json --format xlsx -o tables.xlsx

# 匯出為 CSV
python scripts/table_exporter.py result.json --format csv -o ./tables/

# 只匯出第1和第3張表
python scripts/table_exporter.py result.json --table-index 1 3

中文場景專項最佳化

針對國內常見文件型別的特殊處理，詳見 references/chinese_scenarios.md：

錯誤處理

常見錯誤

小蔥技能站7w4.net，專業的AI技能分享平臺。

自動處理

指令碼內建以下自動處理：

• RGBA → RGB 自動轉換
• 大圖自動縮放（保持寬高比）
• Base64 編碼自動完成
• 臨時錯誤自動重試（預設 3 次，指數退避）
• 錯誤時返回結構化錯誤資訊（success: false + error 欄位），不拋異常

參考資源

• API 詳細文件：references/api_reference.md — 完整 API 規範、引數說明、錯誤碼
• 中文場景指南：references/chinese_scenarios.md — 發票/身份證/營業執照等專項模板
• PaddleOCR 官網：https://www.paddleocr.com
• 百度 AI 開放平臺：https://ai.baidu.com/tech/ocr

與同類技能對比

這個技能質量不錯，文件寫得詳細清楚，功能覆蓋全面（文件解析、表格識別、批次處理等），對中文場景有專門最佳化。上手難度較低，錯誤提示也比較友好。主要不足是缺少一些後設資料資訊，部分功能在某些系統上可能受限。總體來說是一個成熟可用的 OCR 技能，適合需要處理中文文件的使用者。