メインコンテンツへ移動

.chunk()

.chunk() 関数は、戦略とオプションを使用してドキュメントを小さなセグメントに分割します。

使用例
使用例への直接リンク

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
= 4000
各チャンクの最大サイズ。一部の戦略設定（headers を指定した markdown、headers を指定した HTML）では、このパラメータは無視されます。

overlap?:

number
= 50
チャンク間で重複させる文字数またはトークン数。

lengthFunction?:

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

separatorPosition?:

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

addStartIndex?:

boolean
= false
チャンクに開始インデックスのメタデータを追加するかどうか。

stripWhitespace?:

boolean
= true
チャンクから空白を除去するかどうか。

extract?:

ExtractParams
メタデータ抽出の設定。

extract パラメータの詳細は、ExtractParams リファレンスを参照してください。

戦略固有のオプション
戦略固有のオプションへの直接リンク

戦略固有のオプションは、strategy パラメータと並ぶトップレベルのパラメータとして渡します。次に例を示します。

// 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
Characterへの直接リンク

separators?:

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

isSeparatorRegex?:

boolean
= false
separator が正規表現パターンかどうか

Recursive
Recursiveへの直接リンク

separators?:

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

isSeparatorRegex?:

boolean
= false
separator が正規表現パターンかどうか

language?:

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

Sentence
Sentenceへの直接リンク

maxSize:

number
各チャンクの最大サイズ（sentence 戦略では必須）

minSize?:

number
= 50
各チャンクの最小サイズ。これより小さいチャンクは、可能であれば隣接するチャンクと結合されます。

targetSize?:

number
チャンクの推奨目標サイズ。デフォルトは maxSize の 80% です。この戦略では、このサイズに近いチャンクの作成を試みます。

sentenceEnders?:

string[]
= ['.', '!', '?']
分割境界となる文末を示す文字の配列。

fallbackToWords?:

boolean
= true
maxSize を超える文を単語単位の分割にフォールバックするかどうか。

fallbackToCharacters?:

boolean
= true
maxSize を超える単語を文字単位の分割にフォールバックするかどうか。fallbackToWords が有効な場合にのみ適用されます。

HTML
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
Markdownへの直接リンク

headers?:

Array<[string, string]>
[header level, metadata key] のペアの配列

stripHeaders?:

boolean
出力から header を削除するかどうか

returnEachLine?:

boolean
各行を個別のチャンクとして返すかどうか

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

Semantic Markdown
Semantic Markdownへの直接リンク

joinThreshold?:

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

modelName?:

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

encodingName?:

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

allowedSpecial?:

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

disallowedSpecial?:

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

Token
Tokenへの直接リンク

encodingName?:

string
使用するトークンエンコーディングの名前

modelName?:

string
トークン化に使用するモデル名

allowedSpecial?:

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

disallowedSpecial?:

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

JSON
JSONへの直接リンク

maxSize:

number
各チャンクの最大サイズ

minSize?:

number
各チャンクの最小サイズ

ensureAscii?:

boolean
ASCII エンコーディングを保証するかどうか

convertLists?:

boolean
JSON 内のリストを変換するかどうか

Latex
Latexへの直接リンク

Latex 戦略では、上記の一般的なチャンク分割オプションだけを使用します。数式や学術ドキュメント向けに最適化された、LaTeX を考慮した分割を行います。

戻り値
戻り値への直接リンク

チャンクに分割されたドキュメントを含む MDocument インスタンスを返します。各チャンクには次の内容が含まれます。

interface DocumentNode {
  text: string
  metadata: Record<string, any>
  embedding?: number[]
}
On this page