SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场paddleocr-doc-parsing

paddleocr-doc-parsing

办公与效率

查看项目

更新于 10-15 15:12

技能介绍

用途

PaddleOCR 文档解析技能用于对文档进行高级结构化解析，返回完整的文档结构，包括文本、表格、公式、图表和版面信息。

适合在以下情况使用：

  • 含表格的文档（发票、财务报告、电子表格）
  • 含数学公式的文档（学术论文、科学文档）
  • 含图表和图解的文档
  • 多栏排版（报纸、杂志、宣传册）
  • 需要版面分析的复杂文档结构
  • 任何需要结构化理解的文档

如果只是简单纯文本提取、对速度要求高的快速 OCR 任务，或处理文字清晰的截图与简单图片，则应改用文本识别。

主要能力

输出 JSON 包含完整文档数据：页眉、页脚、页码；正文内容；带结构的表格；公式（含 LaTeX）；图形与图表；脚注与参考文献；印章与图章；版面与阅读顺序。

输出 JSON 采用信封结构包裹原始 API 结果：

{
  "ok": true,
  "text": "Full markdown/HTML text extracted from all pages",
  "result": { ... },  // raw provider response
  "error": null
}

关键字段：

  • text — 从所有页面提取的 markdown 文本（用于快速文本展示）
  • result — 原始提供方响应对象
  • result[n].prunedResult — 每页的结构化解析输出（版面/内容/置信度及相关元数据）
  • result[n].markdown — 每页完整渲染输出（markdown/HTML）

原始结果默认位置：脚本在 stderr 上打印的临时文件路径。

使用方式

基本工作流：

执行文档解析：

python scripts/vl_caller.py --file-url "URL provided by user" --pretty

或处理本地文件：

python scripts/vl_caller.py --file-path "file path" --pretty

可选：显式设置文件类型：

python scripts/vl_caller.py --file-url "URL provided by user" --file-type 0 --pretty
  • --file-type 0：PDF
  • --file-type 1：图片

若省略，服务可从输入推断文件类型。

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

  • 若省略 --output，脚本自动保存到系统临时目录
  • 默认路径模式：<system-temp>/paddleocr/doc-parsing/results/result_<timestamp>_<id>.json
  • 若提供 --output，则覆盖默认临时文件目标
  • 若提供 --stdout，JSON 打印到 stdout 且不保存文件
  • 保存模式下，脚本在 stderr 打印绝对保存路径：Result saved to: /absolute/path/...
  • 默认/自定义保存模式下，响应前需读取并解析已保存的 JSON 文件
  • 保存模式下，始终告知用户保存的文件路径以及完整原始 JSON 可在该处获取
  • 仅在明确希望跳过文件持久化时使用 --stdout

使用示例：

示例 1：提取完整文档文本

python scripts/vl_caller.py \
  --file-url "https://example.com/paper.pdf" \
  --pretty

然后使用：顶层 text 快速输出全文；需要页面级输出时使用 result[n].markdown。

示例 2：提取结构化页面数据

python scripts/vl_caller.py \
  --file-path "./financial_report.pdf" \
  --pretty

然后使用：result[n].prunedResult 获取结构化解析数据（版面/内容/置信度）；result[n].markdown 获取渲染后的页面内容。

示例 3：打印 JSON 而不保存

python scripts/vl_caller.py \
  --file-url "URL" \
  --stdout \
  --pretty

首次配置

当 API 未配置时，错误会显示：

PADDLEOCR_DOC_PARSING_API_URL not configured. Get your API at: https://paddleocr.com

配置流程：

  1. 向用户展示确切错误信息（含 URL）。
  2. 引导用户安全配置：建议通过宿主应用的标准方式（如设置文件、环境变量 UI）配置，而不是在聊天中粘贴凭据。
  3. 列出所需环境变量：
    • PADDLEOCR_DOC_PARSING_API_URL
    • PADDLEOCR_ACCESS_TOKEN
    • 可选：PADDLEOCR_DOC_PARSING_TIMEOUT
  4. 若用户仍在聊天中提供凭据（接受任何合理格式），解析并校验取值：
    • 提取 PADDLEOCR_DOC_PARSING_API_URL（查找含 paddleocr.com 或类似的 URL）
    • 确认 PADDLEOCR_DOC_PARSING_API_URL 是完整端点且以 /layout-parsing 结尾
    • 提取 PADDLEOCR_ACCESS_TOKEN（长字母数字字符串，通常 40+ 字符）
    • 告知用户需设置哪些环境变量
  5. 请用户确认环境已配置，等待确认后再重试。

安全提示：提醒用户聊天中共享的凭据可能被存储在对话历史中，建议尽可能通过宿主应用配置设置。若技能安装在宿主应用目录下（例如 ~/.claude/skills），出于安全原因默认不要运行 configure.py 或创建本地 .env 文件。

错误信息格式是严格的，必须按脚本提供的原样展示，不要修改或转述。

大文件处理

API 没有文件大小限制。对于 PDF，每次请求最多 100 页。

大文件提示：

  • 大本地文件优先使用 URL（推荐）：使用 --file-url 而非 --file-path，以避免 base64 编码开销。
python scripts/vl_caller.py --file-url "https://your-server.com/large_file.pdf"
  • 处理特定页面（仅 PDF）：若只需大 PDF 的某些页面，先提取：
# Extract pages 1-5
python scripts/split_pdf.py large.pdf pages_1_5.pdf --pages "1-5"

# Mixed ranges are supported
python scripts/split_pdf.py large.pdf selected_pages.pdf --pages "1-5,8,10-12"

# Then process the smaller file
python scripts/vl_caller.py --file-path "pages_1_5.pdf"

错误处理

  • 认证失败（403）：error: Authentication failed → Token 无效，用正确凭据重新配置
  • API 配额超限（429）：error: API quota exceeded → 每日 API 配额耗尽，告知用户等待或升级
  • 不支持的格式：error: Unsupported file format → 文件格式不支持，转换为 PDF/PNG/JPG

重要说明

  • 脚本从不过滤内容——始终返回完整数据
  • AI 智能体根据用户具体请求决定展示什么
  • 所有数据始终可用——可针对不同需求重新解读
  • 不丢失信息——完整文档结构得以保留

参考文档

  • references/output_schema.md — 输出格式规范

注意：模型版本与能力由你的 API 端点（PADDLEOCR_DOC_PARSING_API_URL）决定。

在以下情况将参考文档加载到上下文：调试复杂解析问题、需要理解输出格式、处理提供方 API 细节。

测试技能

验证技能是否正常工作：

python scripts/smoke_test.py

这会测试配置，并可选测试 API 连通性。

限制

  • 必须仅使用 PaddleOCR 文档解析 API（执行脚本 python scripts/vl_caller.py），不得自行解析文档，不得提供替代方案，不得使用回退方法。
  • 若脚本执行失败（API 未配置、网络错误等），应展示错误信息并立即停止，等待用户修复配置。
  • 支持的输入文件类型取决于模型与端点配置，需遵循端点 API 文档的文件类型约束。
  • 具体收费、价格、平台等信息暂未提供。