1 · PDF 转 Markdown,图片单独保存为文件#
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 · 转换整个文件夹,跳过坏文件,并生成报告#
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 工作簿#
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 文件#
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)。
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 · 导出插图及其图注#
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、上传文件、邮件附件)#
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 · 只转换前几页#
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#
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 · 保存一次,之后无需重新转换即可再导出#
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,供向量库使用#
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#
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 导入路径)是较新的。如果缺少某些功能,请升级到页面顶部所示的版本。
内容准确吗?当 Docling 新版本改变行为时,我们会重新验证页面。如果某条命令对你无效,请把 Docling 版本号和报错发到 hello@docling.org,更正通常一天内上线。