Embedding按语义边界切分长文档的实现方法

长文档做向量检索时，最容易出问题的不是 Embedding 接口，而是分块边界。把全文每 500 个字符硬切，会把标题和解释拆开，也可能让代码块只剩半段。更稳妥的做法是先按标题、段落、列表和代码块建立结构，再在同一章节内按 token 预算合并；每个块带上父标题与序号，召回后才有机会补回邻近上下文。

官方参考地址：https://platform.openai.com/docs/guides/embeddings。下面只讨论分块、索引和召回上下文，不展开向量数据库选型。

先按文档结构确定语义边界

先把 Markdown 或富文本还原成“章节—段落—块”的层级。标题是主题边界，段落是最小叙述单元，列表和代码块通常要整体保留。短段落可以合并，跨越新标题时则应该结束当前候选块。这样做的目标不是让每个块长度完全相同，而是让一个块能够独立说明一个小问题。

下面的示例用段落列表演示合并逻辑。真实项目可把 Markdown 解析器输出的节点直接接入；示例中的字符数只是预估，正式服务应使用与 Embedding 模型一致的 tokenizer 计算 token。

from dataclasses import dataclass

@dataclass
class Chunk:
    text: str
    heading: str
    index: int

def build_chunks(paragraphs, heading, limit=1200):
    chunks = []
    current = []
    current_size = 0

    for paragraph in paragraphs:
        size = len(paragraph)
        # 中文注释：新段落放不下时先结束当前语义块，避免跨标题硬拼文本。
        if current and current_size + size > limit:
            chunks.append(Chunk("\n".join(current), heading, len(chunks)))
            current = []
            current_size = 0
        current.append(paragraph)
        current_size += size

    if current:
        # 中文注释：最后一个未满的块也要落盘，不能因没有下一个段落而丢失。
        chunks.append(Chunk("\n".join(current), heading, len(chunks)))
    return chunks

生产代码还应在解析阶段给代码块和列表打上不可拆分标记。一个超长代码块不能无限塞进向量请求；可以保留代码块标题与语言标识，再按完整函数、类方法或自然段拆开，并在元数据中记录 parent_block。这比把代码从中间截断后让模型猜上下文更可靠。

用 token 预算和有限重叠控制块大小

块太小会丢主题，块太大则召回后上下文嘈杂。可以先设一个目标区间，例如 400～800 token，再为极短段落做合并；不要把某个数字当作所有模型、语言和业务的固定答案。官方 Embeddings 文档给出了模型的最大输入边界，应用仍应在请求前统计 token，并为标题、元数据和查询留出空间。

重叠不是越大越好。它适合连接“定义—例子”或“条件—结论”这种跨段关系，但应限制在同一父标题内；若每个块都复制大段前文，索引会出现大量近重复向量。跨章节时宁愿保留标题元数据，也不要把两个主题强行拼成一个块。

用 Embedding 建索引并在召回时补上下文

分块完成后，批量把每个块发送到 Embedding 接口，保存返回向量和原文的同一索引。Embedding 表示文本相关性，不会替你保存标题层级，也不会自动修复错误切分。查询时先用查询向量取候选块，再按候选块的 doc_id、heading 和 chunk_index 补一小段邻近内容。

from openai import OpenAI

client = OpenAI()

def embed_chunks(chunks):
    texts = [chunk.text.replace("\n", " ") for chunk in chunks]
    # 中文注释：批量请求只传正文，标题和序号作为独立元数据保存。
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts,
    )
    return [
        {"text": chunk.text, "heading": chunk.heading,
         "chunk_index": chunk.index, "vector": item.embedding}
        for chunk, item in zip(chunks, response.data)
    ]

召回阶段建议设置两道边界：第一道是相似度或数量阈值，避免把低相关块全部塞入上下文；第二道是邻居范围，例如只补同一章节前后各一个块。若问题需要跨章节答案，可先按标题过滤，再扩大范围。测试时至少记录“命中块是否包含结论”“补邻居后答案是否完整”“重复块比例”三项，而不是只看向量分数。

常见问题

固定 500 个字符切分为什么不稳定？

字符数没有语义含义，可能把标题、列表、代码和结论拆开。它可以作为兜底上限，但不应作为唯一边界。

重叠窗口应该设置多大？

从能覆盖一两个关键句开始，并限制在同一章节。实际值要结合语言、段落长度和召回重复率调整，不能照抄别人的参数。

标题需要拼进向量文本吗？

通常应把父标题拼到待嵌入文本的前缀，同时单独保存标题字段。这样既能帮助语义表示，又能支持按章节过滤和结果展示。

切分效果怎么判断？

准备一组真实问题，比较固定切分、语义切分和补邻居后的答案完整度；重点看边界导致的漏召回，而不是只比较向量数量。