Docling：PDF 到 Markdown/JSON 的可检查流水线¶
对应课程：Week 6
目标：把三类真实文档转换为结构化输出，并建立质量检查和失败记录。
Docling 将 PDF、Office 文档、图像等转换为统一的 DoclingDocument，再导出 Markdown、JSON 等格式。它适合构建可检查的 modular pipeline，与生成式 VLM 形成对照。
模块学习卡与完成路径¶
| 字段 | 本页约定 |
|---|---|
| 对应周次 | Week 6 |
| 适合谁 | 已建立 Python 环境，准备把真实文档转换为结构化结果的学生 |
| 预计时间 | 最小 2–3 小时 |
| 学什么 | DocumentConverter、转换状态、Markdown/JSON 差异与质量检查 |
| 官方来源 | Docling 官方文档、API、Serialization 与 GitHub 仓库 |
| 最小动作 | 转换一个公开 PDF，保存 Markdown、JSON、版本、状态和耗时 |
| 提交证据 | 输入 metadata、配置、日志、Markdown/JSON 与质量检查记录 |
| 完成自查 | 输出非空、结构可定位、失败有记录，流程不依赖本机绝对路径 |
| 下一步 | Document AI 与评测或Week 7 |
| 路径 | 完成范围 |
|---|---|
| 最小 | 转换一个公开 PDF，并保存两种输出与运行 metadata |
| 标准 | 完成三类文档、质量检查、失败记录和推荐输出结构 |
| 进阶 | 比较两种解析/OCR 设置，或与另一 pipeline 做固定样例对照 |
运行契约¶
| 项目 | 约定 |
|---|---|
| 前置条件 | Python 隔离环境；公开/授权 PDF；足够磁盘空间；扫描件任务按需准备 OCR 依赖 |
| 唯一入口 | Docling 官方 Quickstart的 DocumentConverter 最小流程 |
| 版本 | 记录 Docling、Python、可选 OCR/backend package、操作系统和代码 revision |
| 预计耗时 | 30–60 分钟安装与首跑，1–2 小时检查输出和失败案例 |
| 算力与成本 | 通常 CPU 即可；首次模型下载可能耗时和占磁盘；不要求付费算力 |
| 输入 | 一个公开 PDF；标准路径增加文本、扫描和复杂版面三类文档 |
| 预期输出 | outputs/document.md、outputs/document.json、run-metadata.json、日志和质量检查 |
| 成功判定 | 转换状态可检查，Markdown/JSON 非空，版本、耗时和输入标识已保存 |
| 常见失败与恢复 | 扫描件无文本时启用并记录 OCR；表格丢结构时检查 JSON；首跑慢时区分模型下载与实际转换耗时 |
官方学习入口¶
- Installation（当前安装和可选 OCR 引擎）
- Quickstart（
DocumentConverter） - Supported formats（输入与输出）
- CLI reference（批量转换和参数）
- DocumentConverter API（状态、限制与错误）
- Serialization（Markdown/JSON 的信息差异）
- Official GitHub repository（源码、examples、issues）
最小转换¶
以官方 Quickstart 为准，核心过程是：
from docling.document_converter import DocumentConverter
source = "path/to/document.pdf"
result = DocumentConverter().convert(source)
document = result.document
markdown = document.export_to_markdown()
structured = document.export_to_dict()
不要只打印输出。保存 Markdown、JSON、转换状态、耗时和输入文件的稳定标识。
选择输出格式
Markdown 便于阅读，但可能无法完整表达复杂表格和结构；需要保真中间表示时保存 Docling JSON。具体差异以官方 Serialization 文档为准。
Pipeline 设计¶
validate input
↓
convert with explicit options
↓
check conversion status/errors
↓
export Markdown + JSON
↓
run quality checks
↓
write manifest and report
程序必须限制输入类型、页数或文件大小，并为失败返回非零退出码。批量任务不能静默跳过失败文档。
Week 6 必做任务¶
选择与 Week 5 相同的三份文档：数字 PDF、扫描件、复杂表格文档。
- 使用默认 pipeline 转换并保存 Markdown/JSON；
- 记录 Docling 版本、处理选项、状态、耗时与错误；
- 对扫描件说明 OCR 是否启用、使用什么引擎和语言；
- 定义至少 5 条质量检查；
- 比较 Markdown 与 JSON 对标题、表格和阅读顺序的保留程度；
- 使用一个损坏或不支持的输入验证失败路径。
最小质量检查¶
| 检查 | 示例判定 |
|---|---|
| 文件完整性 | 输入存在、扩展名允许、大小在限制内 |
| 转换状态 | 成功、部分成功或失败被明确记录 |
| 内容非空 | 文本长度超过预设最低值 |
| 页面对应 | 输出覆盖预期页数 |
| 结构保留 | 标题、表格数量与人工检查一致 |
| 阅读顺序 | 抽样段落顺序无明显错乱 |
| JSON 有效性 | 可解析并满足预期顶层字段 |
这些检查用于发现异常，不等同于完整 Benchmark。模型质量评测在 Week 7 完成。
推荐输出结构¶
week06/
├── README.md
├── parse_documents.py
├── quality_checks.py
├── inputs-manifest.csv
├── results/
│ ├── markdown/
│ ├── json/
│ └── run-manifest.csv
└── quality-report.md
run-manifest.csv 至少包含 sample_id,input_hash,status,duration,markdown_path,json_path,error。
自主检查¶
- 使用当前官方
DocumentConverterAPI； - Docling 版本和 pipeline options 被记录；
- 三类文档均有输入—输出对应关系；
- Markdown 与 JSON 都被保存并比较；
- 至少 5 条质量检查能重复运行；
- 损坏输入能得到清晰错误和非零退出码；
- 原始文档来源、许可和隐私状态明确；
- 没有把“转换成功”误写为“解析质量优秀”。
常见问题¶
扫描 PDF 没有文本¶
确认 OCR 是否启用、OCR 引擎是否正确安装、语言数据是否可用，并记录实际配置。
表格在 Markdown 中丢失结构¶
对照 Docling JSON 或 HTML；复杂合并单元格不一定适合用 Markdown 表达。
第一次运行很慢¶
区分模型下载时间和稳定处理时间。报告中单独记录 warm-up，不把首次下载计入每页性能比较。
下一步¶
进入Document AI：从任务到评测，为 pipeline 建立固定 test set、质量指标和错误分类。