リファレンス: .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?:

使用するチャンク分割戦略。指定されていない場合、ドキュメントタイプに基づいてデフォルトが設定されます。チャンク分割戦略によって、追加のオプションがあります。デフォルト: .mdファイル → 'markdown'、.html/.htm → 'html'、.json → 'json'、.tex → 'latex'、その他 → 'recursive'

maxSize?:

number

= 4000

各チャンクの最大サイズ。**注意:** 一部の戦略設定（ヘッダー付きmarkdown、ヘッダー付きHTML）では、このパラメータは無視されます。

size?:

number

**非推奨:** 代わりに`maxSize`を使用してください。このパラメータは次のメジャーバージョンで削除されます。

overlap?:

number

= 50

チャンク間で重複する文字数/トークン数。

lengthFunction?:

(text: string) => number

テキストの長さを計算する関数。デフォルトは文字数カウント。

keepSeparator?:

boolean | 'start' | 'end'

チャンクの開始または終了でセパレータを保持するかどうか

addStartIndex?:

boolean

= false

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

stripWhitespace?:

boolean

= true

チャンクから空白文字を除去するかどうか。

extract?:

ExtractParams

メタデータ抽出設定。

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

戦略固有のオプション

戦略固有のオプションは、strategy パラメータと同じトップレベルのパラメータとして渡します。例:


// Character 戦略の例
const chunks = await doc.chunk({
  strategy: "character",
  separator: ".", // Character 固有のオプション
  isSeparatorRegex: false, // Character 固有のオプション
  maxSize: 300, // 一般的なオプション
});
 
// Recursive 戦略の例
const chunks = await doc.chunk({
  strategy: "recursive",
  separators: ["\n\n", "\n", " "], // Recursive 固有のオプション
  language: "markdown", // Recursive 固有のオプション
  maxSize: 500, // 一般的なオプション
});
 
// Sentence 戦略の例
const chunks = await doc.chunk({
  strategy: "sentence",
  maxSize: 450, // Sentence 戦略では必須
  minSize: 50, // Sentence 固有のオプション
  sentenceEnders: ["."], // Sentence 固有のオプション
  fallbackToCharacters: false, // Sentence 固有のオプション
  keepSeparator: true, // 一般的なオプション
});
 
// HTML 戦略の例
const chunks = await doc.chunk({
  strategy: "html",
  headers: [
    ["h1", "title"],
    ["h2", "subtitle"],
  ], // HTML 固有のオプション
});
 
// Markdown 戦略の例
const chunks = await doc.chunk({
  strategy: "markdown",
  headers: [
    ["#", "title"],
    ["##", "section"],
  ], // Markdown 固有のオプション
  stripHeaders: true, // Markdown 固有のオプション
});
 
// Semantic Markdown 戦略の例
const chunks = await doc.chunk({
  strategy: "semantic-markdown",
  joinThreshold: 500, // Semantic Markdown 固有のオプション
  modelName: "gpt-3.5-turbo", // Semantic Markdown 固有のオプション
});
 
// Token 戦略の例
const chunks = await doc.chunk({
  strategy: "token",
  encodingName: "gpt2", // Token 固有のオプション
  modelName: "gpt-3.5-turbo", // Token 固有のオプション
  maxSize: 1000, // 一般的なオプション
});

以下のオプションは、別の options オブジェクトに入れず、設定オブジェクトのトップレベルに直接渡します。

Character

separators?:

string[]

優先順で試す区切り文字の配列。最初の区切りで分割を試み、できなければ次にフォールバックします。

isSeparatorRegex?:

boolean

= false

区切り文字が正規表現パターンかどうか

Recursive

separators?:

string[]

優先順で試す区切り文字の配列。最初の区切りで分割を試み、できなければ次にフォールバックします。

isSeparatorRegex?:

boolean

= false

区切り文字が正規表現パターンかどうか

language?:

Language

言語固有の分割動作のためのプログラミング言語またはマークアップ言語。対応値は Language enum を参照してください。

Sentence

maxSize:

number

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

minSize?:

number

= 50

各チャンクの最小サイズ。これより小さいチャンクは、可能な場合に隣接するチャンクと結合されます。

targetSize?:

number

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

sentenceEnders?:

string[]

= ['.', '!', '?']

分割境界となる文末記号の配列。

fallbackToWords?:

boolean

= true

maxSizeを超える文章に対して単語レベルの分割にフォールバックするかどうか。

fallbackToCharacters?:

boolean

= true

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

HTML

headers:

Array<[string, string]>

ヘッダーベースの分割用の[セレクタ, メタデータキー]ペアの配列

sections:

Array<[string, string]>

セクションベースの分割用の[セレクタ, メタデータキー]ペアの配列

returnEachLine?:

boolean

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

重要: HTML戦略を使用する場合、すべての一般オプションは無視されます。ヘッダーベースの分割にはheadersを、セクションベースの分割にはsectionsを使用してください。両方を同時に使用した場合、sectionsは無視されます。

Markdown

headers?:

Array<[string, string]>

[ヘッダーレベル, メタデータキー]ペアの配列

stripHeaders?:

boolean

出力からヘッダーを削除するかどうか

returnEachLine?:

boolean

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

重要: headersオプションを使用する場合、Markdown戦略はすべての一般オプションを無視し、Markdownヘッダー構造に基づいてコンテンツが分割されます。Markdownでサイズベースのチャンク化を使用するには、headersパラメータを省略してください。

Semantic Markdown

joinThreshold?:

number

= 500

関連セクションを結合するための最大トークン数。この制限を個別に超えるセクションはそのまま残されますが、小さなセクションは結合後のサイズがこの閾値以下に収まる場合、兄弟または親セクションと結合されます。

modelName?:

string

トークン化用のモデル名。指定された場合、そのモデルの基盤となるトークン化`encodingName`が使用されます。

encodingName?:

string

= cl100k_base

使用するトークンエンコーディングの名前。`modelName`が利用可能な場合はそこから派生されます。

allowedSpecial?:

Set<string> | 'all'

トークン化中に許可される特殊トークンのセット、またはすべての特殊トークンを許可する'all'

disallowedSpecial?:

Set<string> | 'all'

= all

トークン化中に禁止する特殊トークンのセット、またはすべての特殊トークンを禁止する'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 インスタンスを返します。各チャンクには以下が含まれます：


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

リファレンス: .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?:

maxSize?:

number

= 4000

各チャンクの最大サイズ。**注意:** 一部の戦略設定（ヘッダー付きmarkdown、ヘッダー付きHTML）では、このパラメータは無視されます。

size?:

number

**非推奨:** 代わりに`maxSize`を使用してください。このパラメータは次のメジャーバージョンで削除されます。

overlap?:

number

= 50

チャンク間で重複する文字数/トークン数。

lengthFunction?:

(text: string) => number

テキストの長さを計算する関数。デフォルトは文字数カウント。

keepSeparator?:

boolean | 'start' | 'end'

チャンクの開始または終了でセパレータを保持するかどうか

addStartIndex?:

boolean

= false

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

stripWhitespace?:

boolean

= true

チャンクから空白文字を除去するかどうか。

extract?:

ExtractParams

メタデータ抽出設定。

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

戦略固有のオプション

戦略固有のオプションは、strategy パラメータと同じトップレベルのパラメータとして渡します。例:


// Character 戦略の例
const chunks = await doc.chunk({
  strategy: "character",
  separator: ".", // Character 固有のオプション
  isSeparatorRegex: false, // Character 固有のオプション
  maxSize: 300, // 一般的なオプション
});
 
// Recursive 戦略の例
const chunks = await doc.chunk({
  strategy: "recursive",
  separators: ["\n\n", "\n", " "], // Recursive 固有のオプション
  language: "markdown", // Recursive 固有のオプション
  maxSize: 500, // 一般的なオプション
});
 
// Sentence 戦略の例
const chunks = await doc.chunk({
  strategy: "sentence",
  maxSize: 450, // Sentence 戦略では必須
  minSize: 50, // Sentence 固有のオプション
  sentenceEnders: ["."], // Sentence 固有のオプション
  fallbackToCharacters: false, // Sentence 固有のオプション
  keepSeparator: true, // 一般的なオプション
});
 
// HTML 戦略の例
const chunks = await doc.chunk({
  strategy: "html",
  headers: [
    ["h1", "title"],
    ["h2", "subtitle"],
  ], // HTML 固有のオプション
});
 
// Markdown 戦略の例
const chunks = await doc.chunk({
  strategy: "markdown",
  headers: [
    ["#", "title"],
    ["##", "section"],
  ], // Markdown 固有のオプション
  stripHeaders: true, // Markdown 固有のオプション
});
 
// Semantic Markdown 戦略の例
const chunks = await doc.chunk({
  strategy: "semantic-markdown",
  joinThreshold: 500, // Semantic Markdown 固有のオプション
  modelName: "gpt-3.5-turbo", // Semantic Markdown 固有のオプション
});
 
// Token 戦略の例
const chunks = await doc.chunk({
  strategy: "token",
  encodingName: "gpt2", // Token 固有のオプション
  modelName: "gpt-3.5-turbo", // Token 固有のオプション
  maxSize: 1000, // 一般的なオプション
});

以下のオプションは、別の options オブジェクトに入れず、設定オブジェクトのトップレベルに直接渡します。

Character

separators?:

string[]

優先順で試す区切り文字の配列。最初の区切りで分割を試み、できなければ次にフォールバックします。

isSeparatorRegex?:

boolean

= false

区切り文字が正規表現パターンかどうか

Recursive

separators?:

string[]

優先順で試す区切り文字の配列。最初の区切りで分割を試み、できなければ次にフォールバックします。

isSeparatorRegex?:

boolean

= false

区切り文字が正規表現パターンかどうか

language?:

Language

言語固有の分割動作のためのプログラミング言語またはマークアップ言語。対応値は Language enum を参照してください。

Sentence

maxSize:

number

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

minSize?:

number

= 50

各チャンクの最小サイズ。これより小さいチャンクは、可能な場合に隣接するチャンクと結合されます。

targetSize?:

number

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

sentenceEnders?:

string[]

= ['.', '!', '?']

分割境界となる文末記号の配列。

fallbackToWords?:

boolean

= true

maxSizeを超える文章に対して単語レベルの分割にフォールバックするかどうか。

fallbackToCharacters?:

boolean

= true

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

HTML

headers:

Array<[string, string]>

ヘッダーベースの分割用の[セレクタ, メタデータキー]ペアの配列

sections:

Array<[string, string]>

セクションベースの分割用の[セレクタ, メタデータキー]ペアの配列

returnEachLine?:

boolean

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

Markdown

headers?:

Array<[string, string]>

[ヘッダーレベル, メタデータキー]ペアの配列

stripHeaders?:

boolean

出力からヘッダーを削除するかどうか

returnEachLine?:

boolean

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

Semantic Markdown

joinThreshold?:

number

= 500

modelName?:

string

トークン化用のモデル名。指定された場合、そのモデルの基盤となるトークン化`encodingName`が使用されます。

encodingName?:

string

= cl100k_base

使用するトークンエンコーディングの名前。`modelName`が利用可能な場合はそこから派生されます。

allowedSpecial?:

Set<string> | 'all'

トークン化中に許可される特殊トークンのセット、またはすべての特殊トークンを許可する'all'

disallowedSpecial?:

Set<string> | 'all'

= all

トークン化中に禁止する特殊トークンのセット、またはすべての特殊トークンを禁止する'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 インスタンスを返します。各チャンクには以下が含まれます：


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