跳到主要内容
Ed. notes

切片:结构优先,长度兜底

长文 · 2026-11-11 · 合集第 6 / 11 篇

  • RAG
  • Markdown
  • 文本切片
第 6 / 11 篇 · 查看全部章节 → 当前:切片:结构优先,长度兜底

结论

切片的目标不是每块字符数一致,而是让检索命中的片段仍然有语义上下文。当前实现先按 Markdown 标题分章节,保留标题路径;超长章节再按段落兜底。只有标题、没有正文的片段直接跳过,避免短标题污染相似度。

问题与设计

整篇文章直接 embedding 有两个问题:检索粒度太粗,命中后不知道哪一段相关;长文也可能超过模型输入限制。简单按固定字符数截断又会切开句子、代码块和标题关系。

这里采用两层策略:

  1. 结构优先:按标题切章节,每块携带 heading_path。
  2. 长度兜底:章节超过 1200 字符才按段落拆,目标约 700 字符,允许一个不超过 160 字符的末段重叠。

代码块通常没有空行,因此按段落拆不会把它切开。单段特别长时保留整体,不强行截断。

关键代码

主循环:

for heading_path, section in _sections(document.body):
    for piece in _split_section(section):
        if not _has_body(piece):
            continue
        chunks.append(Chunk(
            id=hash_text(f"{document.slug}\n{'/'.join(heading_path)}\n{position}\n{piece}"),
            document_slug=document.slug,
            heading_path=heading_path,
            position=position,
            text=piece,
            content_hash=hash_text(piece),
        ))

标题栈维护层级路径:

while stack and stack[-1][0] >= level:
    stack.pop()
stack.append((level, heading))
current_path = tuple(item[1] for item in stack)

例如 # 安装 / ## 本地环境 / ### 数据库 会得到:

('安装',)
('安装', '本地环境')
('安装', '本地环境', '数据库')

判断片段是否有正文,而不是只有标题:

def _has_body(piece: str) -> bool:
    return any(
        line.strip() and not line.lstrip().startswith("#")
        for line in piece.splitlines()
    )

稳定 ID 由 slug、标题路径、position 和正文共同决定。内容不变时重复切片得到相同 ID;正文、位置或标题层级变化时 ID 改变。content_hash 单独记录正文 hash。

验证

当前内容的切片统计:

documents: 18
chunks: 131
avg chars: 378.3
max chars: 1148

标题路径样例:

('示例',)                     # 文档开头
('示例', '安装')              # 一级章节
('示例', '安装', '命令')      # 二级章节
('示例', '原理')              # 回到同级

测试还验证:同一文档 ID 稳定;改正文后 ID 与 content hash 都变化;长章节产生多个切片;代码块 fence 保持成对。

边界

  • _CHUNK_MAX 是触发拆分阈值,不是绝对上限;单段特别长时会超出。
  • 按字符数不是按 token 数,不同语言和模型的分词差异很大。
  • 标题本身会保留在章节文本里,同时又有 heading_path;这是为了可读性有意重复。
  • 稳定 ID 包含 position,在前面插入内容会改变后续 ID,不是完全的内容寻址。
  • 跳过只有标题的片段会减少噪声,但也意味着纯标题结构不会单独成为检索结果。

下一篇看向量与入库:Chunk 怎样变成 pgvector 中的一行,以及为什么要先准备完全部向量再替换索引。