PDF 多格式解析如何避免混用输出：TEXT、HTML、XML 与 TAG 数据契约

PDF 多格式解析如何避免混用输出，关键不是完成一次调用，而是让输入口径、处理状态和结果证据可以复核。本文围绕“如何按明确输出类型解析 PDF，并分别验收 TEXT、HTML、XML 和 TAG 结果”给出一套面向真实业务流程的实现方式。

问题与结果

输出类型成为任务契约的一部分，不同格式使用独立解析器、校验规则和版本记录。

适用场景

• PDF 文本检索入库
• 保留版面结构的 HTML 归档
• XML 或 TAG 下游数据处理

实现前先确定边界

1. 上传前校验 PDF 文件和输出类型
2. 不同输出类型不能写入同一个无类型字段
3. 接口成功后继续校验内容非空、编码和结构合法性

输出类型就是数据契约

PDF 多格式解析的 PDF 多格式解析的 PDF 多格式解析的 type 支持 text、html、xml 和 tag。调用方应在任务创建时固定输出类型，并将 file_hash + output_type + parser_version 作为幂等键的一部分。

输出类型	建议验收	常见用途
TEXT	非空、编码正常、页序可追踪	搜索、摘要、RAG 入库
HTML	HTML 解析成功、危险标签处理、结构可读	版面归档、富文本预览
XML	XML 严格解析通过、根节点和编码明确	结构化交换
TAG	标签语法符合下游约定	自定义解析流程

最小请求示例

curl -X POST "https://api.gugudata.com/imagerecognition/pdf2format?appkey=YOUR_APPKEY&type=html" \
  -F "pdffile=@document.pdf;type=application/pdf"

先检查 HTTP 状态，再检查 DataStatus.StatusCode，最后根据请求的输出类型校验 Data.Data。文本为空、HTML/XML 无法解析或返回类型与请求不一致时，任务进入失败队列，不应继续摘要、索引或格式转换。

OCR 与格式解析的选择

可复制文本的 PDF 优先走格式解析；扫描件或文本明显不足时再进入 图片流 OCR 分支。OCR 结果和格式解析结果应保留各自方法标识，不要合并成一个无法解释来源的正文。

任务状态与失败处理

生产接入至少区分 INPUT_INVALID、PENDING、RUNNING、SUCCEEDED、PARTIALLY_FAILED 和 FAILED。状态名称可以按业务调整，但不能把“任务已创建”“请求 HTTP 成功”和“结果可用”合并成一个成功状态。

参数错误应直接返回给调用方；频率或额度限制停止当前批次并保留下一次可执行条件；依赖服务失败可以进入有上限的退避重试；业务结果缺失、覆盖不足或引用不足则进入人工复核。每次尝试记录请求标识、开始和结束时间、业务状态、失败原因以及是否产生可用结果。

还应为重试设置幂等键和最大次数。相同输入、相同规则版本和相同业务目标不能因为网络超时重复写入多个正式结果；超过重试上限后保留最后错误和人工处理入口。

运行记录与回归检查

上线前保存一组脱敏固定样本，用于比较接口或规则升级前后的字段结构、状态流转和关键结果。回归测试不追求结果文本逐字一致，而是检查必填字段、来源证据、错误分类和能力边界是否稳定。

对于本文场景，重点回归以下约束：

• 上传前校验 PDF 文件和输出类型
• 不同输出类型不能写入同一个无类型字段
• 接口成功后继续校验内容非空、编码和结构合法性

监控指标至少包括成功结果数、失败数、处理中任务数、人工复核数和数据新鲜度。任何未采样指标都应显示“未采样”，不能默认为零。

数据契约与留痕

字段	作用
job_id	稳定业务标识，用于关联记录和请求追踪
file_hash	内容哈希，用于完整性、版本和重复识别
output_type	业务数据字段，保存来源、口径和缺失状态
parser_version	输入、规则或产物版本，变更时保留旧版本
raw_response	原始来源或响应，供后续复核
parsed_content	业务数据字段，保存来源、口径和缺失状态
validation_status	显式状态或原因，禁止以空值代替失败
failure_reason	显式状态或原因，禁止以空值代替失败

重试应新增尝试记录，不覆盖最后一次失败。派生结果必须关联输入版本、生成时间和业务状态。

验收清单

• 同一文件不同输出类型生成不同任务键
• HTML 和 XML 结果能通过对应解析器
• 失败或空内容不会进入正式数据集

能力边界

格式解析不保证复杂字体、表格、图像和版面完全还原；历史性能和 QPS 描述未经本次实时验证，不写入文章结论。

示例中的 YOUR_APPKEY 仅为占位符。真实密钥只能放在服务端环境变量或密钥管理系统中。