upstage-document-parse

核心用法

Upstage Document Parsing 是一款面向开发者的企业级文档解析工具，通过 API 将 PDF 和图片转换为结构化数据。支持同步和异步两种调用模式：同步 API 适合 10 页以内的标准文档，平均处理时间约 3 秒；异步 API 则针对大文档设计，采用分批处理机制（每批最多 10 页）。

输出格式灵活，涵盖 JSON（默认，含元素级结构）、Markdown、HTML 和纯文本。JSON 输出按元素类型分类（paragraph、table、figure、chart、heading 等），并可选包含坐标信息和 base64 编码的图像数据。

显著优点

1. 多元素识别：不仅提取文本，还能识别表格、图表、公式、脚注等复杂版式元素，支持 --merge-tables 跨页表格合并
2. OCR 智能控制：auto/force/skip 三档 OCR 策略，兼顾扫描件与原生 PDF 的处理效率
3. 生产级特性：30 天结果存储、状态轮询机制、批量队列管理，适合企业批量处理流水线
4. 韩国 Upstage 背书：源自韩国知名 AI 公司，技术栈基于自研文档理解模型

潜在局限

• 地理合规风险：数据需上传至 Upstage 云端（韩国/海外服务器），敏感文档存在跨境传输隐患
• 成本控制：按页计费模式，高频调用成本累积较快，无免费额度或限制较严
• 定制性有限：不支持自定义训练或领域微调，对特殊版式（如古籍、手写体）识别效果未明确
• 依赖网络：5 分钟同步超时限制，超大文档必须走异步流程，增加集成复杂度

适合人群

• 需要快速搭建文档数字化管道的开发团队
• 处理发票、合同、报告等标准商业文档的自动化工作流
• 已有 Upstage 生态或韩国/亚太区业务布局的企业

常规风险

• API 密钥泄露：需妥善管理 UPSTAGE_API_KEY，建议通过环境变量或密钥管理服务注入
• 数据残留：解析结果云端存储 30 天，涉及个人隐私或商业机密的文档需谨慎评估
• 依赖单一供应商：功能深度绑定 Upstage 服务，迁移成本较高，建议关键业务做降级方案

核心用法

该 Skill 是 Upstage Document Parsing API 的命令行封装工具，支持提取 PDF 和图片中的结构化内容。使用方式简单直接：

同步解析（推荐常规文档）

{baseDir}/scripts/parse.sh document.pdf --format markdown --ocr auto

异步解析（推荐大型文档或批量处理）

{baseDir}/scripts/parse-async.sh large-document.pdf  # 提交任务
{baseDir}/scripts/parse-status.sh <request_id> --wait --download  # 获取结果

输出格式支持 JSON（默认）、Markdown、HTML、纯文本，可包含元素坐标信息，支持表格/图表的 base64 编码导出。

显著优点

1. 官方 API 封装：直接对接 Upstage 官方服务，解析质量稳定，对复杂版式（多栏、表格、图表）识别效果优于开源方案
2. 结构化输出：不仅返回纯文本，还返回元素类型（paragraph/table/figure/chart 等）和位置信息，便于下游处理
3. 异步支持：大型文档自动分片处理（每批最多10页），避免超时，适合批量场景
4. 零依赖：仅依赖系统 curl，无 npm/pip 等第三方包管理风险
5. 格式灵活：一键切换 Markdown/HTML/JSON，适配 RAG、知识库、内容迁移等多种场景

潜在缺点与局限性

1. 云端依赖：必须联网，文档需上传至 Upstage 服务器，敏感文档存在合规顾虑
2. 成本因素：Upstage API 按页计费，高频使用成本高于本地开源方案（如 marker、nougat）
3. 异步结果保留期短：仅保留30天，下载链接15分钟过期，需及时获取
4. 超时限制：同步 API 5分钟超时，超百页文档必须走异步流程
5. 语言支持偏向：虽然支持多语言，但在某些 CJK 复杂版式上可能出现表格错位

适合人群

• 需要将扫描件/复杂 PDF 转为结构化数据的知识库建设者
• 追求解析准确率、不愿投入自研 OCR 的中小团队
• 已有 Upstage API 额度或计划使用其 Solar LLM 的整合用户
• 需要提取图表数据并转换为可编辑表格的数据分析师

常规风险

• 隐私合规：文档内容外发至韩国 Upstage 服务器，需评估 GDPR/数据出境合规要求
• API 密钥泄露：密钥存储于环境变量或配置文件，需避免提交至版本控制
• 路径遍历风险：输入文件路径未严格校验，建议配合 realpath 使用