> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# .chunk()

`.chunk()` 函数使用策略和选项将文档拆分为较小片段。

## 示例

```typescript
import { MDocument } from '@mastra/rag'

const doc = MDocument.fromMarkdown(`
# Introduction
This is a sample document that we want to split into chunks.

## Section 1
Here is the first section with some content.

## Section 2
Here is another section with different content.
`)

// Basic chunking with defaults
const chunks = await doc.chunk()

// Markdown-specific chunking with header extraction
const chunksWithMetadata = await doc.chunk({
  strategy: 'markdown',
  headers: [
    ['#', 'title'],
    ['##', 'section'],
  ],
  extract: {
    summary: true, // Extract summaries with default settings
    keywords: true, // Extract keywords with default settings
  },
})
```

## 参数

以下参数适用于所有分块策略。 每种策略只会使用与其特定用例相关的一部分参数。

**strategy** (`'recursive' | 'character' | 'token' | 'markdown' | 'semantic-markdown' | 'html' | 'json' | 'latex' | 'sentence'`): 要使用的分块策略。未指定时，会根据文档类型使用默认值。不同分块策略还具有额外可选项。默认值：.md 文件 → 'markdown'，.html/.htm → 'html'，.json → 'json'，.tex → 'latex'，其他 → 'recursive'。

**maxSize** (`number`): 每个块的最大大小。某些策略配置（带标题的 markdown、带标题的 HTML）会忽略此参数。 (Default: `4000`)

**overlap** (`number`): 块之间重叠的字符/token 数量。 (Default: `50`)

**lengthFunction** (`(text: string) => number`): 用于计算文本长度的函数。默认按字符数计算。

**separatorPosition** (`'start' | 'end'`): 分隔符在块中的位置。'start' 会附加到下一块的开头，'end' 会附加到当前块的末尾。未指定时会丢弃分隔符。

**addStartIndex** (`boolean`): 是否向块添加起始索引元数据。 (Default: `false`)

**stripWhitespace** (`boolean`): 是否移除块中的空白字符。 (Default: `true`)

**extract** (`ExtractParams`): 元数据提取配置。

有关 `extract` 参数的详细信息，请参阅 [ExtractParams 参考](https://mastra.zisheng.pro/reference/rag/extract-params)。

## 策略专属选项

策略专属选项会与 strategy 参数一起作为顶层参数传入。例如：

```typescript
// Character strategy example
const chunks = await doc.chunk({
  strategy: 'character',
  separator: '.', // Character-specific option
  isSeparatorRegex: false, // Character-specific option
  maxSize: 300, // general option
})

// Recursive strategy example
const chunks = await doc.chunk({
  strategy: 'recursive',
  separators: ['\n\n', '\n', ' '], // Recursive-specific option
  language: 'markdown', // Recursive-specific option
  maxSize: 500, // general option
})

// Sentence strategy example
const chunks = await doc.chunk({
  strategy: 'sentence',
  maxSize: 450, // Required for sentence strategy
  minSize: 50, // Sentence-specific option
  sentenceEnders: ['.'], // Sentence-specific option
  fallbackToCharacters: false, // Sentence-specific option
})

// HTML strategy example
const chunks = await doc.chunk({
  strategy: 'html',
  headers: [
    ['h1', 'title'],
    ['h2', 'subtitle'],
  ], // HTML-specific option
})

// Markdown strategy example
const chunks = await doc.chunk({
  strategy: 'markdown',
  headers: [
    ['#', 'title'],
    ['##', 'section'],
  ], // Markdown-specific option
  stripHeaders: true, // Markdown-specific option
})

// Semantic Markdown strategy example
const chunks = await doc.chunk({
  strategy: 'semantic-markdown',
  joinThreshold: 500, // Semantic Markdown-specific option
  modelName: 'gpt-3.5-turbo', // Semantic Markdown-specific option
})

// Token strategy example
const chunks = await doc.chunk({
  strategy: 'token',
  encodingName: 'gpt2', // Token-specific option
  modelName: 'gpt-3.5-turbo', // Token-specific option
  maxSize: 1000, // general option
})
```

以下记录的选项会直接传入配置对象的顶层，而不会嵌套在单独的 options 对象中。

### Character

**separators** (`string[]`): 按优先级顺序尝试的分隔符数组。策略会先尝试使用第一个分隔符拆分，然后回退到后续分隔符。

**isSeparatorRegex** (`boolean`): 分隔符是否为正则表达式模式 (Default: `false`)

### Recursive

**separators** (`string[]`): 按优先级顺序尝试的分隔符数组。策略会先尝试使用第一个分隔符拆分，然后回退到后续分隔符。

**isSeparatorRegex** (`boolean`): 分隔符是否为正则表达式模式 (Default: `false`)

**language** (`Language`): 用于语言专属拆分行为的编程或标记语言。支持的值请参阅 Language 枚举。

### Sentence

**maxSize** (`number`): 每个块的最大大小（sentence 策略必填）

**minSize** (`number`): 每个块的最小大小。小于此值的块会在可能时与相邻块合并。 (Default: `50`)

**targetSize** (`number`): 块的首选目标大小。默认值为 maxSize 的 80%。策略会尝试创建接近此大小的块。

**sentenceEnders** (`string[]`): 标记句子结尾、用作拆分边界的字符数组。 (Default: `['.', '!', '?']`)

**fallbackToWords** (`boolean`): 对于超过 maxSize 的句子，是否回退到词级拆分。 (Default: `true`)

**fallbackToCharacters** (`boolean`): 对于超过 maxSize 的词，是否回退到字符级拆分。仅在启用 fallbackToWords 时适用。 (Default: `true`)

### HTML

**headers** (`Array<[string, string]>`): 用于基于标题拆分的 \[selector, metadata key] 对数组

**sections** (`Array<[string, string]>`): 用于基于章节拆分的 \[selector, metadata key] 对数组

**returnEachLine** (`boolean`): 是否将每一行作为单独的块返回

使用 HTML 策略时，所有通用选项都会被忽略。使用 `headers` 按标题拆分，或使用 `sections` 按章节拆分。如果同时使用，则会忽略 `sections`。

### Markdown

**headers** (`Array<[string, string]>`): \[header level, metadata key] 对数组

**stripHeaders** (`boolean`): 是否从输出中移除标题

**returnEachLine** (`boolean`): 是否将每一行作为单独的块返回

使用 `headers` 选项时，markdown 策略会忽略所有通用选项，并根据 markdown 标题结构拆分内容。要对 markdown 使用基于大小的分块，请省略 `headers` 参数。

### Semantic Markdown

**joinThreshold** (`number`): 合并相关章节的最大 token 数。单独超过此限制的章节会保持不变；若合并后大小仍低于此阈值，较小章节会与同级或父级章节合并。 (Default: `500`)

**modelName** (`string`): 用于 tokenization 的模型名称。如果提供，将使用该模型底层 tokenization 的 encodingName。

**encodingName** (`string`): 要使用的 token 编码名称。若可用，则从 modelName 推导。 (Default: `cl100k_base`)

**allowedSpecial** (`Set<string> | 'all'`): tokenization 期间允许的特殊 token 集合，或使用 'all' 允许所有特殊 token

**disallowedSpecial** (`Set<string> | 'all'`): tokenization 期间不允许的特殊 token 集合，或使用 'all' 禁止所有特殊 token (Default: `all`)

### Token

**encodingName** (`string`): 要使用的 token 编码名称

**modelName** (`string`): 用于 tokenization 的模型名称

**allowedSpecial** (`Set<string> | 'all'`): tokenization 期间允许的特殊 token 集合，或使用 'all' 允许所有特殊 token

**disallowedSpecial** (`Set<string> | 'all'`): tokenization 期间不允许的特殊 token 集合，或使用 'all' 禁止所有特殊 token

### JSON

**maxSize** (`number`): 每个块的最大大小

**minSize** (`number`): 每个块的最小大小

**ensureAscii** (`boolean`): 是否确保使用 ASCII 编码

**convertLists** (`boolean`): 是否转换 JSON 中的列表

### Latex

Latex 策略仅使用上面列出的通用分块选项。它提供针对数学和学术文档优化的 LaTeX 感知拆分。

## 返回值

返回包含分块后文档的 `MDocument` 实例。每个块包括：

```typescript
interface DocumentNode {
  text: string
  metadata: Record<string, any>
  embedding?: number[]
}
```