独立指南——与 IBM 及 Docling 项目无隶属关系。 所有命令均在 Docling 2.148.0 上验证。
  1. 首页
  2. 示例
示例

Docling 实用代码——复制、粘贴、直接运行

针对 Docling 日常任务的简短完整脚本。发布前,我们在 Docling 2.148.0 上用 Docling 技术报告和一份 Word 文件逐一运行过。

已在 Docling 上验证 2.148.0更新于 2026年11月6日12 分钟阅读
要点速览
  • 每个示例都是独立的:导入、转换、输出。
  • 处理原生数字 PDF 时设置 do_ocr = False——这是最大的提速手段。
  • 每个进程只创建一个 DocumentConverter 并复用。

1 · PDF 转 Markdown,图片单独保存为文件#

pythonpdf_to_md_with_images.py
from pathlib import Path
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.document_converter import DocumentConverter, PdfFormatOption
from docling_core.types.doc import ImageRefMode

opts = PdfPipelineOptions(do_ocr=False, generate_picture_images=True, images_scale=2.0)
converter = DocumentConverter(format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=opts)})

doc = converter.convert("report.pdf").document
out = Path("out"); out.mkdir(exist_ok=True)
doc.save_as_markdown(out / "report.md", artifacts_dir=Path("images"), image_mode=ImageRefMode.REFERENCED)
print(sorted(p.name for p in (out / "images").glob("*.png"))[:3])

图片以 PNG 文件写入 out/images,并在 Markdown 中以相对路径链接。相对的 artifacts_dir 以 Markdown 文件所在目录为基准——如果省略它并保存到子目录,docling-core 2.106.0 会把图片多嵌套一层(out/out/report_artifacts),这是我们测试时遇到的意外。

2 · 转换整个文件夹,跳过坏文件,并生成报告#

pythonbatch_folder.py
import csv
from pathlib import Path
from docling.datamodel.base_models import ConversionStatus
from docling.document_converter import DocumentConverter

src, out = Path("inbox"), Path("out")
out.mkdir(exist_ok=True)
converter = DocumentConverter()

with open(out / "report.csv", "w", newline="") as f:
    log = csv.writer(f)
    log.writerow(["file", "status", "pages", "seconds"])
    files = [p for p in src.iterdir() if p.is_file()]
    for res in converter.convert_all(files, raises_on_error=False):
        name = res.input.file.name
        if res.status in (ConversionStatus.SUCCESS, ConversionStatus.PARTIAL_SUCCESS):
            res.document.save_as_markdown(out / f"{res.input.file.stem}.md")
        secs = sum(sum(t.times) for k, t in res.timings.items() if k == "pipeline_total")
        log.writerow([name, res.status.value, len(res.pages), round(secs, 1)])

只有开启性能分析(settings.debug.profile_pipeline_timings = True)时才会填充 pipeline_total;否则耗时一列为 0。

3 · 每张表格导出为 CSV,并汇总到一个 Excel 工作簿#

pythontables_to_csv_excel.py
import pandas as pd
from docling.document_converter import DocumentConverter

doc = DocumentConverter().convert("report.pdf").document
with pd.ExcelWriter("tables.xlsx") as xls:
    for i, table in enumerate(doc.tables, start=1):
        df = table.export_to_dataframe(doc=doc)
        df.to_csv(f"table_{i}.csv", index=False)
        df.to_excel(xls, sheet_name=f"table_{i}", index=False)
        print(i, df.shape, "page", table.prov[0].page_no)

pandas 写入 .xlsx 所用的 openpyxl 会随 Docling 一起安装。

4 · 每页一个 Markdown 文件#

pythonper_page.py
from docling.document_converter import DocumentConverter

doc = DocumentConverter().convert("report.pdf").document
for page_no in sorted(doc.pages):
    md = doc.export_to_markdown(page_no=page_no)
    with open(f"page_{page_no:03d}.md", "w") as f:
        f.write(md)
print(len(doc.pages), "pages written")

5 · 找出需要人工检查的页面#

每个 ConversionResult 都带有置信度报告:每页的解析、版面、表格和 OCR 分数,以及总体等级(poor、fair、good 或 excellent)。

pythonlow_confidence.py
from docling.document_converter import DocumentConverter

res = DocumentConverter().convert("report.pdf")
conf = res.confidence
print("document:", conf.mean_grade.value, round(conf.mean_score, 3))
for page_no, scores in sorted(conf.pages.items()):
    print(page_no, scores.mean_grade.value, round(scores.layout_score, 3))

6 · 导出插图及其图注#

pythonfigures.py
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.document_converter import DocumentConverter, PdfFormatOption

opts = PdfPipelineOptions(do_ocr=False, generate_picture_images=True, images_scale=2.0)
conv = DocumentConverter(format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=opts)})
doc = conv.convert("report.pdf").document

for i, pic in enumerate(doc.pictures, start=1):
    img = pic.get_image(doc)
    if img is not None:
        img.save(f"figure_{i}.png")
    print(i, pic.prov[0].page_no, pic.caption_text(doc)[:70])

7 · 转换字节流(S3、上传文件、邮件附件)#

pythonfrom_bytes.py
from io import BytesIO
from docling.datamodel.base_models import DocumentStream
from docling.document_converter import DocumentConverter

data = open("report.pdf", "rb").read()        # 例如 s3.get_object(...)["Body"].read()
doc = DocumentConverter().convert(DocumentStream(name="report.pdf", stream=BytesIO(data))).document
print(doc.name, len(doc.texts))

8 · 只转换前几页#

pythonfirst_pages.py
from docling.document_converter import DocumentConverter

res = DocumentConverter().convert("report.pdf", page_range=(1, 2))
print(len(res.pages), "pages converted")
print(res.document.export_to_markdown()[:200])

9 · Word、PowerPoint 和 Excel 转 Markdown#

pythonoffice.py
from docling.document_converter import DocumentConverter

converter = DocumentConverter()
for name in ["memo.docx"]:                     # .pptx 和 .xlsx 用法相同
    md = converter.convert(name).document.export_to_markdown()
    print(md)

Office 文件不经过版面和 OCR 模型:我们那份含两段文字和一张表格的 Word 文件不到一秒就转换完成。

10 · 保存一次,之后无需重新转换即可再导出#

pythonreexport.py
from docling.document_converter import DocumentConverter
from docling_core.types.doc import DoclingDocument

DocumentConverter().convert("report.pdf").document.save_as_json("report.json")

doc = DoclingDocument.load_from_json("report.json")   # 瞬间完成,不需要模型
doc.save_as_html("report.html")
print(doc.export_to_text()[:120])

11 · 把分块写成 JSONL,供向量库使用#

pythonchunks_jsonl.py
import json
from docling.chunking import HybridChunker
from docling.document_converter import DocumentConverter

doc = DocumentConverter().convert("report.pdf").document
chunker = HybridChunker(max_tokens=512)
with open("chunks.jsonl", "w") as f:
    for i, ch in enumerate(chunker.chunk(doc)):
        f.write(json.dumps({
            "id": f"report-{i}",
            "text": chunker.contextualize(ch),
            "headings": ch.meta.headings,
            "pages": sorted({p.page_no for it in ch.meta.doc_items for p in it.prov}),
        }) + "\n")

12 · 网页转 Markdown#

pythonhtml_url.py
from docling.document_converter import DocumentConverter

doc = DocumentConverter().convert("https://zh.wikipedia.org/wiki/光学字符识别").document
print(doc.export_to_markdown()[:400])

HTML 直接从 DOM 解析,因此转换很快,标题、列表和表格都能保留。

常见问题

官方的 Docling 示例在哪里?

Docling 文档在 docling-project.github.io/docling/examples 有示例部分。本页示例是独立编写的,更简短,每个都在 Docling 2.148.0 上运行过。

这些示例适用于旧版 Docling 吗?

大多数从 2.x 起即可使用,但部分 API(置信度报告、docling.chunking 导入路径)是较新的。如果缺少某些功能,请升级到页面顶部所示的版本。