🎯 课程主题

理解文档切分的五大策略，深入剖析 TextSplitter 父类中三个核心方法的源码逻辑及其调用关系。

📝 核心知识点

为什么要对 Document 进行切分

原因说明
Token 限制大模型有上下文长度限制，完整文档可能超过上限导致截断和信息缺失
检索精准度大文档中包含大量无关信息，会干扰大模型输出；小块检索更精准
成本控制不必要的内容会消耗更多 Token，增加 API 调用成本

五大切分策略

策略描述优点缺点
按句子切分以句号为分隔符语义完整粒度可能不均匀
固定字符数切分达到指定字符数就切一刀简单可控可能造成语义断裂
固定字符数 + 重叠窗口在固定切分基础上，前后 chunk 之间有重叠缓解语义断裂会产生冗余内容
递归字符切分 ⭐按优先级依次尝试分隔符（段落 → 换行 → 空格 → 字符），递归切分直到满足 chunk size兼顾语义完整性和长度控制（最常用）实现稍复杂
按语义内容切分基于向量相似度判断语义边界语义最优需要模型参与，成本高、速度慢，chunk 大小不均匀

TextSplitter 父类的三个核心方法

class TextSplitter:
    # 方法一：抽象方法，由子类实现
    def split_text(self, text: str) -> List[str]: ...

    # 方法二：传入字符串列表，内部调用 split_text
    def create_documents(
        self, texts: List[str], metadatas: list = None
    ) -> List[Document]: ...

    # 方法三：传入 Document 列表，提取 page_content 后调用 create_documents
    def split_documents(
        self, documents: List[Document]
    ) -> List[Document]: ...

方法调用链

split_documents (方法三)
    └── 提取每个 Document 的 page_content → 构成 List[str]
            └── create_documents (方法二)
                    └── 遍历每个字符串 → 调用 split_text (方法一)
                            └── 将切分后的字符串封装为 Document 对象

核心参数（在父类中定义，所有子类共享）

参数默认值说明
chunk_size4000每个 chunk 的最大字符数
chunk_overlap200相邻 chunk 的重叠字符数
length_functionlen计算文本长度的函数（默认 Python 内置 len）
separator\n\n分隔符（子类可自定义）

注意：chunk_size 和 chunk_overlap 的单位是字符（characters），不是 Token 或字节。

🏗️ 架构与工作流

方法选择指南

你的输入是什么应调用的方法
一段纯文本 strsplit_text(text)
多个纯文本 List[str]create_documents(texts)
多个 Document List[Document]split_documents(documents)

三个方法本质是层层封装的关系，没有本质区别，根据输入类型选择即可。

💻 代码实战

源码剖析：三个方法的关系

# 方法一：抽象方法（以 RecursiveCharacterTextSplitter 的实现为例）
def split_text(self, text: str) -> List[str]:
    """将单段文本切分为多个字符串"""
    # 具体切分逻辑由子类实现
    ...

# 方法二：将字符串列表切分为 Document 列表
def create_documents(
    self, texts: List[str], metadatas: Optional[List[dict]] = None
) -> List[Document]:
    """底层调用了 split_text"""
    documents = []
    for i, text in enumerate(texts):
        for chunk in self.split_text(text):
            documents.append(Document(
                page_content=chunk,
                metadata=metadatas[i] if metadatas else {}
            ))
    return documents

# 方法三：将 Document 列表进行切分
def split_documents(
    self, documents: List[Document]
) -> List[Document]:
    """底层调用了 create_documents"""
    texts = [doc.page_content for doc in documents]
    metadatas = [doc.metadata for doc in documents]
    return self.create_documents(texts, metadatas)

使用示例

from langchain.text_splitter import CharacterTextSplitter

# 创建 Splitter 实例
splitter = CharacterTextSplitter(
    chunk_size=1000,
    chunk_overlap=200,
    separator="\n"
)

# 场景一：传入纯文本
text = "这是一段很长的文本内容..."
chunks = splitter.split_text(text)  # 返回 List[str]

# 场景二：传入字符串列表
texts = ["第一段文本", "第二段文本"]
docs = splitter.create_documents(texts)  # 返回 List[Document]

# 场景三：传入 Document 列表（最常见，与 Loader 配合）
from langchain_community.document_loaders import TextLoader
loader = TextLoader("./document.txt")
documents = loader.load()
split_docs = splitter.split_documents(documents)  # 返回 List[Document]

⚠️ 常见问题与避坑指南

  1. chunk_size 单位混淆：明确是字符数而非 Token 数。中文 1 个汉字 = 1 个字符，英文 1 个字母 = 1 个字符。
  2. chunk_overlap 单位同样为字符：设置重叠窗口大小时注意与 chunk_size 的比例关系。
  3. 抽象方法不能直接调用：split_text 是抽象方法，必须通过子类实例调用，不能直接实例化 TextSplitter。
  4. 按语义切分的代价：虽然效果最好，但需要模型参与向量化计算，增加时间和费用成本，且 chunk 大小极不均匀。
  5. 递归切分是最佳实践：兼顾了语义完整性和长度控制，是当前最主流的方案。

💡 个人总结与延伸

  • 父类设计模式：TextSplitter 遵循模板方法模式：在父类中定义了 create_documents 和 split_documents 的骨架逻辑，将核心切分算法 split_text 作为抽象方法留给子类实现。这种设计使得所有 Splitter 对外接口完全统一。
  • 方法选择策略：实际开发中最常用的是 split_documents(documents)，因为上游 Loader 产出的就是 List[Document]，可以直接对接。只有在特殊场景（如手动构造测试文本）时才使用前两个方法。
  • 与 Loader 的衔接：BaseLoader 也有 load_and_split(text_splitter) 方法，可以直接在加载环节完成切分。但建议分开操作（先 load 再 split），便于调试中间结果和灵活调整切分参数。
  • 接下来的重点：掌握 CharacterTextSplitter 和 RecursiveCharacterTextSplitter 两个最常用的子类，理解其 separator 和 separators 参数的差异。
最近更新:
Contributors: yangwenguang