RAG 系统链路构建：文档切割与转换全解析

from langchain_text_splitters import TextSplitter
from abc import ABC, abstractmethod
from typing import Callable, List, Union

class TextSplitter(BaseDocumentTransformer, ABC):
    """Interface for splitting text into chunks."""
    def __init__(
        self,
        chunk_size: int = 4000,      # 文本块最大长度（默认字符数，部分子类支持 token 数）
        chunk_overlap: int = 200,    # 相邻块重叠长度（保留上下文）
        length_function: Callable[[str], int] = len,  # 长度计算函数（默认字符数，可改用 token 计数）
        keep_separator: Union[bool, Literal["start", "end"]] = False,  # 是否保留分隔符（如句号、换行）
        add_start_index: bool = False,  # 是否添加文本块在原始文档中的起始索引
        strip_whitespace: bool = True,  # 是否去除文本块前后空格
    ) -> None:
        ...

    @abstractmethod
    def split_text(self, text: str) -> List[str]:
        """基础文本分割方法，子类必须实现"""
        ...

关键方法调用链路：split_documents → create_documents → split_text

TextSplitter 的三个核心方法各有分工，很多新手会混淆，用表格一次性讲清：

调用逻辑小技巧：实际开发中优先用 split_documents()——它会自动继承原始文档的元数据（如 PDF 的页码、网页的 URL），避免后续检索时'找不到信息来源'。

三、核心参数深度解析：调对参数=检索精度翻倍

TextSplitter 的 3 个核心参数（chunk_size、chunk_overlap、separators）直接决定分块质量，新手最容易在这里踩坑，下面结合场景讲透：

1. chunk_size：文本块的'最大长度阈值'

• 定义：每个文本块的最大长度（默认按「字符数」计算，可通过 length_function 改为 token 数）
• 核心作用：控制文本块大小，既要适配模型上下文窗口，又要保证信息密度
• 关键技巧：
  • 不是越小越好：细粒度分块（如 chunk_size=500）能提高检索精准度，但会导致语义断裂（比如把一个完整的合同条款拆成两半）；
  • 不是越大越好：粗粒度分块（如 chunk_size=10000）可能超出模型 token 限制，且包含无关信息，降低检索效率；
  • 参考值：根据目标模型调整——GPT-4（32k）可设 1500-2000，Claude 3（200k）可设 5000-8000，预留部分 token 给后续 prompt。

实战案例：分割产品手册文本

from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_core.documents import Document

# 加载后的产品手册文本（假设已用 PyPDFLoader 加载为 Document 对象）
product_manual_doc = [
    Document(
        page_content="深度学习需要大量数据和计算资源。卷积神经网络（CNN）在图像处理中表现优异，常用于图像分类、目标检测等场景。循环神经网络（RNN）则更适合序列数据，如自然语言处理、时间序列预测。",
        metadata={"source": "产品手册.pdf", "page": 5}
    )
]

# 设置 chunk_size=100（字符数），适配中等上下文窗口模型
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=100,
    chunk_overlap=20,
    strip_whitespace=True
)

# 分割文档（自动继承元数据）
split_docs = text_splitter.split_documents(product_manual_doc)

# 输出结果（2 个文本块，均含元数据）
for doc in split_docs:
    print(f"文本块：{doc.page_content}")
    print(f"元数据：{doc.metadata}\n")

2. chunk_overlap：相邻文本块的'上下文粘合剂'

• 定义：相邻两个文本块之间重叠的字符数（或 token 数）
• 核心作用：避免因分割导致语义断裂，确保上下文连贯性
• 关键技巧：
  • 重叠比例建议为 chunk_size 的 10%-20%（如 chunk_size=1000 时，chunk_overlap=100-200）；
  • 无重叠会导致'信息断层'（比如前块结尾是'卷积神经'，后块开头是'网络（CNN）'，单独看都不完整）；
  • 重叠过多会导致冗余，增加存储和检索成本。

经典案例：长文本序列分割计算 假设 chunk_size=1024，chunk_overlap=128，处理长度为 2560 的文本：

• 文本块 1：第 1-1024 个 token（完整前半段）
• 文本块 2：第 897-1920 个 token（与块 1 重叠 128 个，衔接上下文）
• 文本块 3：第 1793-2560 个 token（与块 2 重叠 128 个，覆盖剩余内容）

3. separators：控制分块的'语义边界优先级'

• 定义：分隔符列表，按优先级顺序递归分割文本（优先用高优先级分隔符，分割后仍超 chunk_size 再用低优先级）
• 核心作用：让分块贴合自然语义（段落→句子→短语），减少'拆碎完整语义'的概率
• 默认分隔符：["\n\n", "\n", " ", ""]（先按段落分割，再按换行，最后按空格）
• 自定义技巧：根据文档类型调整——
  • 中文文本：添加 "。"'；''，'（如 ["\n\n", "。", "；", "，", " "]）；
  • 代码文档：添加 "\n\n", "\n", "{", "}", ";", " "（避免拆碎代码块）；
  • Markdown 文档：保留 "## "'### '（按标题分割，保持章节完整性）。

实战案例：中文法律文本自定义分隔符

from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_core.documents import Document
import re

# 法律合同文本（加载后的 Document 对象）
legal_doc = Document(
    page_content="第一条 合同双方：甲方（供应商）：XX 科技有限公司；乙方（采购方）：XX 制造有限公司。第二条 采购标的：甲方为乙方提供 AI 服务器 10 台，型号为 XX-2024，单价 5 万元/台，总金额 50 万元。第三条 交货时间：乙方支付预付款后 30 个工作日内交货。",
    metadata={"source": "采购合同.pdf", "page": 1}
)

# 自定义中文分隔符（优先按段落→条款→分号→句号分割）
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=150,
    chunk_overlap=20,
    separators=["\n\n", r"第 [一二三四五六七八九十] 条", "；", "。", " "]  # 正则匹配中文条款
)

split_docs = text_splitter.split_documents([legal_doc])
for doc in split_docs:
    print(f"法律文本块：{doc.page_content}\n")