RAG 文档切分怎样按标题层级保留上下文

RAG 文档按标题层级切分，应先识别章节，再在每个章节内按长度细分；每个子切片都继承完整标题路径及来源标识。只保留正文容易失去适用范围，只把标题存进 metadata 又不传给模型，也未必补回上下文。切片契约应同时约束正文、检索文本、生成上下文和引用信息。

本文讨论切片能力的设计改造，不是一则新版本发布公告。以 Markdown 为例，使用 LangChain 文本切分器展示写法。官方文档地址：https://docs.langchain.com/oss/python/integrations/splitters/markdown_header_metadata_splitter。代码和图示均为原创教学输入，未执行，也不提供检索效果实测结论。

把标题路径变成切片契约，而不只是前缀

假设知识库文档有“工作区说明”这个一级标题，下面分别是“试用环境”和“团队环境”。两个章节都写着“任务完成后可释放资源”，但授权条件不同。只检索这句话，模型可能无法判断读者正在使用哪一种环境。

建议每个切片保存 doc_id、revision、section_id、heading_path 和 source_uri。doc_id 表示文档身份，revision 表示内容版本，section_id 区分章节，heading_path 是由一级到当前层级的有序路径；source_uri 指向可定位的来源。正文仍应保留原始证据，标题不是额外创造的事实。

先按章节分组，再让子片段继承信息

MarkdownHeaderTextSplitter 可以将配置的标题层级映射到元数据。默认移除正文中的这些标题；示例采用默认行为，再由元数据构造完整路径。长章节继续用 split_documents 细分，保留各章节的 metadata；不要改成对所有正文拼接后做一次无来源的 split_text。

from langchain_text_splitters import (
    MarkdownHeaderTextSplitter,
    RecursiveCharacterTextSplitter,
)

# 原创示例文档，两个同级章节的适用范围不同
markdown = """# 工作区说明
## 试用环境
任务完成后可释放资源。只处理本人创建的演示任务。
## 团队环境
任务完成后可释放资源。共享任务须由工作区负责人确认。
"""
headers = [("#", "h1"), ("##", "h2"), ("###", "h3")]
sections = MarkdownHeaderTextSplitter(
    headers_to_split_on=headers, strip_headers=True,
).split_text(markdown)

for number, section in enumerate(sections):
    # 教学用版本内顺序标识；生产需由解析器提供稳定章节身份
    section.metadata.update({
        "doc_id": "workspace-guide",
        "revision": "demo-revision-a",
        "section_id": f"section-{number}",
        "source_uri": "knowledge://workspace-guide",
    })

# 此处长度单位是字符，不是模型 token；仅用于说明二次细分
chunks = RecursiveCharacterTextSplitter(
    chunk_size=180, chunk_overlap=24,
).split_documents(sections)

for chunk in chunks:
    # 子切片继承章节元数据，构造从父标题到子标题的完整路径
    chunk.metadata["heading_path"] = [
        chunk.metadata[key] for key in ("h1", "h2", "h3")
        if key in chunk.metadata
    ]

knowledge:// 是本例内部来源标识，不是已经存在的公开下载地址；正式知识库应改成自己的可定位来源。示例 section_id 用顺序号，章节前插入新内容时它会改变，因此不能当作永久更新键。

chunk_overlap 在同一章节的长度细分中发挥作用，不跨章节自动补全内容；短章节不需要切成多个子片段时，也不会凭空生成重叠。字符参数只是演示值，最终应使用适合目标模型的长度计算方式，并为标题、引用包装与回答预留上下文预算。

metadata 保留下来，还要让检索与生成看得到

有些向量化管线只处理 page_content，不会自动把任意 metadata 拼进 embedding 输入。因而保留了 heading_path，不等于标题已经参与向量表示。可以显式构造检索文本，同时保留正文与字段，避免难以追溯的重复拼接。

# 示例构造检索文本，不调用 embedding API、不写入向量库
for chunk in chunks:
    path = " / ".join(chunk.metadata["heading_path"])
    retrieval_text = f"章节：{path}\n正文：{chunk.page_content}"
    record = {
        "retrieval_text": retrieval_text,
        "body": chunk.page_content,
        "metadata": dict(chunk.metadata),
    }
    # 只展示元数据键，避免把私有文档全文写入日志
    print(sorted(record["metadata"]))

这是一种可评估的工程方案，不保证标题越多检索越好。高频一级标题在每个片段重复，可能压过具体内容；可以比较“正文”与“短标题路径加正文”两种输入，按真实问题观察变化，不用猜测命中率。

检索返回后，生成上下文也应带标题路径、正文和可定位来源；不能只把向量匹配的纯文本丢给模型。邻接扩展若要补前后片段，应限于同文档、同版本、同权限范围，优先同章节，不能为了“上下文完整”把无权查看的内容一起带入。

旧索引迁移时，不要混用两套切片规则

旧代码可能把 chunk_id 设为序号，并假设每份文档产生固定数量片段。改成按标题切分后，数量、边界和排序都可能变化；旧邻接关系与引用偏移不能直接沿用。建议把 splitter_version 与来源 revision 一起写入索引记录，明确本次内容属于哪一种规则。

可以在独立索引中重建，保留旧索引直到读者自己的对照任务完成，再切换查询入口。embedding 输入若增加标题，即使正文不变，向量也应按新规则重建；不能只补 metadata 就宣称完成语义索引迁移。不同 embedding 模型、维度或归一化策略也要保持各自一致。

同名标题需要章节身份来区分；没有标题的开头正文可以归入明确的文档根章节，而不是默默删除。PDF 转 Markdown、扫描件和网页中的标题层级可能丢失，要先处理转换质量。表格、代码块和跨段落限定条件也不能仅按字符切割后就假设仍完整。

用小样本文档核对边界，再决定上线

读者可准备一份包含同名标题、嵌套小节、长章节、无标题前言和代码围栏的测试文档。预期应包括：同级章节不继承上一个兄弟章节的低级标题；长章节所有子片段保有同一条 heading_path；每个片段能够定位来源和版本；代码围栏里的井号不应被误当文档标题。这些是建议的核对目标，不是本文执行过的测试。

正文保留格式与来源偏移的要求较高时，应选择适合文档格式的解析器；默认 Markdown 切分器并不等于精确保留全部空白或原文件位置。不要在没有原始定位信息时伪造页码、行号或精确引用。

最终判断不是“每片都有一个标题”就够了，而是切片单独返回时能说明所属章节，检索输入能表达必要语境，生成回答能引用可追溯证据，更新文档时旧切片可被正确替换。

相关问题

strip_headers=False 会给每个子片段补完整父标题吗？不能作这种假设。保留文本中出现的标题与显式继承完整路径是不同职责，应以 metadata 构造所需路径。

按标题切分后还需要长度限制吗？需要。一个章节可能很长，标题分组不保证符合模型输入上限。

来源 URL 是否必须参与 embedding？不必机械加入。来源字段主要承担定位和引用职责，是否进入检索文本应按业务评估。

元数据传递的另一框架参考：https://docs.haystack.deepset.ai/docs/documentsplitter。不同框架的字段名称和默认行为不完全相同，应显式映射，不直接混用代码。