LangChain Splitter 全解析：那么多分割策略，其实你只需要一个

问题出在哪？出在你用了一刀切的分割策略。

文本分割这件事，看起来就是"按字数切一刀"，但背后藏着一个残酷的事实：切错了，后面整条 RAG 链路全废。Embedding 再好、向量数据库再快、Prompt 写得再漂亮，喂进去的 chunk 本身就是碎片化的垃圾，你能指望 LLM 给你什么好答案？

今天这篇，我带你把 LangChain.js 里所有主流 Splitter 掰开揉碎，搞清楚每一种适合什么场景，以及为什么 90% 的情况下你只需要一个。

01 文本分割的本质：为什么"切"比"搜"更重要

文本分割的核心目标不是"把文本变短"，而是"让每个 chunk 携带完整的语义单元"。

我们先建立一个直觉。假设你有一篇 5000 字的技术文档，要塞进 RAG 系统。LLM 的 context window 有限，你不可能整篇丢进去，所以必须切成小块。问题是：怎么切？

最朴素的做法：每 500 个字符切一刀。

原文：[============================5000字============================] 朴素切割：[==500==][==500==][==500==][==500==][==500==]... 问题：第3块的前半段是"函数A的返回值说明"，后半段是"函数B的参数列表" → 这个 chunk 的语义是混乱的 → embedding 向量会变成两个主题的"平均值" → 检索时两个问题都能匹配到它，但两个问题它都答不好

更聪明的做法：按文档的自然结构来切——段落、标题、代码块、列表项，这些天然就是语义边界。

理想切割： ┌─────────────────────────────┐ │ ## 函数A │ │ 参数说明... │ ← chunk 1：完整的函数A文档 │ 返回值说明... │ └─────────────────────────────┘ ┌─────────────────────────────┐ │ ## 函数B │ │ 参数说明... │ ← chunk 2：完整的函数B文档 │ 返回值说明... │ └─────────────────────────────┘

这就是为什么 LangChain 提供了那么多 Splitter——不同类型的文档，"自然结构"长得不一样，需要不同的分割策略来识别。

02 RecursiveCharacterTextSplitter：为什么它是你的默认首选

如果你只记住一个 Splitter，就记 RecursiveCharacterTextSplitter。它覆盖 90% 的场景。

它的核心思想是递归分割：不是简单地每隔 N 个字符切一刀，而是按照一个分隔符优先级列表来尝试切割。对于普通文本，默认的分隔符列表是：

["\n\n", "\n", " ", ""]

翻译成人话就是：

1. 先试着按双换行（段落）切——如果每个段落都在 chunkSize 以内，完美
2. 段落太长？退而求其次，按单换行切
3. 还是太长？按空格（单词边界）切
4. 最后实在没办法，按单个字符硬切

这种"先大后小"的递归策略，能最大程度保持文本的语义完整性。

importRecursiveCharacterTextSplitterfrom"langchain/text_splitter"constnewRecursiveCharacterTextSplitterchunkSize1000chunkOverlap200separators"\n\n""\n"" """// 默认值，可自定义const`# LangChain 简介LangChain 是一个用于构建 LLM 应用的框架。它提供了一系列工具和抽象，帮助开发者快速构建基于大语言模型的应用程序。## 核心概念LangChain 的核心概念包括 Chain、Agent、Tool 等。每个概念都有明确的职责划分。Chain 是最基础的抽象，它将多个步骤串联起来，形成一个完整的处理流程。## 安装方式使用 npm 安装：npm install langchain使用 yarn 安装：yarn add langchain`constawaitcreateDocumentsforEach(chunk, i) =>consolelog`--- Chunk ${i} (${chunk.pageContent.length} chars) ---`consolelogpageContentconsolelog

输出你会看到，它会优先在## 核心概念和## 安装方式这些双换行处切开，而不是在句子中间生硬截断。

✅ 正确用法：设置合理的 chunkOverlap

// ✅ overlap 通常设为 chunkSize 的 10%-20%constnewRecursiveCharacterTextSplitterchunkSize1000chunkOverlap200// 200 / 1000 = 20%，合理

❌ 错误用法：overlap 为 0 或过大

// ❌ overlap 为 0，相邻 chunk 之间的上下文完全丢失constnewRecursiveCharacterTextSplitterchunkSize1000chunkOverlap0// 边界处的信息被截断// ❌ overlap 过大，chunk 之间大量重复，浪费 token 和存储constnewRecursiveCharacterTextSplitterchunkSize1000chunkOverlap800// 80% 重叠？太离谱了

03 MarkdownHeaderTextSplitter：按标题层级精准切割

处理 Markdown 文档时，MarkdownHeaderTextSplitter 能按标题层级把文档拆成带有结构化 metadata 的 chunk。

这个 Splitter 的独特之处在于：它不只是切文本，还会把每个 chunk 所属的标题层级信息写进 metadata。这在 RAG 中极其有用——你不光知道这个 chunk 说了什么，还知道它在文档中的"位置"。

importMarkdownHeaderTextSplitterfrom"langchain/text_splitter"const`# 用户指南欢迎使用我们的产品。## 快速开始### 安装运行以下命令安装：\`\`\`bashnpm install our-product\`\`\`### 配置在项目根目录创建配置文件 config.json。配置文件需要包含 apiKey 和 endpoint 两个字段。## 高级功能### 自定义插件你可以通过插件系统扩展功能。插件需要实现 Plugin 接口。### 性能优化开启缓存可以显著提升性能。建议在生产环境中使用 Redis 作为缓存后端。`constheadersToSplitOnstringstring"#""h1""##""h2""###""h3"constnewMarkdownHeaderTextSplitterconstawaitsplitTextforEach(chunk, i) =>consolelog`--- Chunk ${i} ---`consolelog"Content:"pageContentconsolelog"Metadata:"metadataconsolelog// 输出示例：// --- Chunk 0 ---// Content: 欢迎使用我们的产品。// Metadata: { h1: "用户指南" }//// --- Chunk 1 ---// Content: 运行以下命令安装：...// Metadata: { h1: "用户指南", h2: "快速开始", h3: "安装" }//// --- Chunk 2 ---// Content: 在项目根目录创建配置文件...// Metadata: { h1: "用户指南", h2: "快速开始", h3: "配置" }

看到没？每个 chunk 的 metadata 里都带着完整的标题层级路径。检索的时候，你可以用这些 metadata 做过滤——比如用户问"怎么安装"，你可以优先搜索h3: "安装"的 chunk，精准度直接拉满。

实战中，MarkdownHeaderTextSplitter 通常和 RecursiveCharacterTextSplitter 组合使用：

importMarkdownHeaderTextSplitterRecursiveCharacterTextSplitterfrom"langchain/text_splitter"// 第一步：按标题结构切割，保留 metadataconstnewMarkdownHeaderTextSplitterheadersToSplitOn"#""h1""##""h2""###""h3"constawaitsplitText// 第二步：对每个 chunk 再做二次分割，控制大小constnewRecursiveCharacterTextSplitterchunkSize500chunkOverlap100constawaitsplitDocuments// finalChunks 每个都不超过 500 字符，且保留了标题层级 metadataconsolelog`最终 chunk 数量: ${finalChunks.length}`forEach(chunk, i) =>consolelog`Chunk ${i}: ${chunk.pageContent.length} chars`consolelog` Metadata:`metadata

两步分割流程： 原始 Markdown │ ▼ ┌──────────────────────────┐ │ MarkdownHeaderTextSplitter│ ← 按标题结构切，保留 metadata └──────────┬───────────────┘ │ ┌──────┴──────┐ ▼ ▼ [chunk1] [chunk2] ...可能某个 chunk 还是太长 │ │ ▼ ▼ ┌──────────────────────────┐ │RecursiveCharacterSplitter │ ← 控制每个 chunk 的大小 └──────────┬───────────────┘ │ ┌──┬───┴───┬──┐ ▼ ▼ ▼ ▼ [c1][c2] [c3][c4] ...每个都带着原始 metadata

04 CodeTextSplitter：让代码按语法结构切割

切代码和切自然语言完全是两回事。CodeTextSplitter 能识别编程语言的语法结构，避免把一个函数切成两半。

想象一下，一个 200 行的 TypeScript 文件，你用普通的字符分割器按 1000 字符切一刀。很可能刚好切在一个if-else块的中间，或者把函数签名和函数体分到两个 chunk 里。这种 chunk 送去 embedding，得到的向量基本没有语义价值。

LangChain.js 的RecursiveCharacterTextSplitter提供了fromLanguage静态方法，可以根据编程语言自动配置合适的分隔符：

importRecursiveCharacterTextSplitterfrom"langchain/text_splitter"importSupportedTextSplitterLanguagefrom"langchain/text_splitter"// 查看支持的语言列表consolelogRecursiveCharacterTextSplittergetSupportedLanguages// ['cpp', 'go', 'java', 'js', 'php', 'python', 'ruby', 'rust',// 'scala', 'swift', 'markdown', 'latex', 'html', 'sol']// 创建 TypeScript/JavaScript 代码分割器constRecursiveCharacterTextSplitterfromLanguage"js"chunkSize1000chunkOverlap200const`interface User { id: string; name: string; email: string; role: "admin" | "user" | "guest";}class UserService { private users: Map<string, User> = new Map(); async createUser(input: Omit<User, "id">): Promise<User> { const id = crypto.randomUUID(); const user: User = { id, ...input }; this.users.set(id, user); return user; } async getUserById(id: string): Promise<User | undefined> { return this.users.get(id); } async updateUser( id: string, updates: Partial<Omit<User, "id">> ): Promise<User> { const existing = this.users.get(id); if (!existing) { throw new Error(\`User \${id} not found\`); } const updated = { ...existing, ...updates }; this.users.set(id, updated); return updated; } async deleteUser(id: string): Promise<boolean> { return this.users.delete(id); } async listUsers(role?: User["role"]): Promise<User[]> { const allUsers = Array.from(this.users.values()); if (role) { return allUsers.filter((u) => u.role === role); } return allUsers; }}function formatUser(user: User): string { return \`\${user.name} (\${user.email}) - \${user.role}\`;}`constawaitcreateDocumentsforEach(chunk, i) =>consolelog`--- Code Chunk ${i} (${chunk.pageContent.length} chars) ---`consolelogpageContentconsolelog

JS/TS 的分隔符优先级大致是：

类/函数定义 → 方法定义 → 控制流语句 → 换行 → 空格 → 字符

这样一来，interface User和class UserService会被优先作为分割点，而不是在方法体内部硬切。

✅ 正确：针对不同语言用不同的 splitter

// ✅ Python 代码用 python splitterconstRecursiveCharacterTextSplitterfromLanguage"python"chunkSize1000chunkOverlap200// ✅ Markdown 文档用 markdown splitterconstRecursiveCharacterTextSplitterfromLanguage"markdown"chunkSize1000chunkOverlap200

❌ 错误：用通用 splitter 切代码

// ❌ 通用 splitter 不认识代码结构constnewRecursiveCharacterTextSplitterchunkSize1000chunkOverlap200// 会在 if 语句中间、函数参数列表中间等地方切割

05 HTMLSectionSplitter：基于 HTML 标签的结构化分割

处理网页内容时，HTMLSectionSplitter 能根据 HTML 标签（如 h1-h6、section、div）做语义分割。

爬取的网页内容往往带有丰富的 HTML 结构，直接扒成纯文本再切割，等于把最有价值的结构信息扔掉了。HTMLSectionSplitter 的思路和 MarkdownHeaderTextSplitter 类似——利用文档本身的标签结构来确定语义边界。

importHTMLSectionSplitterfrom"langchain/text_splitter"const`<!DOCTYPE html><html><body> <h1>API 文档</h1> <p>这是我们 REST API 的完整文档。</p> <h2>认证</h2> <p>所有请求需要在 Header 中携带 Bearer Token。</p> <p>Token 通过 /auth/login 接口获取，有效期为 24 小时。</p> <h2>用户接口</h2> <h3>获取用户列表</h3> <p>GET /api/users</p> <p>返回所有用户的分页列表，默认每页 20 条。</p> <h3>创建用户</h3> <p>POST /api/users</p> <p>请求体需包含 name、email、role 字段。</p> <h2>订单接口</h2> <p>订单相关的 CRUD 操作。</p> <h3>查询订单</h3> <p>GET /api/orders?status=pending</p> <p>支持按状态、时间范围筛选。</p></body></html>`constheadersstringstring"h1""h1""h2""h2""h3""h3"constnewHTMLSectionSplitterheadersToSplitOnconstawaitsplitTextforEach(chunk, i) =>consolelog`--- HTML Chunk ${i} ---`consolelog"Content:"pageContenttrimconsolelog"Metadata:"metadataconsolelog// 输出：// --- HTML Chunk 0 ---// Content: 这是我们 REST API 的完整文档。// Metadata: { h1: "API 文档" }//// --- HTML Chunk 1 ---// Content: 所有请求需要在 Header 中携带 Bearer Token...// Metadata: { h1: "API 文档", h2: "认证" }//// --- HTML Chunk 2 ---// Content: GET /api/users...// Metadata: { h1: "API 文档", h2: "用户接口", h3: "获取用户列表" }

使用场景判断：

06 语义分割（Semantic Chunking）：按"意思"切，而不是按"结构"切

前面所有 Splitter 都是基于规则的——按字符、按标题、按语法。语义分割则完全不同：它用 embedding 模型来判断"这句话和上一句话是不是在说同一件事"。

原理其实不复杂：

语义分割流程： 1. 把文本按句子拆开 [句子1] [句子2] [句子3] [句子4] [句子5] ... 2. 对每个句子做 embedding [vec1] [vec2] [vec3] [vec4] [vec5] ... 3. 计算相邻句子的余弦相似度 sim(1,2)=0.92 sim(2,3)=0.88 sim(3,4)=0.41 sim(4,5)=0.85 4. 相似度骤降的地方就是语义边界 ↑ 这里！0.88→0.41 断崖式下跌 说明句子3和句子4在讲不同的事 5. 在边界处切割 [句子1, 句子2, 句子3] | [句子4, 句子5, ...] chunk 1 chunk 2

LangChain.js 中可以通过实验性的语义分割方式来实现：

importOpenAIEmbeddingsfrom"@langchain/openai"// 语义分割的核心逻辑（简化实现，帮助理解原理）asyncfunctionsemanticChunking text: string, embeddings: OpenAIEmbeddings, threshold: number = 0.75Promisestring// 1. 按句子拆分constsplit/(?<=[.!?。！？\n])\s+/filter(s) =>trimlength0iflength1return// 2. 对每个句子做 embeddingconstawaitembedDocuments// 3. 计算相邻句子的余弦相似度constsimilaritiesnumberforlet0length1constcosineSimilarity1push// 4. 找到语义边界（相似度低于阈值的位置）constbreakpointsnumberforlet0lengthifpush1// 在第 i+1 个句子前切割// 5. 按边界切割constchunksstringlet0forconstofpushslicejoin" "pushslicejoin" "returnfunctioncosineSimilaritya: number[], b: number[]numberlet000forlet0lengthreturnMathsqrtMathsqrt// 使用constnewOpenAIEmbeddingsmodelName"text-embedding-3-small"const`LangChain 是一个强大的 LLM 应用开发框架。它提供了丰富的工具链来简化开发流程。开发者可以用它快速构建 chatbot、RAG 系统等应用。今天的天气非常好，阳光明媚。适合出去散步或者骑自行车。公园里的樱花已经开了，很多人在拍照。向量数据库是 RAG 系统的核心组件。它负责存储和检索 embedding 向量。常见的向量数据库包括 Pinecone、Weaviate 和 Chroma。`constawaitsemanticChunking0.78forEach(chunk, i) =>consolelog`--- Semantic Chunk ${i} ---`consolelogconsolelog// 会自动把"LangChain相关"、"天气相关"、"向量数据库相关"分成三个 chunk

语义分割的优缺点要清楚：

✅优点：

• 切割结果最符合人类直觉，同一个 chunk 里的内容确实在讲同一件事
• 不依赖文档格式，纯文本也能用
• 对混合主题的长文档效果特别好

❌缺点：

• 需要调用 embedding API，有额外的时间和费用成本
• threshold 的选择很主观，不同文档可能需要不同的值
• 对短文本效果不好，句子太少时相似度波动大

07 chunkSize 和 chunkOverlap：实战调优经验

chunkSize 和 chunkOverlap 没有"最佳值"，只有"最适合你场景的值"。但有一些经验法则可以参考。

这两个参数的选择，直接影响 RAG 的检索质量和成本。我把踩过的坑总结成一张决策表：

chunkSize 选择参考： ┌──────────────────┬────────────┬──────────────────────────────┐ │ 场景 │ chunkSize │ 原因 │ ├──────────────────┼────────────┼──────────────────────────────┤ │ FAQ / 问答对 │ 200-500 │ 每个 QA 本身就短，切太大会混入 │ │ │ │ 其他 QA 的内容 │ ├──────────────────┼────────────┼──────────────────────────────┤ │ 技术文档 │ 500-1000 │ 一个知识点通常在 500-1000 字 │ │ │ │ 能说清楚 │ ├──────────────────┼────────────┼──────────────────────────────┤ │ 法律/合同文本 │ 1000-2000 │ 条款之间有强关联，需要保持 │ │ │ │ 更大的上下文窗口 │ ├──────────────────┼────────────┼──────────────────────────────┤ │ 代码文件 │ 1000-2000 │ 一个完整的函数/类通常较长 │ ├──────────────────┼────────────┼──────────────────────────────┤ │ 聊天记录 │ 500-800 │ 对话轮次之间需要保持上下文 │ └──────────────────┴────────────┴──────────────────────────────┘ chunkOverlap 经验法则：chunkSize 的 10%-25%

来看一个对比实验：

importRecursiveCharacterTextSplitterfrom"langchain/text_splitter"const`这里假设是一篇 3000 字的技术文档...`// 三种配置对比constname"小块无重叠"chunkSize200chunkOverlap0name"中块适度重叠"chunkSize800chunkOverlap150name"大块高重叠"chunkSize2000chunkOverlap500forconstofconstnewRecursiveCharacterTextSplitterchunkSizechunkSizechunkOverlapchunkOverlapconstawaitcreateDocumentsconsolelog`[${config.name}]`consolelog` chunk 数量: ${chunks.length}`consolelog` 平均 chunk 大小: ${ Math.round(chunks.reduce((sum, c) => sum + c.pageContent.length, 0) / chunks.length) } chars`consolelog` 总字符数（含重叠）: ${ chunks.reduce((sum, c) => sum + c.pageContent.length, 0) }`consolelog// 预期输出：// [小块无重叠]// chunk 数量: 15// 平均 chunk 大小: 200 chars// 总字符数（含重叠）: 3000 ← 没有冗余，但边界信息丢失//// [中块适度重叠]// chunk 数量: 5// 平均 chunk 大小: 750 chars// 总字符数（含重叠）: 3750 ← 适度冗余，检索效果好//// [大块高重叠]// chunk 数量: 3// 平均 chunk 大小: 1800 chars// 总字符数（含重叠）: 5400 ← 大量冗余，token 浪费严重

我个人的默认起步配置是chunkSize: 800, chunkOverlap: 150，然后根据实际检索效果再调整。

08 分割策略决策树：一张图告诉你该用哪个

决策很简单，跟着这棵树走就行：

你的文档是什么格式？ │ ├── Markdown？ │ ├── 需要保留标题层级信息？ │ │ ├── 是 → MarkdownHeaderTextSplitter（+ Recursive 二次切割） │ │ └── 否 → RecursiveCharacterTextSplitter.fromLanguage("markdown") │ └ │ ├── HTML / 网页？ │ ├── 有清晰的 h1-h6 结构？ │ │ ├── 是 → HTMLSectionSplitter │ │ └── 否 → 先转纯文本，再用 RecursiveCharacterTextSplitter │ └ │ ├── 代码文件？ │ └── RecursiveCharacterTextSplitter.fromLanguage("对应语言") │ ├── 纯文本 / 通用文档？ │ ├── 文档主题单一，结构清晰？ │ │ └── RecursiveCharacterTextSplitter（默认分隔符） │ ├── 文档主题混杂，段落间跳跃大？ │ │ └── 语义分割（Semantic Chunking） │ └ │ └── 不确定 / 懒得想？ └── RecursiveCharacterTextSplitter ← 就它了，不会错

这就是标题说的"你只需要一个"的原因：RecursiveCharacterTextSplitter 是万金油。它不是最优解，但它是最安全的选择。只有当你明确知道文档结构、并且对检索精度有更高要求时，再考虑换成专用的 Splitter。

09 常见坑

坑 1：chunkSize 设太小，把完整语义切碎了

chunkSize 设成 100-200，一个段落被切成 3、4 块，每块都不完整。embedding 出来的向量语义模糊，检索什么都能匹配上一点，但什么都回答不准。建议最小不低于 300。

坑 2：忘记设 chunkOverlap，边界处信息丢失

两个相邻 chunk 之间没有重叠，刚好某个关键信息横跨了分割点——前一个 chunk 有"问题描述"，后一个 chunk 有"解决方案"，但它们被分到了两个不同的 chunk 里。检索时只能命中其中一个，LLM 拿到的上下文不完整。overlap 至少设 10%。

坑 3：对代码用通用分割器

代码和自然语言的结构完全不同。通用分割器可能在{和}中间切开，导致一个 chunk 里有if (condition) {但没有对应的}。不但语义碎片化，还可能导致后续处理（比如代码高亮、语法分析）出错。代码一定用fromLanguage。

坑 4：Markdown 标题里有特殊字符，Splitter 解析失败

比如标题是## 3.1 配置config.json文件，反引号可能干扰标题匹配。用 MarkdownHeaderTextSplitter 前，最好先做一轮预处理，清理标题中的特殊格式。

坑 5：语义分割的 threshold 一刀切

不同类型的文档，语义密度不同。技术文档相邻段落的相似度普遍较高（因为都在讲同一个技术主题），用 0.8 的 threshold 可能整篇文档都不切。而新闻聚合页主题跳跃大，0.8 会切得太碎。建议先跑一遍相似度分布，看看数据再定 threshold。

总结

• RecursiveCharacterTextSplitter 是你的首选 Splitter，它通过递归分隔符优先级策略，在绝大多数场景下都能给出合理的分割结果
• 处理 Markdown 文档时，用 MarkdownHeaderTextSplitter 按标题层级切割，它能把标题路径写进 metadata，大幅提升检索时的过滤精度
• 代码文件必须用 fromLanguage 创建专用分割器，否则会在语法结构中间硬切，产生无意义的 chunk
• chunkSize 推荐 500-1000 起步，chunkOverlap 设为 chunkSize 的 10%-20%，然后根据实际检索效果迭代调整
• 语义分割是终极武器但不是默认选择——它需要额外调用 embedding API，成本和延迟都更高，适合对精度要求极致的场景
• 当你拿不准用哪个 Splitter 时，选 RecursiveCharacterTextSplitter 不会错——先跑起来，再根据效果针对性优化

文档切好了，下一步就是把这些 chunk 变成向量、存进向量数据库。下一篇我们来聊向量数据库原理——embedding 是怎么存的、相似度搜索是怎么做到毫秒级的、主流向量数据库（Pinecone / Chroma / Weaviate）怎么选。

学AI大模型的正确顺序，千万不要搞错了

🤔2026年AI风口已来！各行各业的AI渗透肉眼可见，超多公司要么转型做AI相关产品，要么高薪挖AI技术人才，机遇直接摆在眼前！

有往AI方向发展，或者本身有后端编程基础的朋友，直接冲AI大模型应用开发转岗超合适！

就算暂时不打算转岗，了解大模型、RAG、Prompt、Agent这些热门概念，能上手做简单项目，也绝对是求职加分王🔋

📝给大家整理了超全最新的AI大模型应用开发学习清单和资料，手把手帮你快速入门！👇👇

学习路线:

✅大模型基础认知—大模型核心原理、发展历程、主流模型（GPT、文心一言等）特点解析
✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑
✅开发基础能力—Python进阶、API接口调用、大模型开发框架（LangChain等）实操
✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用
✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代
✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经

以上6大模块，看似清晰好上手，实则每个部分都有扎实的核心内容需要吃透！

我把大模型的学习全流程已经整理📚好了！抓住AI时代风口，轻松解锁职业新可能，希望大家都能把握机遇，实现薪资/职业跃迁～

这份完整版的大模型 AI 学习资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】