LlamaIndex 提供了多种 TextSplitter 来处理不同类型的文本数据，每种都针对特定场景设计，旨在优化检索增强生成（RAG）系统的性能

文本分割（Text Splitting）是构建检索增强生成（RAG）系统的关键步骤，其目标是将大文档划分为语义连贯、大小适宜的文本块（chunk），以便后续的向量化、存储和检索。LlamaIndex 提供了多种文本分割器（TextSplitter），每种都针对不同的文本类型和应用场景设计

 dataconnecters在默认解析时一个文档会保留成一个node节点
# 文本切割太大
    上下文丢失：过大的文本片段可能包含多个主题，使得模型难以理解特定上下文，导致答案不精准
    计算资源消耗：处理大文本块需要更多的计算资源，可能导致效率低下，响应时间延长
    信息冗余：大文本可能包含不必要的信息，使模型的注意力分散，从而影响关键信息的提取
# 文本切割太小
    上下文不足：过小的文本片段可能缺乏必要的上下文，导致模型误解文本的意思
    频繁拆分：切割过于细碎会导致模型在理解多段信息时出现困难，尤其是在推理和整合信息时
    模型性能下降：太小的切割可能使得训练时数据样本稀疏，影响模型的学习效果和泛化能力

一、文本分割的 “底层逻辑”：为什么选对分割器这么重要？

在 RAG 流程中，文本分割直接影响两个核心环节：

1. 向量化质量：如果 chunk 语义破碎（比如一句话被切两半），Embedding 模型无法捕捉完整含义，检索时会出现 “答非所问”；
2. 检索精度：chunk 太大（比如整篇文档一个 chunk），会包含大量无关信息（噪音）；chunk 太小（比如 10 个字一个 chunk），会丢失上下文关联，导致 “断章取义”。

好的分割器要实现 “平衡”：语义完整 + 长度适配模型限制。

二、LlamaIndex 主流 TextSplitter 深度解

1. SentenceSplitter（语义优先，通用首选）

• 核心原理：基于 “语义边界” 分割（中文靠。！？、，英文靠 . ? ! ），优先保证句子 / 短句完整，再按 chunk_size 限制长度。
• 关键参数（中文场景重点关注）：

  from llama_index.core.node_parser import SentenceSplitter
  
  # 中文文本最优配置（适配大多数 Embedding 模型）
  sentence_splitter = SentenceSplitter(
      chunk_size=300,          # 每个 chunk 最大字符数（中文300字≈英文100词，适配多数模型）
      chunk_overlap=50,        # 相邻 chunk 重叠字符数（1/6~1/3 chunk_size，避免语义割裂）
      separator="\n\n",        # 优先分割符：先按段落（空行）分割，再按句子
      paragraph_separator="\n\n",  # 段落界定符
  )
  

• 适用场景：✅ 通用文本（PDF、Word、新闻、报告）；✅ 中文 / 中英文混合文本（语义分割对中文更友好）；✅ 新手入门、快速搭建 RAG 原型。
• 实战效果：原始文本："人工智能的核心是机器学习，而机器学习的基础是数据。近年来，大模型的爆发让 AI 应用场景大幅扩展，从医疗诊断到智能驾驶，都能看到 AI 的身影。"分割后（chunk_size=50，chunk_overlap=10）：
  • Chunk1："人工智能的核心是机器学习，而机器学习的基础是数据。近年来，大模型的爆发让 AI 应用场景大幅扩展，"
  • Chunk2："大模型的爆发让 AI 应用场景大幅扩展，从医疗诊断到智能驾驶，都能看到 AI 的身影。"

2. TokenTextSplitter（长度精准，适配模型）

• 核心原理：基于 “Token 数” 分割（而非字符数），严格匹配大模型 / Embedding 模型的 Token 限制（比如 OpenAI 模型单段最大 8191 Token），分割时会在空格 / 标点处 “软截断”，尽量保留语义。
• 关键参数（英文 / 长文档重点关注）：

  from llama_index.core.node_parser import TokenTextSplitter
  
  # 适配 GPT-4o/OpenAI Embedding 模型的配置
  token_splitter = TokenTextSplitter(
      chunk_size=1024,         # 每个 chunk 最大 Token 数（匹配模型上下文窗口）
      chunk_overlap=128,       # 重叠 Token 数（1/8 chunk_size，保证连贯性）
      tokenizer=None,          # 默认用 tiktoken（OpenAI 官方 Token 计算工具），可自定义
      encoding_name="cl100k_base"  # Token 编码方式（适配 GPT-3.5/4 系列）
  )
  

• 适用场景：✅ 英文长文档（Token 计算更精准，中文 Token ≈ 字符数）；✅ 需严格控制 Token 长度的场景（比如 Embedding 模型限制 2048 Token）；✅ 大模型上下文窗口较小的场景（比如 2k Token 模型）。
• 注意点：中文场景下，chunk_size=1024 约等于 1024 个中文字符（tiktoken 对中文按字编码），可直接按 “字符数≈Token 数” 估算。

3. CodeSplitter（语法优先，代码专属）

• 核心原理：基于编程语言语法分割，识别函数、类、代码块、注释等结构，优先在语法边界（如 def/class/}）分割，避免破坏代码逻辑。
• 关键参数（代码文档重点关注）：

  from llama_index.core.node_parser import CodeSplitter
  
  # Python 代码分割配置
  code_splitter = CodeSplitter(
      language="python",       # 支持 python/java/js/cpp 等主流语言
      chunk_lines=50,          # 每个 chunk 最大行数（代码按行分割更直观）
      chunk_lines_overlap=5,   # 重叠行数（避免函数/类被截断）
      max_chars=1500,          # 兜底限制：单个 chunk 最大字符数（防止超长代码块）
      comment_prefix="#",      # 注释前缀（保留注释上下文）
  )
  

• 适用场景：✅ 代码文件（.py/.java/.js/.cpp）；✅ 技术文档（含大量代码片段，如 API 文档、教程）；✅ 代码问答 RAG 系统（比如 “如何用 Python 实现文本分割”）。
• 实战效果：原始 Python 代码：

  def add(a, b):
      return a + b
  
  class Calculator:
      def __init__(self):
          self.result = 0
  
      def multiply(self, x, y):
          self.result = x * y
          return self.result
  

  分割后（chunk_lines=10）：
  • Chunk1：包含 add 函数 + Calculator 类定义前 3 行；
  • Chunk2：包含 Calculator 类的 multiply 方法（重叠类定义部分，保证语法完整）。

4. 特殊场景分割器

三、分割器选择指南（按场景快速匹配）

四、参数调优技巧（避免踩坑）

1. chunk_size 怎么定？

   • 参考 Embedding 模型的最大输入长度：比如 OpenAI text-embedding-3-small 最大支持 8191 Token，可设 chunk_size=1024-2048（留有余地）；
   • 中文场景：优先按 “字符数” 设置（SentenceSplitter），300-500 字符是 “语义完整 + 检索精准” 的黄金区间。

2. chunk_overlap 怎么设？

   • 原则：overlap = chunk_size × (1/6 ~ 1/3)；
   • 短文本（chunk_size<300）：overlap=50-80（避免语义割裂）；
   • 长文本（chunk_size>1024）：overlap=128-256（减少冗余）。

3. 中文场景特殊注意：

   • 避免用 “纯字符截断” 的分割器（如简单的字符串切片），优先选 SentenceSplitter（按标点分割）；
   • 若文本无标点（如日志），可自定义 separator 为 “换行符” 或特定分隔符。

五例子

from llama_index.core import SimpleDirectoryReader

reader = SimpleDirectoryReader(
    input_dir="./data", # 目标目录
    recursive=False, # 是否递归遍历子目录
    required_exts=[".pdf"] # (可选)只读取指定后缀的文件
)
documents = reader.load_data()
from llama_index.core.node_parser import TokenTextSplitter

node_parser = TokenTextSplitter(
    chunk_size=100,  # 每个 chunk 的最大长度
    chunk_overlap=50  # chunk 之间重叠长度
)

nodes = node_parser.get_nodes_from_documents(
    documents, show_progress=False
)
print(f"共生成 {len(nodes)} 个节点")
for index, value in enumerate(nodes, start=1):  # 从1开始计数
    print(f"索引: {index}, 值: { value.get_content()}")
#https://developers.llamaindex.ai/python/framework-api-reference/llms/
#nodeparser