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 策略。