核心用法
PaddleOCR Document Parsing Skill 是一款面向复杂文档结构的专业解析工具，基于百度飞桨 PP-StructureV3 / PaddleOCR-VL 系列视觉语言模型构建。用户通过命令行调用 vl_caller.py 脚本，传入 PDF 或图像文件（本地路径或 URL），即可获取包含完整版面信息的结构化输出。
核心工作流分为三步：1) 识别输入源并选择对应参数（--file-url 或 --file-path）；2) 执行解析命令，支持自动类型检测或显式指定（--file-type 0/1）；3) 处理返回的 JSON 响应，提取 text 字段获得完整 Markdown 格式文档，或深入 layoutParsingResults 获取页面级精细化数据（表格单元格坐标、公式 LaTeX、图表区域、印章位置等）。
工具链提供辅助优化脚本：optimize_file.py 用于大图像压缩降质，split_pdf.py 支持按需提取 PDF 指定页码，有效应对 100 页上限约束。输出默认保存至系统临时目录，也可通过 --stdout 直接管道传输。
显著优点
- 版面还原精度高：区别于普通 OCR 的纯文本输出，该技能完整保留表格结构（单元格级别）、数学公式（LaTeX 渲染）、多栏排版阅读顺序及图表区域定位，满足学术文献、财务报表、合同发票等复杂场景的结构化需求。
- 端到端中文优化：PaddleOCR 原生针对中文文档训练，对横竖混排、印章干扰、低质量扫描件具有更强的鲁棒性。
- 灵活的输出形态：同时提供人类可读的 Markdown (
text) 和机器友好的结构化 JSON (prunedResult)，兼顾直接阅读与下游 RAG/搜索 pipeline 接入。 - 完善的辅助工具链：内置图像优化、PDF 分页提取、冒烟测试等脚本，降低大文件处理门槛。
潜在局限性与风险
- API 依赖与配额限制：需配置
PADDLEOCR_DOC_PARSING_API_URL及PADDLEOCR_ACCESS_TOKEN，存在网络延迟、服务可用性及每日调用配额（429 错误）风险；大 PDF（50+ 页）解析耗时可达数分钟。 - 成本与复杂度门槛：仅建议用于含表格、公式、复杂版面的文档；纯文本场景使用过度，且需 Python 环境及可选依赖安装，配置链路较普通 OCR 更长。
- 输出体积与存储：完整解析结果 JSON 体积较大，默认落盘临时文件需及时清理，避免敏感文档残留。
- 置信度波动：极端模糊、手写体或艺术字体区域可能识别失败，需人工复核低 confidence 字段。
适合人群
- 需要处理学术论文、技术手册、财务报表、合同发票、杂志多栏排版等复杂版面的知识工作者
- 构建文档智能 pipeline（RAG、知识图谱、自动归档）的开发者与数据工程师
- 对中文文档解析精度有较高要求，且能接受云端 API 模式的企业用户
常规风险
- 凭证泄露风险：Token 与 API URL 若通过聊天粘贴可能留存对话历史，应优先使用宿主应用的标准配置机制。
- 敏感文档外传：文件上传至 PaddleOCR 云端服务，涉及机密、个人隐私或合规敏感内容时需评估数据出境与服务商安全资质。
- 解析失败无 fallback：错误处理策略明确要求 "do not fall back to your own vision capabilities"，一旦 API 异常则无备用解析路径，需确保网络与配额稳定性。