Docling 用于 RAG

RAG 流水线共六段，Docling 拥有前三段——它们在任何嵌入存在之前决定答案质量。两种分块哲学：导出 Markdown 再切（如 LangChain 的 MarkdownHeaderTextSplitter），或在 DoclingDocument 上原生分块。原生分块保留 Markdown 再切悄悄丢掉的表格、标题与出处，除有理由一律优先原生。

• 解析——版式、阅读顺序、表格、公式、图片 → 结构化 DoclingDocument。
• 序列化 / 分块——带标题、表题与出处的结构化分块（或导出 Markdown/HTML/JSON 再切）。
• 文本增强——contextualize() 前置标题上下文，使每块自足。
• 嵌入 → 入库 → 检索 → 生成——自选嵌入模型、向量库与框架，与 Docling 无关。

程序化流水线请在 Python 中转换并保留文档对象，分块器作用于对象而非文件：

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("report.pdf")
document = result.document

导出是序列化器的简写（MarkdownDocSerializer 等）。对 RAG 而言选择关键在表格。若合并表头格决定答案，请选 HTML 或 JSON 而非 Markdown，或保留 Markdown 但在分块时复述表头（第 7 节）。序列化器可定制：子类化 BaseTableSerializer 等完全掌控（见高级分块与序列化示例）。

全部原生分块器实现 BaseChunker（chunk() 输出分块流，contextualize() 输出增强文本），故 LlamaIndex 类集成经同一接口接纳内置、自研或第三方分块器。

原理：从层级分块起步，一遍仅切分超限块（词元感知），另一遍仅合并同标题同表题的连续不足 peer。关键参数：

嵌入上下文化文本，而非 chunk.text：

两条运维提示：分块时的 transformers「Token indices sequence length …」警告是已归档的误报（见官方 FAQ），服务端以 TOKENIZERS_PARALLELISM=false 压住 fork 警告。

• tokenizer——对齐嵌入模型分词器（第 9 节）。默认从分词器推导上限。
• max_tokens——每块上限；应容下增强（上下文化）形态。
• merge_peers=True——合并不足 peer；严格切分则置 False。
• repeat_table_header=True——每表格块以表头行开头（第 7 节）。
• omit_header_on_overflow=False——去表头可容纳、带表头则溢出的行省略表头（宽表、严格预算）。
• serializer_provider——如经 ChunkingSerializerProvider 的 Markdown 表格，控制块文本形态。

from docling.chunking import HybridChunker

chunker = HybridChunker()
chunks = list(chunker.chunk(document))
print(len(chunks), chunks[0].text[:120])

for chunk in chunker.chunk(document):
    enriched = chunker.contextualize(chunk)  # 前置标题，请嵌入这个
    vector = embed(enriched)

完整演示：混合分块（含宽 CSV 表头复述）、按行分块、表格抽取。

• 复述表头（repeat_table_header=True，默认）：被切散表格的每块以表头行开头，每块对嵌入模型自描述。
• 溢出逃生（omit_header_on_overflow=True）：宽表中去表头可容纳、带表头则溢出的行省略表头，省词元不断行。
• 合并格：Markdown 拍平合并信息；若关键，请从 HTML/JSON 序列化分块或自研表格序列化器。
• 按行备选：LineBasedTokenChunker 加重复前缀保 CSV 式行完整，同经 omit_prefix_on_overflow 处理溢出。

每块携带 dl_meta，请保留在向量载荷中，它把「一个答案」变成「有出处的答案」。出处含逐项页码与边框，足以支撑「第 3 页」引用或源区高亮（见视觉定位）。切勿为「省空间」丢元数据，否则引用无从谈起。

铁律：以嵌入模型的分词器度量分块。分词器错配悄悄量错尺寸，破坏合并切分决策。大规模下 Data Prep Kit 分块 + 分词流水线批量贯彻同一原则。

from transformers import AutoTokenizer
from docling_core.transforms.chunker.tokenizer.huggingface import HuggingFaceTokenizer
from docling.chunking import HybridChunker

EMBED_MODEL_ID = "sentence-transformers/all-MiniLM-L6-v2"
tokenizer = HuggingFaceTokenizer(
    tokenizer=AutoTokenizer.from_pretrained(EMBED_MODEL_ID),
    max_tokens=512,
)
chunker = HybridChunker(tokenizer=tokenizer, merge_peers=True)

LangChain——langchain-docling：两种模式：DOC_CHUNKS（默认，每个原生块一个 LangChain Document，元数据完整）与 MARKDOWN（每文件一个 Document，下游再切，如以 MarkdownHeaderTextSplitter 按 #/##/###）。完整流程见官方 LangChain RAG 示例（Milvus + Mixtral）与 LangChain 指南。

LlamaIndex——Reader + Node Parser：DoclingReader 填充 LlamaIndex Document（JSON 无损或 Markdown 有损）；Docling Node Parser 凭格式知识转为 Nodes。任何 BaseChunker 实现接入同一接口。见官方 LlamaIndex RAG 示例。

Haystack 及其他：Haystack 以 Docling 为转换器组件（示例、集成文档）。三巨头之外：txtai、Kotaemon、DocETL、Vectara、Semantica、Hector、haiku.rag、Bee、CrewAI、Langflow、Open WebUI、spaCy、NVIDIA、Granite cookbook RAG 与 Data Prep Kit 均集成 Docling，浏览官方集成索引。

from transformers import AutoTokenizer
from docling_core.transforms.chunker.tokenizer.huggingface import HuggingFaceTokenizer
from docling.chunking import HybridChunker
from langchain_docling import DoclingLoader
from langchain_docling.loader import ExportType

tokenizer = HuggingFaceTokenizer(
    tokenizer=AutoTokenizer.from_pretrained("sentence-transformers/all-MiniLM-L6-v2")
)
loader = DoclingLoader(
    file_path=["https://arxiv.org/pdf/2408.09869"],
    export_type=ExportType.DOC_CHUNKS,  # 原生块（默认）
    chunker=HybridChunker(tokenizer=tokenizer),
)
docs = loader.load()  # 每块一个 LangChain Document，dl_meta 在 metadata

from llama_index.readers.docling import DoclingReader

reader = DoclingReader(export_type="json")  # 无损；"markdown" 有损
documents = reader.load_data("report.pdf")

存储从不影响 Docling，分块加嵌入哪里都可入库。官方实例覆盖：

--chunks-type 取 hybrid（默认）或 hierarchical；分词器默认 sentence-transformers/all-MiniLM-L6-v2。远端转换（docling convert-remote / docling-serve）服务端支持同样分块选项。见命令查找。

• 分词器 == 嵌入模型。永远如此，每次换模型复查。
• 嵌入 contextualize() 输出，chunk.text 另存展示。
• 保留 DocMeta（headings、page_no、bbox、origin）于载荷供引用。
• 复述表格表头；合并格表格用 HTML/JSON 源。
• 压缩转换成本：数字 PDF 用 --no-ocr，跳过无用富化，批量转换并预下载模型（docling-tools models download --all）。

• 横向扩展：语料用 Data Prep Kit 分块 + 分词；服务用队列后的 docling-serve /v1/convert/source 加 --to chunks。
• PII 先行：嵌入前检测脱敏 PII（见PII 示例），泄露无法反嵌入。

• 答案缺上下文 /「孤儿」块——嵌入了 chunk.text；改 contextualize() 并确认标题。
• 表格答错——启用 repeat_table_header；检查合并格（Markdown 拍平合并信息，用 HTML/JSON）。
• transformers 长度警告——已归档误报，可忽略（官方 FAQ）。
• 块相对模型过大过小——分词器错配，锁定模型分词器并调 max_tokens。
• 无法引用——入库丢元数据，持久化 dl_meta（page_no、headings、origin）。
• 摄取太慢——见转换慢：关闭多余 OCR/富化，用 GPU，批量。

已按 Docling v2.129.0 验证 · 最近检查 2026-09-22 · 官方来源