跳转到主要内容

LangChain

10 · 文本切分

chunk_size 与 chunk_overlap 怎么设

  • LangChain
  • Python

本节速览

这一节的每一块内容,分别是干什么的:

内容是干什么的
RecursiveCharacterTextSplitter按分隔符层级递归切,通用首选
from_language按编程语言语法切代码,保留完整函数
TokenTextSplitter按 token 数切,精确控制块长度
调参建议chunk_size 与 chunk_overlap 怎么设

切分解决两个问题:LLM 上下文窗口放不下完整数据;即使放得下,塞入过多无关内容也会稀释注意力、增加 token 成本。目标是把长文档切成内部语义相关、彼此相对独立的小块。

切分质量直接决定检索质量,进而决定 RAG 回答质量。切分器位于 langchain-text-splitters 包(pip install langchain-text-splitters)。

工作模型:切、装、重叠

所有切分器遵循三步:

  1. 切:按分隔逻辑把原文切成语义单元(一般到句子级)。
  2. 装:把语义单元组装进块,直到达到 chunk_size 上限。
  3. 重叠:组装下一块时,按 chunk_overlap 从上一块尾部复制一段作为新块开头。

重叠存在的原因:任何切分点都可能切断语义。重叠用少量冗余换取上下文完整性。第一块是 AABBCC、chunk_overlap 为 2 时,第二块就是 CCDDEE。

RecursiveCharacterTextSplitter:通用首选

没有它会怎样——不切:文档超上下文直接报错,没超也按整篇计费,检索粒度粗到等于全文检索。按固定字符数硬切:句子、表格、定义被拦腰斩断,检索命中半句话,答案缺胳膊少腿。

有了它——按「段落→句子→字符」的层级递归切,块边界尽量落在自然分隔处,每块语义完整。

默认分隔符列表 ["\n\n", "\n", " ", ""]:先按段落切,段落内按句子、词逐级往下切,再把片段组装回 chunk_size 以内。这种「先粗后细」的递归保持相关文本相邻,是所有切分任务的首选起点。

import warnings   # 过滤 langchain-community 的 sunset 弃用警告(见 09 章版本说明)

warnings.filterwarnings("ignore", message="`langchain-community` is being sunset*")

from langchain_community.document_loaders import TextLoader   # 加载 txt 文件
from langchain_text_splitters import RecursiveCharacterTextSplitter   # 递归文本切分器

docs = TextLoader("data/qiu.txt").load()   # 09 章那份《秋园小记》,425 字

splitter = RecursiveCharacterTextSplitter(
    chunk_size=64,       # 教学演示值,实际按下面建议设置
    chunk_overlap=16,
)

split_docs = splitter.split_documents(docs)   # 继承原 Document 的 metadata

print(len(split_docs))                          # 切成 10 块
# 10

print([len(d.page_content) for d in split_docs[:3]])   # 前 3 块的字数
# [63, 63, 25]

print(split_docs[0].page_content)
# 《秋园小记》

# 秋天的后园里,墙角有一棵老槐树。风一起,叶子就簌簌地落,铺了满地碎金。清晨的露水还没散,踩上去有点凉,有点软。

print(split_docs[0].metadata)                   # metadata 原样带过来
# {'source': 'data/qiu.txt'}

chunk_size=64 却切出 63 字的块,不是 bug:切点落在段落分隔符 \n\n 上,分隔符本身不计入块内。块大小是上限而非目标值,实际长度取决于自然分隔点在哪。

两个核心参数的取舍:

参数过大过小
chunk_size一块多个主题,检索引入噪音,token 成本高装不下完整语义,信息被截断
chunk_overlap重复提取相同信息关键信息可能被切在两块边界

调参建议

没有它会怎样——chunk 太大:一块塞好几个主题,命中了也淹没在无关内容里;太小:一块只有半句,答案拼不起来;overlap 为 0:边界处的信息两块都只有一半。

有了它——size 按「一个完整语义单元」定,overlap 留一句缓冲,召回质量立得住。

没有理论最优值,实用流程:

  1. 从 1.x 默认值 4000 / 200 起步(0.x 旧教程写的 1000 / 200 已过时);
  2. 用 ChunkViz 可视化检查:打开网页,把文本贴进左侧输入框,填入 chunk_size 与 chunk_overlap,右侧按块上色显示,切分边界落在哪里一目了然;
  3. 跑通完整 RAG 链路后,根据回答质量和过程日志回调参数或换切分器。

链路跑通前投入大量时间精调这两个参数,性价比很低。切分结果会继承原 Document 的 metadata;构造时传 add_start_index=True 还会记录每块在原文中的起始位置,便于回溯:

import warnings   # 过滤 langchain-community 的 sunset 弃用警告(见 09 章版本说明)

warnings.filterwarnings("ignore", message="`langchain-community` is being sunset*")

from langchain_community.document_loaders import TextLoader   # 加载 txt 文件
from langchain_text_splitters import RecursiveCharacterTextSplitter   # 递归文本切分器

docs = TextLoader("data/qiu.txt").load()

splitter = RecursiveCharacterTextSplitter(
    chunk_size=64,
    chunk_overlap=16,
    add_start_index=True,   # 在 metadata 里记下每块的起始位置
)

split_docs = splitter.split_documents(docs)

print(split_docs[0].metadata)
# {'source': 'data/qiu.txt', 'start_index': 0}

print([d.metadata["start_index"] for d in split_docs[:5]])   # 前 5 块的起始位置
# [0, 65, 112, 139, 186]

不传 add_start_index 时 metadata 只有 {'source': 'data/qiu.txt'}。有了起始位置,检索命中某块后可以直接回原文定位上下文,不必再猜它属于哪一段。

同一份文本用两组参数各切一遍,直观感受差别:

from pathlib import Path   # 读文件

from langchain_text_splitters import RecursiveCharacterTextSplitter   # 递归文本切分器

# 同一份语料:《秋园小记》全文去掉换行,便于观察重叠效果
text = Path("data/qiu.txt").read_text(encoding="utf-8").replace("\n", "")

print(len(text))
# 412

small = RecursiveCharacterTextSplitter(chunk_size=50, chunk_overlap=10)
big = RecursiveCharacterTextSplitter(chunk_size=200, chunk_overlap=50)

# 小参数:11 块,单块信息少,检索定位准,但上下文容易断
print("小参数块大小:", [len(c.page_content) for c in small.create_documents([text])])
# 小参数块大小: [50, 50, 50, 50, 50, 50, 50, 50, 50, 50, 12]

# 大参数:3 块,单块上下文完整,但容易混入无关内容
print("大参数块大小:", [len(c.page_content) for c in big.create_documents([text])])
# 大参数块大小: [200, 200, 112]

调参调的就是这个平衡:块小召回准但答案缺上下文,块大上下文全但检索噪音多。先跑通链路,再按回答质量偏向哪边调。

重叠是否真的生效,可以直接验证——下一块的开头应当等于上一块的结尾:

# 接上一块:small(小参数切分器)与 text(去换行的语料)都来自上面的调参示例
small_chunks = [c.page_content for c in small.create_documents([text])]

print(repr(small_chunks[0][-10:]))    # 第 1 块的末尾 10 字
# '。清晨的露水还没散,'

print(repr(small_chunks[1][:10]))     # 第 2 块的开头 10 字
# '。清晨的露水还没散,'

print(small_chunks[1].startswith(small_chunks[0][-10:]))   # 完全一致
# True

一个容易踩的边界条件:重叠发生在「装块」阶段,只在同一段落内部生效。如果切点正好落在 \n\n 段落分隔符上,下一块从新段落开头,不会复制上一段的尾巴。上面这份文本是先 .replace("\n", "") 去掉了段落分隔才处处可见重叠;09 章 qiu.txt 原文直接切时,段落边界处的两块就没有重叠。语料本身段落分明时,这一点要心里有数。

代码切分:from_language

没有它会怎样——通用切分器切代码,函数从第 5 行劈开:检索命中半个函数,模型看不到函数名和参数,答非所问。

有了它——按语言语法切,函数、类保持完整,命中即完整上下文。

按编程语言语法切,本质是把该语言的特征分隔符(函数边界、语句结尾)作为分隔符列表。from_language 生成的 PYTHON 分隔符按优先级排列如下——\nclass 、\ndef 排在 \n\n、\n 之前,所以会优先在函数/类边界切开:

['\nclass ', '\ndef ', '\n\tdef ', '\n\n', '\n', ' ', '']
from langchain_text_splitters import Language, RecursiveCharacterTextSplitter   # 切分器与语言枚举

code = (
    "def add(a, b):\n"
    "    total = a + b\n"
    "    return total\n"
    "def sub(a, b):\n"          # 注意:函数之间是单换行,没有空行
    "    diff = a - b\n"
    "    return diff\n"
)

splitter = RecursiveCharacterTextSplitter.from_language(
    Language.PYTHON,    # 也接受字符串 "python"
    chunk_size=40,
    chunk_overlap=0,
)

code_docs = splitter.create_documents([code])

print(len(code_docs))
# 4

for d in code_docs:
    print(repr(d.page_content))
# 'def add(a, b):\n    total = a + b'
# 'return total'
# 'def sub(a, b):\n    diff = a - b'
# 'return diff'

同样参数换成通用切分器,差别立刻显现——它不认识 \ndef ,任意换行都能当切点(接上一块:复用上面的 code,并把 RecursiveCharacterTextSplitter 一起导入):

from langchain_text_splitters import RecursiveCharacterTextSplitter   # 递归文本切分器

# 接上一块:复用上面的 code(那段 def add / class Calc 示例代码)
generic = RecursiveCharacterTextSplitter(chunk_size=40, chunk_overlap=0)

for d in generic.create_documents([code]):
    print(repr(d.page_content))
# 'def add(a, b):\n    total = a + b'
# 'return total\ndef sub(a, b):'      ← 上一个函数的尾巴粘住了下一个函数的头
# 'diff = a - b\n    return diff'

中间那块 'return total\ndef sub(a, b):' 就是「没有它会怎样」的实物证据:检索命中这一块,模型看到的是残缺的 sub——没有参数列表、没有函数体。语言感知切分则保证每块都从一个函数边界开始。

两个注意点:

  • from_language 默认 chunk_overlap=200。只传 chunk_size 而它小于 200 时会直接报错 ValueError: Got a larger chunk overlap (200) than chunk size——上面显式写了 chunk_overlap=0 就是这个原因。
  • Language 枚举覆盖 cpp、go、java、js、python、markdown、html 等。Python 版 create_documents 不会给 metadata 生成行号(上面 metadata 是 {}),需要行号要自行实现。

Token 切分:TokenTextSplitter

没有它会怎样——按字符数切,中英混排时字符数和 token 数对不上:设 800 字符,实际 token 超了,模型侧照样报超限。

有了它——直接按 token 预算切,块多大、花多少钱,可控。

纯按 token 数量切,不照顾标点和语义。适用场景:对 token 数量精确敏感(如按预算组装上下文),或与其他切分器组合:

from langchain_text_splitters import TokenTextSplitter   # 按 token 切分

splitter = TokenTextSplitter(chunk_size=10, chunk_overlap=0)
text = "孔乙己是站着喝酒而穿长衫的唯一的人。他身材很高大;青白脸色,皱纹间时常夹些伤痕。"

docs = splitter.create_documents([text])

print(len(docs))
# 9

# U+FFFD 是「替换符」——残缺字节解码失败时填进去的占位字符
BROKEN = "\ufffd"

print(sum(BROKEN in d.page_content for d in docs))   # 9 块里有几块被切坏了
# 7

默认用 tiktoken 的 gpt2 编码计 token,需 pip install tiktoken。

这 7 块里是肉眼可见的乱码,不是显示问题。 gpt2 是字节级 BPE:英文一个词往往是 1 个 token,而一个汉字会被拆成 2~3 个 token(孔乙己 3 个字实测 6 个 token)。按 token 边界切,就会从汉字中间劈开,解回字符串时残缺的字节被填成替换符 U+FFFD,在终端里显示成一个方框或问号。

直接 print(docs[0].page_content) 会看到 孔乙己是站 后面跟着一个乱码方框——因为 U+FFFD 是可打印字符,repr() 也不会把它转义成 \ufffd,所以别指望在输出里认出这个转义串。判断是否切坏,用上面 "\ufffd" in ... 这种检测,不要靠肉眼看。同一句英文用相同参数切实测零乱码——问题只出在多字节字符上。

换编码也躲不掉。实测 encoding_name='cl100k_base':

chunk_size块数含乱码的块
1076
2044
5020

规律是 chunk_size 越大越不容易切坏字符,但小值下必然出现。中文语料的实用做法:

  • 按 token 预算切中文,用 RecursiveCharacterTextSplitter——它按字符切,永远落在字符边界上。同样 chunk_size=10,实测 4 块、零乱码('孔乙己是站着喝酒而穿'、'长衫的唯一的人。他身'……)。
  • 必须用 TokenTextSplitter 时,把 chunk_size 放大到远大于单字符的 token 数(中文取几十以上),或切成后做 \ufffd 检查。

选型

切分器场景
RecursiveCharacterTextSplitter通用文本,默认选择
from_language(Language.X)代码、Markdown、HTML 等结构化文本
TokenTextSplittertoken 预算精确敏感
CharacterTextSplitter按用户指定的单一字符切

上一节:文档加载器 · 下一节:Embedding 与向量存储