> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/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`): 各チャンクの最大サイズ。一部の戦略設定（headers を指定した markdown、headers を指定した HTML）では、このパラメータは無視されます。 (Default: `4000`)

**overlap** (`number`): チャンク間で重複させる文字数またはトークン数。 (Default: `50`)

**lengthFunction** (`(text: string) => number`): テキストの長さを計算する関数。デフォルトでは文字数を使用します。

**separatorPosition** (`'start' | 'end'`): チャンク内で separator を配置する位置。'start' は次のチャンクの先頭に付加し、'end' は現在のチャンクの末尾に付加します。指定しない場合、separator は破棄されます。

**addStartIndex** (`boolean`): チャンクに開始インデックスのメタデータを追加するかどうか。 (Default: `false`)

**stripWhitespace** (`boolean`): チャンクから空白を除去するかどうか。 (Default: `true`)

**extract** (`ExtractParams`): メタデータ抽出の設定。

`extract` パラメータの詳細は、[ExtractParams リファレンス](https://mastra.zisheng.pro/ja/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[]`): 優先順に試行する separator の配列。最初の separator で分割を試み、分割できない場合は後続の separator を順に使用します。

**isSeparatorRegex** (`boolean`): separator が正規表現パターンかどうか (Default: `false`)

### Recursive

**separators** (`string[]`): 優先順に試行する separator の配列。最初の separator で分割を試み、分割できない場合は後続の separator を順に使用します。

**isSeparatorRegex** (`boolean`): separator が正規表現パターンかどうか (Default: `false`)

**language** (`Language`): 言語固有の分割動作に使用するプログラミング言語またはマークアップ言語。サポートされる値については、Language enum を参照してください。

### 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]>`): header ベースの分割に使用する \[selector, metadata key] のペアの配列

**sections** (`Array<[string, string]>`): section ベースの分割に使用する \[selector, metadata key] のペアの配列

**returnEachLine** (`boolean`): 各行を個別のチャンクとして返すかどうか

HTML 戦略を使用する場合、すべての一般オプションは無視されます。header ベースの分割には `headers` を、section ベースの分割には `sections` を使用します。両方を指定した場合、`sections` は無視されます。

### Markdown

**headers** (`Array<[string, string]>`): \[header level, metadata key] のペアの配列

**stripHeaders** (`boolean`): 出力から header を削除するかどうか

**returnEachLine** (`boolean`): 各行を個別のチャンクとして返すかどうか

`headers` オプションを使用すると、markdown 戦略ではすべての一般オプションが無視され、markdown の header 構造に基づいて内容が分割されます。markdown でサイズに基づくチャンク分割を使用するには、`headers` パラメータを省略してください。

### Semantic Markdown

**joinThreshold** (`number`): 関連する section を結合する際の最大トークン数。この上限を単独で超える section はそのまま維持されますが、小さい section は、結合後のサイズがこのしきい値以下であれば兄弟または親の section と結合されます。 (Default: `500`)

**modelName** (`string`): トークン化に使用するモデル名。指定すると、モデルが内部で使用するトークン化の encodingName が使用されます。

**encodingName** (`string`): 使用するトークンエンコーディングの名前。利用可能な場合は modelName から導出されます。 (Default: `cl100k_base`)

**allowedSpecial** (`Set<string> | 'all'`): トークン化で許可する特殊トークンのセット。すべての特殊トークンを許可する場合は 'all'

**disallowedSpecial** (`Set<string> | 'all'`): トークン化で禁止する特殊トークンのセット。すべての特殊トークンを禁止する場合は 'all' (Default: `all`)

### Token

**encodingName** (`string`): 使用するトークンエンコーディングの名前

**modelName** (`string`): トークン化に使用するモデル名

**allowedSpecial** (`Set<string> | 'all'`): トークン化で許可する特殊トークンのセット。すべての特殊トークンを許可する場合は 'all'

**disallowedSpecial** (`Set<string> | 'all'`): トークン化で禁止する特殊トークンのセット。すべての特殊トークンを禁止する場合は 'all'

### 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[]
}
```