opendataloader-pdf 输出格式全解析：JSON、Markdown、HTML、Text、标注PDF怎么选
opendataloader-pdf 输出格式全解析：JSON、Markdown、HTML、Text、标注PDF怎么选
opendataloader-pdf 是一款开源 PDF 解析器（PDF Parser for AI-ready data），专注 AI 就绪数据提取与 PDF 无障碍自动化。解析完成后，它支持 JSON、Markdown、HTML、Text、标注 PDF 等多种输出格式，且可一次同时输出。本文面向新手，逐一讲清每种输出格式的定位、适用场景和关键选项，帮你在一张表内做出选择。
一分钟速览：6 种输出格式定位表
先建立全局认知。可取格式值定义在 options.json 的 --format 选项中（json, text, html, pdf, markdown, tagged-pdf），核心代码中的输出类型枚举见 OutputType.java：
| 格式 | 取值 | 一句话定位 | 典型场景 |
|---|---|---|---|
| JSON | json |
结构化数据 + 边界框（默认格式） | RAG 溯源引用、元素级控制 |
| Markdown | markdown |
干净的带结构文本 | LLM 上下文、RAG 分块 |
| HTML | html |
浏览器可渲染的网页格式 | 网页展示、邮件、知识库 |
| Text | text |
最轻量的纯文本 | 搜索索引、快速预览 |
| 标注 PDF | pdf |
可视化检测效果 | 质量调试、结果验收 |
| 标注 Tagged PDF | tagged-pdf |
带无障碍结构标签的 PDF | 无障碍合规（读屏器可访问） |
💡 不用单选：多个格式可用逗号组合一次输出，如
format="json,markdown"。PDF 只解析一次，各格式输出保持相互一致。
JSON：RAG 管线的"全能选手"
JSON 是默认输出格式，也是最能回答"这段内容出自哪里"的格式。每个元素都带有：
type：元素类型（heading、paragraph、table、list、image、caption、formula 等）page number：所在页码（从 1 开始）bounding box：位置坐标[left, bottom, right, top]，单位是 PDF 点（72pt = 1 英寸）content/heading level/font等：文本内容、标题层级、字体信息
下面是仓库样例 samples/json/lorem.json 中的一段真实输出：
{
"type": "heading",
"pdfua_tag": "H1",
"page number": 1,
"bounding box": [200.891, 706.938, 394.152, 745.132],
"heading level": 1,
"content": "Lorem Ipsum"
}
什么时候选 JSON：
- RAG 回答需要溯源引用（"点击定位原文"）——用 bounding box 在原文中高亮精确段落
- 需要程序化处理元素——按章节、按页拆分都靠
heading level和page number - 需要校验数据结构——仓库提供了完整的 JSON Schema：schema.json
Markdown：转换即用于 LLM
Markdown 是最适合新手的格式：保留标题层级、表格、列表和阅读顺序，干净到可以直接塞进 LLM 上下文窗口或喂给 RAG 分块器。
两个高频选项（完整说明见 options.json）：
--markdown-page-separator：页间分隔符，用%page-number%占位插入页码，便于带页码的分块--markdown-with-html：允许跨行合并等复杂表格回退为 HTML 表格语法，避免结构在纯 Markdown 里丢失
文档图片较多时，配合 --image-output 控制：external（默认，图片存磁盘引用）/ embedded（Base64 内嵌，单文件自包含）/ off（不提取图片）。
HTML：面向网页展示的场景
如果目标是把文档展示在网页、邮件或内部知识库中，选 format="html"：输出浏览器可直接渲染的标记，标题、表格等样式开箱即用。与 Markdown 一样，支持 --html-page-separator 添加页间分隔符。
Text：最轻量的"只要文字"之选
如果只关心"把文字拿到手"——搜索索引、快速预览、或交给只接受纯文本的工具——选 format="text"。输出最小、无任何标记；配合 --keep-line-breaks 可保留原始换行。
标注 PDF：用眼睛看出解析器"看到了什么"
pdf 格式与其他格式不同——它输出在原文件副本上叠加检测结果：标题、段落、表格、图片各元素都被框出并标注语义类型：
上图为仓库样例：论文页面上的标题（蓝紫色）、摘要（绿色）、插图与图注、正文段落，全部被解析器框出并分类。
什么时候选：怀疑提取质量时（阅读顺序错乱、表格漏检），生成一份标注 PDF 看一眼，比逐条翻 JSON 直观得多——这也是验收解析效果的最佳方式。
隐藏格式：tagged-pdf 与无障碍合规
若需要 PDF 满足无障碍法规（EAA、ADA/Section 508 等），选 format="tagged-pdf"：未打标签的 PDF 进，带结构标签的 Tagged PDF 出——屏幕阅读器可识别的标题、段落、列表、表格和阅读顺序标签，全自动生成，Apache 2.0 开源免费。这是该项目区别于其他 PDF 解析器的核心能力之一。
场景速查表：按目标选格式
| 你的目标 | 推荐格式 |
|---|---|
| RAG + 来源引用（页码 + 区域定位） | json |
| RAG 按标题分块 | markdown |
| 网页 / 邮件展示 | html |
| 搜索索引、快速预览 | text |
| 效果调试、质量验收 | pdf 配合 json 交叉核对 |
| 无障碍合规 | tagged-pdf |
| 一次满足多种需求 | format="json,markdown,html" 组合输出 |
两条实用提醒：
- 多格式同出只解析一次，比分多次运行更快，且输出相互一致
- 管道输出（
--to-stdout）有坑：只支持单一格式，且部分格式无法走管道——拿不准就写入文件再读文件，流式输出的注意事项可参考 format-guide.md
小结
- 要数据选 JSON，要文本选 Markdown，要展示选 HTML，要预览选 Text，要调试选 标注 PDF，要合规选 tagged-pdf
- 多格式可逗号组合，一次解析、多份输出
- 选定格式后，再用
--pages、--image-output、--markdown-page-separator等选项微调
更完整的"目标 → 能力 → 格式"决策路径，可查阅 skills/odl-pdf/references/format-guide.md。