---
type: study
status: verified
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
tags:
  - study
  - langchain
  - python
  - integrations
  - text-splitter
  - rag
topic: LangChain Python 文本切分结构边界与召回质量
sources:
  - https://docs.langchain.com/oss/python/integrations/splitters
  - https://docs.langchain.com/oss/python/integrations/splitters/character_text_splitter
  - https://docs.langchain.com/oss/python/integrations/splitters/code_splitter
  - https://docs.langchain.com/oss/python/integrations/splitters/index
  - https://docs.langchain.com/oss/python/integrations/splitters/markdown_header_metadata_splitter
  - https://docs.langchain.com/oss/python/integrations/splitters/recursive_json_splitter
  - https://docs.langchain.com/oss/python/integrations/splitters/recursive_text_splitter
  - https://docs.langchain.com/oss/python/integrations/splitters/split_by_token
  - https://docs.langchain.com/oss/python/integrations/splitters/split_html
last_verified: 2026-08-11
---
# Text Splitters：结构边界与召回质量

## 默认选择

文本切分解决两件事：让 chunk 可进入模型上下文，并让每个 chunk 可独立召回。官方对通用文本的默认建议是 `RecursiveCharacterTextSplitter`；只有明确的文档结构、token 硬限制或语言边界需求时再换策略。`/splitters` 与 `/splitters/index` 当前同正文，统一包为 `langchain-text-splitters`。

## 9 个路由

| 路由 | 类/策略 | 已验证边界 |
|---|---|---|
| `splitters`、`index` | 总览 | text structure、length、document structure 三类；推荐递归字符切分。 |
| `character_text_splitter` | `CharacterTextSplitter` | 按一个 separator 分割、按字符计长；`split_text` 返回字符串，`create_documents` 保留输入 metadata。 |
| `code_splitter` | `RecursiveCharacterTextSplitter.from_language(Language.*)` | 为 Python/JS/TS/Markdown/LaTeX/HTML/Solidity/C#/Haskell/PHP/PowerShell/VB 等提供 separator 列表；不是完整 AST parser。 |
| `markdown_header_metadata_splitter` | `MarkdownHeaderTextSplitter` | 按 header 分组并写 header metadata；默认移除 header、空白和换行，可用 `strip_headers=False` 或实验 splitter 保留格式。 |
| `recursive_json_splitter` | `RecursiveJsonSplitter` | 深度优先尽量保持对象完整；默认不拆 list，可先转 dict；超长字符串不会拆，因此 `max_chunk_size` 不是硬上限。 |
| `recursive_text_splitter` | `RecursiveCharacterTextSplitter` | 默认依次尝试 `\n\n`、`\n`、空格、空字符串；可为无词边界语言加入句号、逗号、零宽空格等 separators。 |
| `split_by_token` | tiktoken、`TokenTextSplitter`、spaCy、SentenceTransformers、NLTK、KoNLPy、HF tokenizer | 应使用与目标模型相同 tokenizer；token 数才是模型硬约束。 |
| `split_html` | `HTMLHeaderTextSplitter` | 按 heading 组织并保存 header metadata。 |
| `split_html` | `HTMLSectionSplitter` / `HTMLSemanticPreservingSplitter` | section splitter 处理结构；semantic-preserving 保持 table/list/custom element，但回填保留元素后可能超过 `max_chunk_size`。 |

## 容易误判的边界

- Markdown 的 `chunk_overlap` 只会在某个 header section 本身超过 `chunk_size`、又被第二阶段拆分时出现。应对 header 输出调用 `split_documents(docs)`，才能同时保留 metadata 和 section 内 overlap。
- `RecursiveJsonSplitter` 的 list 和大字符串可能产生超限 chunk；需要 token 硬上限时，再接递归文本/token splitter，并保留 JSON path metadata。
- 直接 `TokenTextSplitter` 可能把中文、日文等多 token 字符切坏，产生非法 Unicode；使用 `RecursiveCharacterTextSplitter.from_tiktoken_encoder` 或字符 splitter 的 encoder 工厂保证字符串边界。
- HTML semantic preservation 优先“不拆表格/列表”，所以 `max_chunk_size` 是目标值而非硬保证；入模前仍需最终 token gate。
- 代码 separator 只是启发式结构，不保证函数、字符串、注释或语法树节点绝对完整；高准确代码检索应使用 parser/AST 加语言级测试。

## 生产策略

切分是确定性 CPU 转换，当前页面未提供原生 async 或流式网络契约；可在摄取 worker 并行，但需限制内存并保持输入顺序/稳定 ID。版本化保存 splitter 类、所有参数、tokenizer/model、separator、parser version 和 chunk ID 算法。

不要只用平均 chunk 长度调参。评测至少覆盖：chunk token P50/P95/max、超限率、空 chunk、重复率、父子/邻接关系、metadata 保留率、recall@k、answer citation coverage 和总成本。结构化文档要单测 header/table/list/page locator；中日韩、emoji、组合字符和超长无空格文本是必要边界样本。

## 验证边界

已逐页核对 9 个官方 Markdown 路由和所有明确限制；没有用业务语料跑 retrieval evaluation，因此推荐参数只能作为起点，不能视为当前项目的最优 chunk 策略。