按标题结构切分
结构化切分按 Markdown 的标题层级下刀，每个切片天然携带所在章节的标题路径（一级、二级、三级标题）。对文档站、产品手册、规范说明这类层次清晰的内容，它既让检索结果更好读，也让引用标注能直接指出是哪一节，便于人工核对。
基本信息
| 适用 | Markdown、文档站、层次清晰的规范类内容 |
|---|---|
| 输出 | 文本片段 + 标题路径元数据 |
| 典型工具 | MarkdownHeaderTextSplitter |
| 局限 | 标题缺失或层级混乱的文档粒度会失控 |
MarkdownHeaderTextSplitter
MarkdownHeaderTextSplitter
from langchain_text_splitters import MarkdownHeaderTextSplitter
splitter = MarkdownHeaderTextSplitter(
headers_to_split_on=[("#", "h1"), ("##", "h2"), ("###", "h3")],
)
docs = splitter.split_text(md_text)
print(docs[0].metadata) # {'h1': ..., 'h2': ...}
print(docs[0].page_content[:80])使用要点
- 标题路径写进元数据：检索结果展示与引用标注都依赖它
- 超长章节二次切分：按标题切完再对每节做递归切分，兼顾结构与粒度
- 过短章节合并：只有一两行的章节可与相邻同节内容合并，避免碎片
- 保留标题文本在片段内：检索时段落脱离标题容易失去语境
- 先规范化标题：统一层级写法，避免同级标题混用不同符号
与其它切分方式的组合
| 组合 | 做法 | 适用 |
|---|---|---|
| 标题 + 递归 | 先按标题分节，再按长度细分 | 文档站与手册的常规选择 |
| 标题 + 固定长度 | 按标题分节后按字符滑窗切 | 节的长度差异大时 |
| 纯标题 | 节点短且均匀时直接使用 | FAQ 与速查表 |
| 标题 + 表格单独处理 | 表格从正文剥离后独立成块 | 技术文档里表格密集的场景 |
超长章节可在标题切分后再对每节做递归切分，两级组合兼顾结构与粒度；切分后记得检查是否出现只有标题没有正文的空片段。
上线检查
- 统计切片长度的分布，明显偏短的碎片占比过高时先合并再入库
- 确认每片都带标题路径，缺失的片段在回答里无法指明出处
- 检查代码块与表格是否被标题切分打断，必要时先剥离再切
- 用几条跨章节的问题测检索，验证答案要点不会被章节边界切散
- 文档改版后重新切分并对比切片数量，数量突变通常意味着结构被改动