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)。
工作模型:切、装、重叠
所有切分器遵循三步:
- 切:按分隔逻辑把原文切成语义单元(一般到句子级)。
- 装:把语义单元组装进块,直到达到
chunk_size上限。 - 重叠:组装下一块时,按
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.x 默认值 4000 / 200 起步(0.x 旧教程写的 1000 / 200 已过时);
- 用 ChunkViz 可视化检查:打开网页,把文本贴进左侧输入框,填入 chunk_size 与 chunk_overlap,右侧按块上色显示,切分边界落在哪里一目了然;
- 跑通完整 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 | 块数 | 含乱码的块 |
|---|---|---|
| 10 | 7 | 6 |
| 20 | 4 | 4 |
| 50 | 2 | 0 |
规律是 chunk_size 越大越不容易切坏字符,但小值下必然出现。中文语料的实用做法:
- 按 token 预算切中文,用
RecursiveCharacterTextSplitter——它按字符切,永远落在字符边界上。同样chunk_size=10,实测 4 块、零乱码('孔乙己是站着喝酒而穿'、'长衫的唯一的人。他身'……)。 - 必须用
TokenTextSplitter时,把chunk_size放大到远大于单字符的 token 数(中文取几十以上),或切成后做\ufffd检查。
选型
| 切分器 | 场景 |
|---|---|
RecursiveCharacterTextSplitter | 通用文本,默认选择 |
from_language(Language.X) | 代码、Markdown、HTML 等结构化文本 |
TokenTextSplitter | token 预算精确敏感 |
CharacterTextSplitter | 按用户指定的单一字符切 |
上一节:文档加载器 · 下一节:Embedding 与向量存储