PaddleOCR 中文文档解析技能

专业级中文文档 OCR 技能。基于百度飞桨引擎，支持文档解析和文字识别两大核心能力，中文场景准确率业界领先。

快速判断：用哪个模式？

特征判断规则：

• 有表格/公式/多栏排版 → 文档解析 (doc-parse)
• 纯文字截图/简单图片 → 文字识别 (text-recog)
• 多文件 → 批量处理 (batch)

安装与配置

1. 安装依赖

python scripts/install_deps.py

可选依赖（表格导出、PDF分页）：

python scripts/install_deps.py --with-optional
7w4.net小葱技能。

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：

错误处理

常见错误

自动处理

脚本内置以下自动处理：

• 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 技能，适合需要处理中文文档的用户。