.chunk()

La fonction .chunk() divise les documents en segments plus petits au moyen de stratégies et d'options.

Exemple

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

Paramètres

Les paramètres suivants sont disponibles pour toutes les stratégies de découpage. Chaque stratégie n'utilise que le sous-ensemble de paramètres adapté à son cas d'utilisation.

strategy?:

'recursive' | 'character' | 'token' | 'markdown' | 'semantic-markdown' | 'html' | 'json' | 'latex' | 'sentence'

Stratégie de découpage à utiliser. Si elle n'est pas précisée, la valeur par défaut dépend du type de document. Selon la stratégie de découpage, des options supplémentaires sont disponibles. Valeurs par défaut : fichiers .md → 'markdown', .html/.htm → 'html', .json → 'json', .tex → 'latex', autres → 'recursive'

maxSize?:

number

= 4000

Taille maximale de chaque segment. Certaines configurations de stratégie (markdown avec des en-têtes, HTML avec des en-têtes) ignorent ce paramètre.

overlap?:

number

= 50

Nombre de caractères ou de tokens qui se chevauchent entre les segments.

lengthFunction?:

(text: string) => number

Fonction permettant de calculer la longueur du texte. Utilise par défaut le nombre de caractères.

separatorPosition?:

'start' | 'end'

Emplacement du séparateur dans les segments. 'start' le rattache au début du segment suivant, tandis que 'end' le rattache à la fin du segment actuel. Si aucune valeur n'est précisée, les séparateurs sont supprimés.

addStartIndex?:

boolean

= false

Indique s'il faut ajouter aux segments les métadonnées de l'index de départ.

stripWhitespace?:

boolean

= true

Indique s'il faut supprimer les espaces des segments.

extract?:

ExtractParams

Configuration de l'extraction des métadonnées.

Consultez la référence d'ExtractParams pour plus de détails sur le paramètre extract.

Options propres aux stratégies

Les options propres à une stratégie sont transmises comme paramètres de premier niveau avec le paramètre de stratégie. Par exemple :

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

Les options décrites ci-dessous sont transmises directement au premier niveau de l'objet de configuration, et non imbriquées dans un objet d'options distinct.

Character

separators?:

string[]

Tableau de séparateurs à essayer par ordre de préférence. La stratégie tente d'effectuer le découpage sur le premier séparateur, puis utilise les suivants comme solutions de repli.

isSeparatorRegex?:

boolean

= false

Indique si le séparateur est un motif regex

Recursive

separators?:

string[]

Tableau de séparateurs à essayer par ordre de préférence. La stratégie tente d'effectuer le découpage sur le premier séparateur, puis utilise les suivants comme solutions de repli.

isSeparatorRegex?:

boolean

= false

Indique si les séparateurs sont des motifs regex

language?:

Language

Langage de programmation ou de balisage utilisé pour un comportement de découpage propre au langage. Consultez l'enum Language pour connaître les valeurs prises en charge.

Sentence

maxSize:

number

Taille maximale de chaque segment (obligatoire pour la stratégie sentence)

minSize?:

number

= 50

Taille minimale de chaque segment. Dans la mesure du possible, les segments plus petits sont fusionnés avec les segments adjacents.

targetSize?:

number

Taille cible privilégiée des segments. Utilise par défaut 80 % de maxSize. La stratégie tente de créer des segments proches de cette taille.

sentenceEnders?:

string[]

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

Tableau de caractères marquant les fins de phrase utilisées comme limites de découpage.

fallbackToWords?:

boolean

= true

Indique si un découpage au niveau des mots doit être utilisé pour les phrases qui dépassent maxSize.

fallbackToCharacters?:

boolean

= true

Indique si un découpage au niveau des caractères doit être utilisé pour les mots qui dépassent maxSize. Ne s'applique que si fallbackToWords est activé.

HTML

headers:

Array<[string, string]>

Tableau de paires [sélecteur, clé de métadonnées] pour le découpage fondé sur les en-têtes

sections:

Array<[string, string]>

Tableau de paires [sélecteur, clé de métadonnées] pour le découpage fondé sur les sections

returnEachLine?:

boolean

Indique si chaque ligne doit être renvoyée comme un segment distinct

Lorsque vous utilisez la stratégie HTML, toutes les options générales sont ignorées. Utilisez headers pour le découpage fondé sur les en-têtes ou sections pour celui fondé sur les sections. Si les deux sont utilisés, sections est ignoré.

Markdown

headers?:

Array<[string, string]>

Tableau de paires [niveau d'en-tête, clé de métadonnées]

stripHeaders?:

boolean

Indique si les en-têtes doivent être supprimés de la sortie

returnEachLine?:

boolean

Indique si chaque ligne doit être renvoyée comme un segment distinct

Lorsque vous utilisez l'option headers, la stratégie markdown ignore toutes les options générales et découpe le contenu selon la structure des en-têtes markdown. Pour utiliser avec markdown un découpage fondé sur la taille, omettez le paramètre headers.

Semantic Markdown

joinThreshold?:

number

= 500

Nombre maximal de tokens pour fusionner les sections associées. Les sections qui dépassent individuellement cette limite restent intactes, tandis que les plus petites sont fusionnées avec leurs sections sœurs ou parentes si leur taille combinée demeure sous ce seuil.

modelName?:

string

Nom du modèle utilisé pour la tokenisation. S'il est fourni, son encodingName de tokenisation sous-jacent est utilisé.

encodingName?:

string

= cl100k_base

Nom de l'encodage des tokens à utiliser. Dérivé de modelName lorsqu'il est disponible.

allowedSpecial?:

Set<string> | 'all'

Ensemble des tokens spéciaux autorisés pendant la tokenisation, ou 'all' pour tous les autoriser

disallowedSpecial?:

Set<string> | 'all'

= all

Ensemble des tokens spéciaux à interdire pendant la tokenisation, ou 'all' pour tous les interdire

Token

encodingName?:

string

Nom de l'encodage des tokens à utiliser

modelName?:

string

Nom du modèle utilisé pour la tokenisation

allowedSpecial?:

Set<string> | 'all'

Ensemble des tokens spéciaux autorisés pendant la tokenisation, ou 'all' pour tous les autoriser

disallowedSpecial?:

Set<string> | 'all'

Ensemble des tokens spéciaux à interdire pendant la tokenisation, ou 'all' pour tous les interdire

JSON

maxSize:

number

Taille maximale de chaque segment

minSize?:

number

Taille minimale de chaque segment

ensureAscii?:

boolean

Indique s'il faut garantir l'encodage ASCII

convertLists?:

boolean

Indique si les listes doivent être converties dans le JSON

Latex

La stratégie Latex utilise uniquement les options générales de découpage répertoriées ci-dessus. Elle fournit un découpage tenant compte de LaTeX et optimisé pour les documents mathématiques et universitaires.

Valeur de retour

Renvoie une instance de MDocument contenant les documents découpés. Chaque segment comprend :

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