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

# .큰 덩어리()

그만큼`.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'`): The chunking strategy to use. If not specified, defaults based on document type. Depending on the chunking strategy, there are additional optionals. Defaults: .md files → 'markdown', .html/.htm → 'html', .json → 'json', .tex → 'latex', others → 'recursive'

**maxSize** (`number`): Maximum size of each chunk. Some strategy configurations (markdown with headers, HTML with headers) ignore this parameter. (Default: `4000`)

**overlap** (`number`): Number of characters/tokens that overlap between chunks. (Default: `50`)

**lengthFunction** (`(text: string) => number`): Function to calculate text length. Defaults to character count.

**separatorPosition** (`'start' | 'end'`): Where to position the separator in chunks. 'start' attaches to beginning of next chunk, 'end' attaches to end of current chunk. If not specified, separators are discarded.

**addStartIndex** (`boolean`): Whether to add start index metadata to chunks. (Default: `false`)

**stripWhitespace** (`boolean`): Whether to strip whitespace from chunks. (Default: `true`)

**extract** (`ExtractParams`): Metadata extraction configuration.

보다[ExtractParams reference](https://mastra.zisheng.pro/ko/reference/rag/extract-params) for details on the `extract` parameter.

## 전략별 옵션

전략별 옵션은 전략 매개변수와 함께 최상위 매개변수로 전달됩니다. 예를 들어:

```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
})
```

아래에 설명된 옵션은 별도의 옵션 개체 내에 중첩되지 않고 구성 개체의 최상위 수준에서 직접 전달됩니다.

### 성격

**separators** (`string[]`): Array of separators to try in order of preference. The strategy will attempt to split on the first separator, then fall back to subsequent ones.

**isSeparatorRegex** (`boolean`): Whether the separator is a regex pattern (Default: `false`)

### 재귀적

**separators** (`string[]`): Array of separators to try in order of preference. The strategy will attempt to split on the first separator, then fall back to subsequent ones.

**isSeparatorRegex** (`boolean`): Whether the separators are regex patterns (Default: `false`)

**language** (`Language`): Programming or markup language for language-specific splitting behavior. See Language enum for supported values.

### 문장

**maxSize** (`number`): Maximum size of each chunk (required for sentence strategy)

**minSize** (`number`): Minimum size of each chunk. Chunks smaller than this will be merged with adjacent chunks when possible. (Default: `50`)

**targetSize** (`number`): Preferred target size for chunks. Defaults to 80% of maxSize. The strategy will try to create chunks close to this size.

**sentenceEnders** (`string[]`): Array of characters that mark sentence endings for splitting boundaries. (Default: `['.', '!', '?']`)

**fallbackToWords** (`boolean`): Whether to fall back to word-level splitting for sentences that exceed maxSize. (Default: `true`)

**fallbackToCharacters** (`boolean`): Whether to fall back to character-level splitting for words that exceed maxSize. Only applies if fallbackToWords is enabled. (Default: `true`)

### HTML

**headers** (`Array<[string, string]>`): Array of \[selector, metadata key] pairs for header-based splitting

**sections** (`Array<[string, string]>`): Array of \[selector, metadata key] pairs for section-based splitting

**returnEachLine** (`boolean`): Whether to return each line as a separate chunk

HTML 전략을 사용할 때 모든 일반 옵션은 무시됩니다. 사용`headers` for header-based splitting or `sections` for section-based splitting. If used together, `sections` will be ignored.

### 가격 인하

**headers** (`Array<[string, string]>`): Array of \[header level, metadata key] pairs

**stripHeaders** (`boolean`): Whether to remove headers from the output

**returnEachLine** (`boolean`): Whether to return each line as a separate chunk

사용할 때`headers` 옵션을 사용하면 마크다운 전략은 모든 일반 옵션을 무시하고 마크다운 헤더 구조를 기준으로 콘텐츠를 분할합니다. 마크다운에서 크기 기반 청킹을 사용하려면 를 생략하세요. `headers` parameter.

### 의미론적 마크다운

**joinThreshold** (`number`): Maximum token count for merging related sections. Sections exceeding this limit individually are left intact, but smaller sections are merged with siblings or parents if the combined size stays under this threshold. (Default: `500`)

**modelName** (`string`): Name of the model for tokenization. If provided, the model's underlying tokenization encodingName will be used.

**encodingName** (`string`): Name of the token encoding to use. Derived from modelName if available. (Default: `cl100k_base`)

**allowedSpecial** (`Set<string> | 'all'`): Set of special tokens allowed during tokenization, or 'all' to allow all special tokens

**disallowedSpecial** (`Set<string> | 'all'`): Set of special tokens to disallow during tokenization, or 'all' to disallow all special tokens (Default: `all`)

### 토큰

**encodingName** (`string`): Name of the token encoding to use

**modelName** (`string`): Name of the model for tokenization

**allowedSpecial** (`Set<string> | 'all'`): Set of special tokens allowed during tokenization, or 'all' to allow all special tokens

**disallowedSpecial** (`Set<string> | 'all'`): Set of special tokens to disallow during tokenization, or 'all' to disallow all special tokens

### JSON

**maxSize** (`number`): Maximum size of each chunk

**minSize** (`number`): Minimum size of each chunk

**ensureAscii** (`boolean`): Whether to ensure ASCII encoding

**convertLists** (`boolean`): Whether to convert lists in the JSON

### 유액

Latex 전략은 위에 나열된 일반적인 청킹 옵션만 사용합니다. 수학 및 학술 문서에 최적화된 LaTeX 인식 분할을 제공합니다.

## 반환 값

다음을 반환합니다.`MDocument` 청킹된 문서를 포함하는 인스턴스입니다. 각 청크에는 다음이 포함됩니다:

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