paddleocr-doc-parsing

PaddleOCR 文档解析技能

何时使用此技能

触发关键词（路由）：上方 YAML description 中列出了中英文触发词——使用该字段进行发现和路由。

适用于以下情况：

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

不适用于以下情况：

• 仅需提取简单文本
• 对速度要求很高的快速 OCR 任务
• 文本清晰的截图或简单图像

安装

脚本以内联方式声明依赖项（PEP 723）。无需单独安装——uv 会自动解析依赖项：

uv run scripts/layout_caller.py --help

如何使用此技能

工作目录：以下所有 uv run scripts/... 命令都应在此技能的根目录下运行（即包含此 SKILL.md 文件的目录）。

基本工作流

1. 确定输入来源：

   • 用户提供 URL：使用 --file-url 参数
   • 用户提供本地文件路径：使用 --file-path 参数

2. 执行文档解析：

   uv run scripts/layout_caller.py --file-url "URL provided by user" --pretty
   

   或者处理本地文件：

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

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

   uv run scripts/layout_caller.py --file-url "URL provided by user" --file-type 0 --pretty
   

   • --file-type 0：PDF
   • --file-type 1：图像
   • 如果省略，系统会根据文件扩展名自动检测类型。本地文件必须使用可识别的扩展名（.pdf、.png、.jpg、.jpeg、.bmp、.tiff、.tif、.webp）；否则请显式传入 --file-type。对于扩展名无法识别的 URL，服务会尝试推断文件类型。

   性能说明：解析时间取决于文档的复杂程度。单页图像通常需要 1-5 秒；大型 PDF（50 页以上）可能需要几分钟。请留出充足时间，再判断是否超时。

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

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

3. 解析 JSON 响应：

   • 检查 ok 字段：true 表示成功，false 表示出错
   • 输出包含完整的文档数据：文本、表格、公式（LaTeX）、图形、印章、页眉/页脚和阅读顺序
   • 根据用户需求使用相应字段：
     • text — 所有页面的完整文档文本
     • result.result.layoutParsingResults[n].markdown.text — 页面级 Markdown
     • result.result.layoutParsingResults[n].prunedResult — 包含位置和置信度的结构化版面数据
   • 处理错误：如果 ok 为 false，则显示 error.message

4. 向用户呈现结果：

   • 根据用户的请求显示内容（参见下方“完整输出显示”）
   • 如果内容为空，文档可能不包含可提取的文本
   • 在保存模式下，务必告知用户保存文件的路径，并说明完整的原始 JSON 可在该路径下查看

解析后要做什么

获取结构化输出后，常见的后续步骤：

• 保存为 Markdown：将 text 字段写入 .md 文件——表格、标题和公式都会保留
• 提取特定表格：访问 result.result.layoutParsingResults[n].prunedResult，获取带有位置和置信度数据的单个布局元素
• 馈送至 RAG / 搜索工作流：text 字段是结构化 Markdown，可直接用于分块和索引
• 结果不理想：重试前请参阅下方的“获得更好结果的技巧”

显示完整输出

根据用户的请求，显示提取出的完整内容。只有用户能收到全部内容，解析后的输出才有用——截断会悄无声息地丢失数据。

• 如果用户要求“全部文本”，请显示完整的 text 字段
• 如果用户要求“表格”，请显示文档中的所有表格
• 如果用户要求“主要内容”，请过滤掉页眉/页脚，但显示所有正文文本
• 除非内容特别长（>10,000 个字符），否则不要用“...”截断
• 用户期望看到完整输出时，不要说“以下是预览”

正确示例：

User: "Extract all the text from this document"
Agent: I've parsed the complete document. Here's all the extracted text:

[Display entire text field or concatenated regions in reading order]

Document Statistics:
- Total regions: 25
- Text blocks: 15
- Tables: 3
- Formulas: 2
Quality: Excellent (confidence: 0.92)

错误示例：

User: "Extract all the text"
Agent: "I found a document with multiple sections. Here's the beginning:
'Introduction...' (content truncated for brevity)"

了解输出

脚本会返回包含 ok、text、result 和 error 的封装对象。使用 text 获取完整文档内容；访问 result.result.layoutParsingResults[n] 获取每页的结构化数据。

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

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

替代方案：paddleocr CLI

此镜像默认使用随附的 scripts/layout_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_DOC_PARSING_API_URL（脚本仍需要该 URL）。

基本文档解析：

# From URL
paddleocr api --model_type doc_parsing --file_url "https://example.com/report.pdf"

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

常用选项：

# Specific model
paddleocr api --model_type doc_parsing --model PP-StructureV3 --file_path "./report.pdf"

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

# Page ranges (replaces split_pdf.py for most cases)
paddleocr api --model_type doc_parsing --file_path "./large.pdf" --page_ranges "1-5,10,15-20"

# Save result and extracted resources (images)
paddleocr api --model_type doc_parsing --file_url "https://..." \
  --output result.json --save_resources ./resources

# Prettify markdown output
paddleocr api --model_type doc_parsing --file_path "./document.pdf" --prettify_markdown True

CLI 输出格式——与脚本封装对象不同：

{
  "jobId": "job-xxx",
  "pages": [
    {
      "markdownText": "# Title\n\nContent...",
      "markdownImages": { "img1": "https://...", "img2": "https://..." },
      "outputImages": { "layout1": "https://..." }
    }
  ]
}

CLI 会向 stdout 打印 {jobId, pages:[...]}。它不会将响应封装在脚本的 {ok, text, result, error} 对象中，不会自动保存到临时文件，也不会为你拼接顶层的 text 字段。字段名称也不同于脚本的原始 result.result.layoutParsingResults[n].markdown.text 路径。如果切换使用方式，请相应更新解析逻辑。

脚本与 CLI——快速对比：

	脚本（默认）	paddleocr CLI（替代方案）
安装	uv 解析 PEP 723 内联依赖	pip install "paddleocr>=3.7.0"
必需环境变量	PADDLEOCR_DOC_PARSING_API_URL + PADDLEOCR_ACCESS_TOKEN	仅需 PADDLEOCR_ACCESS_TOKEN
入口	uv run scripts/layout_caller.py ...	paddleocr api --model_type doc_parsing ...
页面选择	使用 scripts/split_pdf.py 预先拆分	原生支持 --page_ranges "1-5,10"
图像优化	上传前运行 scripts/optimize_file.py	同样可用，或使用 CLI 默认设置
输出	{ok, text, result, error} 封装对象，自动保存到临时文件	{jobId, pages:[...]} 输出至 stdout
结果位置	stderr 上打印的路径（或 --output/--stdout）	stdout（或 --output）
最适合	Skills 运行环境、便于离线使用、无需额外安装	已安装 paddleocr，希望使用上游规范流程

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

使用示例

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

uv run scripts/layout_caller.py \
  --file-url "https://example.com/paper.pdf" \
  --pretty

然后使用：

• 顶层的 text 快速输出全文
• 需要按页面输出时，使用 result.result.layoutParsingResults[n].markdown

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

uv run scripts/layout_caller.py \
  --file-path "./financial_report.pdf" \
  --pretty

然后使用：

• 使用 result.result.layoutParsingResults[n].prunedResult 获取结构化解析数据（布局/内容/置信度）

示例 3：将 JSON 输出到 stdout（不保存到文件）

uv run scripts/layout_caller.py \
  --file-url "URL" \
  --stdout \
  --pretty

默认情况下，脚本会将 JSON 写入临时文件，并将路径输出到 stderr。添加 --stdout 可直接将完整 JSON 输出到 stdout。需要内联查看结果或将其传递给其他工具时，请使用此选项。

首次配置

未配置 API 时，脚本会输出：

{
  "ok": false,
  "text": "",
  "result": null,
  "error": {
    "code": "CONFIG_ERROR",
    "message": "PADDLEOCR_DOC_PARSING_API_URL not configured. Get your API at: https://paddleocr.com"
  }
}

配置流程：

1. 向用户显示准确的错误消息。

2. 指导用户获取凭据：访问 PaddleOCR 网站，点击 API，选择模型（PP-StructureV3、PaddleOCR-VL 或 PaddleOCR-VL-1.5），然后复制 API_URL 和 Token。它们对应以下环境变量：

   • PADDLEOCR_DOC_PARSING_API_URL — 以 /layout-parsing 结尾的完整端点 URL
   • PADDLEOCR_ACCESS_TOKEN — 40 位字母数字字符串

   也可以配置 PADDLEOCR_DOC_PARSING_TIMEOUT 来设置请求超时时间。建议使用宿主应用的标准配置方法，而不要在聊天中粘贴凭据。

3. 设置凭据——任选以下一种方式：

   • 用户通过宿主 UI 完成配置：请用户确认，然后重试。
   • 用户在聊天中粘贴凭据：提醒用户凭据可能会保存在对话历史中，协助用户使用宿主的标准配置方法保存凭据，然后重试。

处理大文件

对于 PDF，每次请求最多处理 100 页。

解析前优化大型图像

对于大型图像文件，请在上传前进行压缩——这可以缩短上传时间，并提升处理稳定性：

uv run scripts/optimize_file.py input.png output.jpg --quality 85
uv run scripts/layout_caller.py --file-path "output.jpg" --pretty

--quality 控制 JPEG/WebP 有损压缩（1-100，默认值为 85）；对 PNG 输出无效。使用 --target-size（单位为 MB，默认值为 20）设置文件大小上限——脚本会反复缩小图像，直至达到目标大小。

大型本地文件使用 URL（推荐）

对于特别大的本地文件，建议使用 --file-url，而不是 --file-path，以避免 base64 编码开销：

uv run scripts/layout_caller.py --file-url "https://your-server.com/large_file.pdf"

处理指定页面（仅限 PDF）

如果大型 PDF 只需要其中某些页面，请先提取这些页面：

# Extract pages 1-5
uv run scripts/split_pdf.py large.pdf pages_1_5.pdf --pages "1-5"

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

# Then process the smaller file
uv run scripts/layout_caller.py --file-path "pages_1_5.pdf"

错误处理

所有错误都会以 JSON 格式返回，并包含 ok: false。显示错误消息并停止操作——不要改用你自身的视觉能力。根据 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 字段为空
• 文档可能为空白、仅包含图像，或不含可提取的文本

提高结果质量的提示

如果解析质量不佳：

• 大型或高分辨率图像：解析前使用 optimize_file.py 进行压缩——过大的输入可能会影响布局检测：

  uv run scripts/optimize_file.py input.png optimized.jpg --quality 85
  

• 检查置信度：result.result.layoutParsingResults[n].prunedResult 包含各布局元素的置信度分数——较低的分数表示需要检查的区域

参考文档

• references/output_schema.md — 完整的输出架构、字段说明和命令示例

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

测试技能

验证技能是否正常工作：

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。