Docling 文档分块（Chunking）完全指南：BaseChunker 抽象与 Hybrid / Hierarchical / Line-Based 分块器实战

Docling 文档分块Chunking完全指南BaseChunker 抽象与 Hybrid / Hierarchical / Line-Based 分块器实战【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/doclingDocling 提供了一组原生分块器native chunkers让你可以直接在结构化文档模型DoclingDocument上完成面向 RAG 与检索增强生成gen AI的文本切分而无需先导出 Markdown 再自行切分。本文围绕 Docling 的 chunking 概念页展开系统讲解BaseChunker抽象接口、HybridChunker、HierarchicalChunker与LineBasedTokenChunker三类分块器的原理与参数并结合仓库中的 CLI 实现、服务端配置模型与官方示例 Notebook给出可直接复制运行的实战代码。读完后你将能够为嵌入模型正确选择 tokenizer 与 max_tokens、控制表格表头在跨块场景下的重复行为以及通过自定义序列化器扩展 chunk 的文本呈现形式。两种分块思路原生 chunker vs 导出后处理从一份DoclingDocument出发原则上有两种分块路线导出 Markdown或类似格式后做用户自定义分块先把文档导出为 Markdown再在下游用任意方式切分。仓库中 LangChain RAG 示例 中就展示了这种 Markdown 导出模式的做法使用 Docling 原生 chunker直接操作DoclingDocument对象本身利用其内部结构信息标题层级、表格、图片、列表等生成带元数据的 chunk。本文聚焦第二种方式。chunker是 Docling 的一个抽象层给定一个DoclingDocument它返回一个 chunk 流stream每个 chunk 都以字符串形式捕获文档的某一部分并附带相应的元数据标题、说明文字、来源文档项引用等。为了兼顾下游应用的灵活性与开箱即用的便捷性Docling 定义了一个 chunker 类层级基类BaseChunker加若干具体子类。Docling 与 LlamaIndex 等 gen AI 框架的集成正是基于BaseChunker接口完成的因此用户可以方便地接入任何内置、自定义或第三方的BaseChunker实现。在docling包中这些分块器通过 docling/chunking/init.py 统一再导出from docling_core.transforms.chunker.base import BaseChunk, BaseChunker, BaseMeta from docling_core.transforms.chunker.hierarchical_chunker import ( DocChunk, DocMeta, HierarchicalChunker, ) from docling_core.transforms.chunker.hybrid_chunker import HybridChunker可以看到真正的实现位于docling_core.transforms.chunker命名空间docling.chunking只是包一层再导出的便捷入口。BaseChunker分块器的最小接口约定BaseChunker基类 API 规定任何 chunker 都应提供两个方法def chunk(self, dl_doc: DoclingDocument, **kwargs) - Iterator[BaseChunk] 返回所提供文档的 chunk 流惰性迭代适合处理大文档def contextualize(self, chunk: BaseChunk) - str 返回 chunk 的元数据增强后序列化文本通常用于喂给嵌入模型或生成模型——即在纯文本之前拼接上该 chunk 所属的标题、说明文字等上下文信息让下游模型知道这段文本来自文档的哪个部分。这两个方法构成了 Docling 与 gen AI 框架的集成契约只要实现该接口就可以被任意下游框架消费。HybridChunkertoken 感知的结构 长度混合分块引入方式如果你使用的是完整的docling包from docling.chunking import HybridChunker如果你只使用docling-core包则需按需安装 extra 后从核心路径导入# 使用 HuggingFace tokenizer 时安装 chunking extra pip install docling-core[chunking] # 或者使用 OpenAI tokenizertiktoken时 pip install docling-core[chunking-openai]from docling_core.transforms.chunker.hybrid_chunker import HybridChunker工作原理两遍 pass 的 token 感知精化HybridChunker采用混合策略在基于文档结构的层级式hierarchical分块结果之上应用 tokenization 感知的精化。具体来说它以层级分块器的输出为起点基于用户提供的 tokenizer通常应与嵌入模型的 tokenizer 对齐执行两遍处理第一遍只在必要时拆分split——即当某个 chunk 的 token 数超过上限时把它切小第二遍只在可能时合并merge——即把 token 偏小的相邻 chunk 合并起来前提是它们具有相同的标题与说明文字headings captions。用户可通过参数merge_peers关闭这一步默认True。这种先保结构、再控长度的设计使得 chunk 既保留了文档语义边界不会把两段不同主题的文字硬拼到一起又能稳定控制在嵌入模型可接受的 token 范围内。表头重复Table Chunking with Repeated Headers当用HybridChunker切分表格时可以控制表头table header的处理方式repeat_table_header默认True启用后当一张表横跨多个 chunk 时表头会在每个 chunk 的开头重复出现保证每个 chunk 都保有表格结构上下文检索回来的行不会因为缺少列名而无法被模型理解omit_header_on_overflow默认False与repeat_table_headerTrue联合使用为宽表提供灵活性——如果某一行在不带表头时能装进 token 上限、但带上表头会超限则该行所在的 chunk 会省略表头。这能在保留行完整性的同时最大化 token 利用率特别适合表头非常宽、或 token 预算非常紧张的场景。Hybrid 分块示例 Notebook 中给出了完整的表头重复用法以 CSV 宽表为例from docling_core.transforms.chunker.hierarchical_chunker import ( ChunkingDocSerializer, ChunkingSerializerProvider, ) from docling_core.transforms.serializer.markdown import ( MarkdownParams, MarkdownTableSerializer, ) # 自定义序列化器让表格以 Markdown 形式呈现 class MDTableSerializerProvider(ChunkingSerializerProvider): def get_serializer(self, doc): return ChunkingDocSerializer( docdoc, table_serializerMarkdownTableSerializer(), paramsMarkdownParams(compact_tablesTrue), ) small_tokenizer HuggingFaceTokenizer( tokenizerAutoTokenizer.from_pretrained(EMBED_MODEL_ID), max_tokens200, ) chunker_with_headers HybridChunker( tokenizersmall_tokenizer, repeat_table_headerTrue, # 每个 chunk 重复表头 serializer_providerMDTableSerializerProvider(), # 使用 Markdown 表格格式 ) csv_chunks list(chunker_with_headers.chunk(csv_doc)) for i, chunk in enumerate(csv_chunks[:3], 1): print(fChunk {i}: {chunk.text[:300]}...) print(fTokens: {small_tokenizer.count_tokens(chunk.text)})Line-Based Token Chunker保行完整的 token 分块器引入方式使用docling包时from docling.chunking import LineBasedTokenChunker只使用docling-core时先安装chunkingextra再from docling_core.transforms.chunker.line_chunker import LineBasedTokenChunker定位与能力LineBasedTokenChunker是一个 tokenization 感知、保持行边界的分块器特别适合表格、代码、日志、列表等结构化内容。它优先保证整行完整地落在单个 chunk 内只有当某一行自身就超过最大 token 限制时才被迫拆行。核心能力优先让整行保留在同一个 chunk 内支持为每个 chunk 附加一个重复前缀例如表格表头为每行提供结构上下文通过omit_prefix_on_overflow参数处理溢出设为True时如果某行带前缀会超 token 上限但不带前缀能放下则该行省略前缀从而保持行完整。Line-Based 分块示例 Notebook 演示了两种行为的对比以及直接对DoclingDocument分块from docling_core.transforms.chunker.line_chunker import LineBasedTokenChunker from docling_core.transforms.chunker.tokenizer.huggingface import HuggingFaceTokenizer from transformers import AutoTokenizer tokenizer HuggingFaceTokenizer( tokenizerAutoTokenizer.from_pretrained(sentence-transformers/all-MiniLM-L6-v2), max_tokens50, # 演示用的小上限 ) # 带表头前缀的分块器 chunker LineBasedTokenChunker( tokenizertokenizer, prefix| Name | Age | Department |\n|------|-----|------------|\n, omit_prefix_on_overflowFalse, # 默认总是包含前缀 ) lines [ | Alice | 30 | Engineering |\n, | Bob | 25 | Marketing |\n, | Charlie | 35 | Sales |\n, ] chunks chunker.chunk_text(lines) # 对行列表直接分块 for i, chunk in enumerate(chunks, 1): print(f Chunk {i} ) print(chunk) print(fTokens: {tokenizer.count_tokens(chunk)}\n)同样的 chunker 也可以直接作用于转换后的文档from docling.document_converter import DocumentConverter result DocumentConverter().convert(docs/examples/data/2408.09869v3_enriched.json) doc result.document chunker LineBasedTokenChunker( tokenizertokenizer, prefix, # 普通文档不需要前缀 ) chunks list(chunker.chunk(doc))示例中还展示了边缘行为当前缀本身超过max_tokens时构造器会发出警告并把前缀自行切分成prefix_chunksomit_prefix_on_overflowTrue与False的对比输出则直观体现了保行完整与保前缀上下文之间的取舍。HierarchicalChunker基于文档结构分块HierarchicalChunker直接利用DoclingDocument的结构信息为每一个检测到的文档元素段落、表格、图片等创建一个 chunk默认会把列表项合并到一起可通过参数merge_list_items关闭。它会负责挂接所有相关的文档元数据包括标题headings和说明文字captions。它是整个 chunker 层级的结构基准——HybridChunker的输入正是它的输出。由于它不做 token 长度控制适合一个元素一个 chunk的粗粒度检索策略或作为其他自定义分块逻辑的起点。Tokenizer 的选择与 max_tokens 设置HybridChunker和LineBasedTokenChunker都要求传入一个 tokenizer这是把文档结构与模型上下文窗口对齐的关键一环。仓库示例hybrid_chunking.ipynb展示了两种主流配置# HuggingFace tokenizer默认路径 from docling_core.transforms.chunker.tokenizer.huggingface import HuggingFaceTokenizer from transformers import AutoTokenizer EMBED_MODEL_ID sentence-transformers/all-MiniLM-L6-v2 MAX_TOKENS 64 # 示例中故意设小实际应不超过嵌入模型上下文长度 tokenizer HuggingFaceTokenizer( tokenizerAutoTokenizer.from_pretrained(EMBED_MODEL_ID), max_tokensMAX_TOKENS, # 可选HF 情况下默认从 tokenizer 上下文长度推导 ) # OpenAI tokenizertiktoken # import tiktoken # from docling_core.transforms.chunker.tokenizer.openai import OpenAITokenizer # tokenizer OpenAITokenizer( # tokenizertiktoken.encoding_for_model(gpt-4o), # max_tokens128 * 1024, # OpenAI 系模型需要按其上下文窗口显式给出 # )实践要点max_tokens应与你最终使用的嵌入或生成模型的 tokenizer 与上下文上限对齐——示例中默认使用的sentence-transformers/all-MiniLM-L6-v2即是一个常见默认值若不给max_tokensHuggingFace 路径下会从 tokenizer 自身的上下文长度自动推导分块后用tokenizer.count_tokens(chunk.text)可校验每个 chunk 是否确实落在预算内这也是示例 Notebook 中每轮打印 token 数的原因。CLI 中的原生分块--to chunksDocling 命令行直接把原生分块做成了导出格式。从 docling/cli/main.py 的源码可以看到chunker_type: ChunkerType ChunkerType.HYBRID, chunk_max_tokens: int | None None, chunk_tokenizer: str sentence-transformers/all-MiniLM-L6-v2,if export_chunks: ... if chunker_type ChunkerType.HIERARCHICAL: chunker_obj HierarchicalChunker() else: # 默认hybrid hf_tok HuggingFaceTokenizer.from_pretrained( model_namechunk_tokenizer, max_tokenschunk_max_tokens, ) chunker_obj HybridChunker(tokenizerhf_tok)对应的相关 CLI 选项同文件约 L750-L760--to chunks以 JSONL 形式导出 chunk每个文档生成.chunks.jsonl--chunks-type选择hierarchical或hybrid默认hybrid--chunks-max-tokens每个 chunk 的最大 token 数缺省使用 tokenizer 自身的上限--chunks-tokenizerHuggingFace tokenizer 模型名默认sentence-transformers/all-MiniLM-L6-v2。从源码看docling/cli/main.py导出的每条 chunk 记录包含raw_textchunk 原文、textcontextualize后的元数据增强文本、headings、captions、doc_items组成该 chunk 的文档项self_ref列表与origin来源页信息并在 hybrid 模式下额外记录num_tokens。这意味着 CLI 输出的 chunk 可直接用于构建索引同时保留了回溯到原文档结构的能力。服务端配置Chunker 选项模型如果你通过 Docling 服务service_client远程调用分块配置由 docling/datamodel/service/chunking.py 中的 Pydantic 模型描述class BaseChunkerOptions(BaseModel): chunker: ChunkerType # hierarchical | hybrid use_markdown_tables: bool False # 表格用 Markdown 格式序列化 use_markdown_images: bool False # chunk 中序列化图片引用并增加 has_image 元数据 image_placeholder: str ![IMAGE] # 关闭 markdown 图片时使用的占位符 include_raw_text: bool False # 响应中同时给出 raw_text 与 textHybridChunkerOptions在此之上增加三个 hybrid 专属参数class HybridChunkerOptions(BaseChunkerOptions): chunker: Literal[ChunkerType.HYBRID] ChunkerType.HYBRID max_tokens: Optional[int] None # 为 None 时从 tokenizer 自动提取 tokenizer: str sentence-transformers/all-MiniLM-L6-v2 # HF 模型名 merge_peers: bool True # 合并具有相同标题的偏小相邻 chunk注意与 API 层的区别Python 本地调用时max_tokens直接传给HuggingFaceTokenizer构造而服务端选项中tokenizer是字符串模型名、由服务端实例化。service_client/client.py 与 _async_client.py 中chunking_options参数的默认值即HybridChunkerOptions()/HierarchicalChunkerOptions()。进阶自定义序列化与 Chunk 扩展Advanced chunking serialization 示例 展示了HybridChunker的两个高级扩展点都是基于序列化器提供器ChunkingSerializerProvider机制更换表格序列化器如上文MDTableSerializerProvider让表格 chunk 以 Markdown 呈现自定义图片占位与序列化通过MarkdownParams(image_placeholder!-- image --)修改图片占位符或继承MarkdownPictureSerializer把图片的分类结果、SMILES、描述文本等元数据直接写进 chunk 文本Chunk 扩展器chunk expanderTreeChunkExpander可把被 token 上限截断的表格 chunk 反向扩展到其完整的所属文档项完整表格PageChunkExpander则扩展到整个所属页面。当嵌入/生成阶段需要完整上下文而检索阶段需要小粒度时这种双向能力很有价值from docling_core.transforms.chunker.chunk_expander import ( PageChunkExpander, TreeChunkExpander, ) tree_expander TreeChunkExpander() expanded_chunk tree_expander.expand( chunktable_chunk, dl_docdoc, serializerserializer )此外该示例还演示了通过MarkdownParams(traverse_picturesTrue)控制是否遍历图片生成对应 chunk以及用chunker.chunk(doc)直接处理经 OCR 转换的扫描 PDF 文档。参考示例与延伸阅读Hybrid 分块示例Notebooktokenizer 配置、merge_peers、表头重复Line-based 分块示例Notebook行边界保持与前缀溢出处理进阶分块与序列化示例Notebook自定义序列化器、chunk 扩展器相关概念页DoclingDocumentchunker 的输入对象、序列化chunk 文本呈现的底层机制。总结来说Docling 的 chunking 体系以BaseChunker接口为契约以HierarchicalChunker为结构基础以HybridChunker为默认的 token 感知生产选择并辅以LineBasedTokenChunker应对表格/代码/日志等行敏感内容再通过 CLI 的--to chunks、服务端ChunkerOptions与自定义序列化器/扩展器覆盖了从本地脚本到远程服务、从默认行为到深度定制的完整链路。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考