切片:结构优先,长度兜底
结论
切片的目标不是每块字符数一致,而是让检索命中的片段仍然有语义上下文。当前实现先按 Markdown 标题分章节,保留标题路径;超长章节再按段落兜底。只有标题、没有正文的片段直接跳过,避免短标题污染相似度。
问题与设计
整篇文章直接 embedding 有两个问题:检索粒度太粗,命中后不知道哪一段相关;长文也可能超过模型输入限制。简单按固定字符数截断又会切开句子、代码块和标题关系。
这里采用两层策略:
- 结构优先:按标题切章节,每块携带
heading_path。 - 长度兜底:章节超过 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 中的一行,以及为什么要先准备完全部向量再替换索引。