Docling 如何用 NativePdfPipeline 快速提取 PDF 原生文本而不跑布局模型？

当你手上的 PDF 自带文本层，而任务只是把里面的文字（和嵌入图片）抽出来装进 DoclingDocument 时，默认的 standard 管线会多余地跑布局检测、OCR 和表格结构模型，这些模型还需要下载和加载。Docling 的 NativePdfPipeline 专门解决这个问题：它只用 docling-parse 解析 PDF 原生内容——每个原生文本单元（text cell）变成一个文本项，每个嵌入位图变成一个图片项，不跑任何布局、OCR 或表格模型（docs/usage/advanced_options.md 中的 "Extract the native content of a PDF" 一节）。本文给出从安装到验证结果的完整路径，以及这条管线的明确限制。

NativePdfPipeline 能提取什么、不能提取什么

先确认你的目标是否在它的能力范围内（以下行为来自 native_pdf_pipeline.py 的实现说明）：

• 能：PDF 后端报告的每个文本单元变成一个带 provenance 框（页码、bbox、charspan）的普通 TextItem；每个嵌入位图变成一个 PictureItem；按需给每页附加渲染图。
• 不能：结果文档没有阅读顺序、没有标题层级、没有表格结构——条目按解析器报告的顺序出现。需要结构化输出时应使用带布局模型的默认管线。
• 不跑 OCR，文字只能来自 PDF 本身已编码的文本层；纯扫描页没有可提取的文本。
• 要求输入走 PDF 后端：NativePdfFormatOption 默认使用 ThreadedDoclingParseDocumentBackend；CLI 中 --pipeline native 明确要求 docling-parse 类后端，传入其他 PDF 后端会直接报错 Error: --pipeline native requires a docling-parse PDF backend 并中止。

准备：安装 Docling

按 安装文档 从 Python 包管理器安装即可，支持 macOS、Linux、Windows 的 x86_64 与 arm64：

pip install docling

这条管线不加载任何模型，因此不需要做模型预下载（docling-tools models download 是给布局、表格等模型准备的，本文场景用不到）。

命令行路径：一条命令提取

最短路径在 docs/reference/cli.md 中定义：

docling --pipeline native --from pdf FILE

FILE 是待转换的本地 PDF 路径（源文档中的占位符，替换为你的文件）。命令中各参数：

• --pipeline：可选 legacy、standard、native、vlm、asr，默认是 standard。只有 native 对应 NativePdfPipeline，漏写就会退化为跑模型的默认管线。
• --from pdf：限定输入格式为 PDF。
• --parser-threads（可选）：PDF 解析工作线程数。由于这条管线不跑模型，解析线程是它唯一的并行度，默认值为机器 CPU 线程数减一：

docling --pipeline native --from pdf --parser-threads 8 FILE

CLI 还会自动处理页面渲染：只有当导出格式需要携带图片时才渲染页面图（images_scale=2），否则跳过渲染只解析，避免为不用的产物付出光栅化开销。

Python 路径：配置并运行

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import NativePdfPipelineOptions
from docling.document_converter import DocumentConverter, NativePdfFormatOption

pipeline_options = NativePdfPipelineOptions()
pipeline_options.generate_page_images = True
pipeline_options.images_scale = 2.0

doc_converter = DocumentConverter(
    format_options={
        InputFormat.PDF: NativePdfFormatOption(pipeline_options=pipeline_options)
    }
)

result = doc_converter.convert("report.pdf")  # 替换为你的本地 PDF 路径
doc = result.document

注意两点：DocumentConverter() 不传 format_options 时默认走 StandardPdfPipeline，所以必须显式传 NativePdfFormatOption；它接收 NativePdfPipelineOptions 时会自动配置底层 ThreadedDoclingParseBackendOptions（解析线程数、位图解码、页面渲染都与管线选项对齐）。

NativePdfPipelineOptions 中与本场景直接相关的选项：

选项	默认值	用途
generate_page_images	True	给每页附加按 images_scale 像素/点渲染的页面图。设为 False 则跳过渲染只解析，文档明确说明这样更快
images_scale	由示例显式设为 2.0	页面渲染的像素/点比例，也决定输出页面图的 DPI（72 * images_scale）
parser_threads	机器 CPU 线程数减一（最小 1）	PDF 解析工作线程数；模型的 accelerator_options 在这条管线中不生效
text_cell_unit	TextCellUnit.LINE	文本项粒度：按行（默认）、按词或按字符；docling-parse 后端支持词和行
generate_picture_images	True	把嵌入位图附到图片项上。需要后端 include_bitmap_images=True，NativePdfFormatOption 会按此选项自动设置

只要文字、不需要页面图时，把 generate_page_images 设为 False 是最直接的提速手段。

验证提取结果

验证方式与 tests/test_native_pdf_pipeline.py 中的断言一致：

from docling.datamodel.base_models import ConversionStatus

print(result.status)  # 期望 ConversionStatus.SUCCESS

# 文本项数量与非空
print(len(doc.texts) > 0)

# 每个文本项的 provenance：页号、bbox、字符区间
for text in doc.texts:
    prov = text.prov[0]
    assert prov.charspan == (0, len(text.text))

# 导出 Markdown 查看整体内容
print(doc.export_to_markdown())

逐项判断：

• result.status 为 ConversionStatus.SUCCESS，说明全部页面解析成功。
• doc.texts 非空，且每个文本项带一条 provenance：page_no 为所在页、bbox 为左下原点且落在页面尺寸内、charspan 覆盖整个文本。
• 图片项在 doc.pictures 中；默认（generate_picture_images=True）时每项带 image，设为 False 时仍保留但 image 为 None（只有位置框）。
• generate_page_images=False 时，doc.pages[1].image 为 None，但文本项照常产出——这是判断"跳过渲染是否生效"的直接依据。

限制与失败形态

• 单页解析失败不会终止整个文档：该页会记录一条 ErrorItem（含页码和错误信息），整体状态变为 PARTIAL_SUCCESS，其余页面正常产出。
• document_timeout 超时时同样停止在当前页，标记 PARTIAL_SUCCESS 并写入 timeout 错误项。
• 若后端渲染比例与管线要求的 images_scale 不一致，每个页面会被光栅化两次（第二次串行执行），日志会给出 warning 并提示把后端 render_scale 设为与 images_scale 相同。
• 需要阅读顺序、标题、表格结构或扫描版 OCR 时，NativePdfPipeline 不适用，应换回默认的 standard 管线。

更多背景可查阅 docs/usage/advanced_options.md、docs/reference/cli.md 与管线实现 docling/pipeline/native_pdf_pipeline.py。