RAG切分长文档时按标题层级保留上下文的策略

长文档做 RAG 时，固定长度切块最容易留下一个问题：检索命中了正文，却丢了它属于哪个章节。更稳妥的做法是先解析标题树，再让每个 chunk 同时携带标题路径、来源位置和文档版本。这样向量负责找相关片段，metadata 负责把片段还原成可解释的上下文。

一、先把标题树压成 heading_path

解析 Markdown、HTML 或 PDF 时，维护一个按层级变化的标题栈。遇到二级标题就截断更深层级，遇到三级标题就替换三级位置；正文节点继承当前栈的副本。不要只保存最后一个标题，否则“超时配置”在不同章节中会变成同一个模糊标签。

二、让 chunk_text 和 metadata 各司其职

Hugging Face 的 RAG 文档把被检索内容作为文档输入，并强调检索器返回文档内容与相关分数；实际工程还需要保留能回到原文的字段。建议至少保存 doc_id、heading_path、source、section_index、chunk_index 和 version。

def make_chunk(node, text, doc_id, source, section_index, chunk_index, version):
    # 标题路径放入正文前缀，让模型脱离相邻片段也能理解主题。
    heading_path = " / ".join(node["heading_path"])
    chunk_text = f"章节：{heading_path}\n\n{text.strip()}"
    return {
        "text": chunk_text,
        "metadata": {
            "doc_id": doc_id,              # 用于同一文档内去重和回链
            "heading_path": heading_path,  # 用于显示章节语境
            "source": source,              # 用于引用原始文件或 URL
            "section_index": section_index,
            "chunk_index": chunk_index,
            "version": version,            # 文档更新后避免混入旧片段
        },
    }

这里没有把所有父级正文复制进每个 chunk。父级标题通常很短，复制标题成本可控；父级正文则可能造成重复向量和上下文膨胀，应该在召回阶段按需要补邻近片段。

三、优先在语义边界切分，超长节点再兜底

一个标题下的段落、列表和代码块应尽量保持完整。可以先按段落累加 token，接近上限时结束当前 chunk；遇到单个超长代码块或表格，再按行或记录切开，并保留一个小的 overlap。不要为了填满窗口把列表中间截断，否则检索结果可能只剩参数名，没有参数含义。

四、召回后按章节重建上下文

向量检索返回多个相似 chunk 时，先按 doc_id + section_index + chunk_index 去重，再给同一章节设置数量上限。命中一段时可补取前后相邻片段，但不要把整章无条件塞给模型。最终上下文可采用“标题路径—来源—正文”的固定顺序，让回答同时具备主题和出处。

五、用三项指标判断切分是否有效

不要只看相似度分数。抽样问题时记录命中的 heading_path 是否正确、答案引用是否能回到 source，以及上下文中与问题无关的片段比例。若同一问题总命中相邻章节，优先检查标题栈和 section_index；若命中正确但答案缺少限定条件，检查切块是否把列表、表格或代码块截断。

相关问题

标题路径应该放进向量正文吗？

建议放入简短前缀，同时保留 metadata。前缀帮助语义检索，metadata 方便过滤、排序和展示，两者用途不同。

chunk 越大，RAG 回答就越完整吗？

不一定。chunk 过大会混入无关段落，过小又会丢条件和定义，应以问题命中率、引用完整性和上下文噪声共同调参。

文档更新后如何避免新旧 chunk 混在一起？

为文档生成稳定的版本字段，更新时按 doc_id 和 version 做删除或过滤，并在召回结果中记录实际版本。