Découpeurs de Texte

Découpez les documents en chunks optimisés pour les embeddings et la récupération avec des stratégies intelligentes.

Pourquoi Découper le Texte ?

Les documents volumineux doivent être découpés en chunks plus petits pour une recherche sémantique et une injection de contexte efficaces. Un bon découpage préserve le sens et respecte la structure du document.

Granularity

Dimensionnement

chunk_size

500-1000 car. pour la précision; 2k pour les synthèses.

Continuity

Chevauchement

overlap_ratio

Zone tampon de 10-20% pour ne pas perdre le sens aux coupures.

Integrity

Logique Structurelle

semantic_split

Priorise les paragraphes et phrases plutôt qu'un compte fixe.

# RecursiveCharacterTextSplitter

Le découpeur le plus polyvalent. Utilise des séparateurs hiérarchiques pour découper le texte tout en préservant les limites sémantiques. Essaie de découper sur les paragraphes d'abord, puis les phrases, puis les mots, et enfin les caractères en dernier recours.

import { RecursiveCharacterTextSplitter } from '@orka-js/tools';
 
const splitter = new RecursiveCharacterTextSplitter({
  chunkSize: 1000,           // Taille cible des chunks en caractères
  chunkOverlap: 200,         // Chevauchement entre les chunks
  separators: ['\n\n', '\n', '. ', ' ', ''],  // Essayer ces séparateurs dans cet ordre
  keepSeparator: true,       // Garder les séparateurs dans les chunks
  trimWhitespace: true       // Supprimer les espaces en début et fin
});
 
const text = `Contenu long du document ici...`;
const chunks = splitter.split(text);
 
// Or split multiple documents
const documents = [
  { id: '1', content: 'Doc 1...', metadata: {} },
  { id: '2', content: 'Doc 2...', metadata: {} }
];
const allChunks = splitter.splitDocuments(documents);

Intégrité des Paragraphes

Objectif prioritaire : garder les paragraphes complets pour préserver l'unité sémantique.

\n\nPriority 1

Sauts de Ligne

Si les paragraphes sont trop grands, le splitter se replie sur les lignes individuelles.

\nPriority 2

Logique de Phrases

Troisième recours : découpe aux points pour s'assurer que les pensées restent complètes.

. Priority 3

Continuité des Mots

Découpe sur les espaces pour éviter de couper les mots, préservant la lisibilité.

spacePriority 4

Tampon Contextuel

Appliqué à chaque découpe pour assurer la fluidité du contexte entre les chunks.

overlapSafety Net

# MarkdownTextSplitter

Découpeur spécialisé pour Markdown qui respecte la structure du document : en-têtes, blocs de code et listes. Parfait pour la documentation où maintenir la hiérarchie et les exemples de code est crucial.

import { MarkdownTextSplitter } from '@orka-js/tools';
 
const splitter = new MarkdownTextSplitter({
  chunkSize: 1000,
  chunkOverlap: 200
});
 
const markdown = `
## Introduction
 
Ceci est un paragraphe...
 
### Sous-section
 
Plus de contenu ici...
 
\`\`\`typescript
const code = 'exemple';
\`\`\`
`;
 
 
More content here...
 
\`\`\`typescript
const code = `exemple`;
\`\`\`
`;
 
const chunks = splitter.split(markdown);
// Découpe aux en-têtes, préservant la structure

Sectionnement H2

Préserve les sections majeures. Idéal pour la cohérence thématique de haut niveau.

\n## Priority 1

Sous-sectionnement H3

Maintient les sous-thèmes ensemble pour des explications détaillées contextuelles.

\n### Priority 2

Intégrité des Blocs Code

Garantit que les snippets et leur syntaxe restent indivis pour une interprétation fidèle.

\n```\nPriority 3

Ruptures Thématiques

Utilise les lignes horizontales comme frontières naturelles entre concepts logiques.

\n---\nPriority 4

Flux de Paragraphes

L'unité de sens standard. Repli quand les structures plus larges dépassent les limites.

\n\nPriority 5

# CodeTextSplitter

Découpeur conscient du langage qui respecte la structure du code : classes, fonctions et blocs. Utilise des séparateurs spécifiques au langage pour découper aux frontières naturelles comme les définitions de fonctions, déclarations de classes et instructions d'import.

import { CodeTextSplitter } from '@orka-js/tools';
 
const splitter = new CodeTextSplitter({
  language: 'typescript',  // or 'python', 'javascript', 'java', etc.
  chunkSize: 1000,
  chunkOverlap: 200
});
 
const code = `
export class MyClass {
  constructor() {}
 
  method1() {
    // implementation
  }
 
  method2() {
    // implementation
  }
}
 
export function helperFunction() {
  // implementation
}
`;
 
const chunks = splitter.split(code);
// Découpe aux frontières de classes/fonctions

Écosystème Web

Compréhension profonde des structures TS/JS, classes et fonctions fléchées.

*.ts, *.jsFull Support

Backend & Systèmes

Respecte l'indentation Python et les patterns Go pour éviter la fragmentation logique.

*.py, *.goNative Parsing

Langages Bas-Niveau

Optimisé pour Rust et C++, préservant l'intégrité des macros et des blocs.

*.rs, *.cppMemory Safe

Logique Entreprise

Gère les structures Java verbeuses et les décorateurs sans rompre le contexte.

*.javaStrict Structure

Styles Déclaratifs

Préserve l'imbrication HTML et les blocs CSS pour une analyse fidèle du layout.

*.html, *.cssTag Awareness

# TokenTextSplitter

Découpe le texte en fonction du nombre de tokens estimé, utile pour rester dans les limites de contexte du LLM. Utilise une estimation du ratio caractères-tokens (défaut : 4 caractères par token pour l'anglais) pour garantir que les chunks respectent les contraintes du modèle.

import { TokenTextSplitter } from '@orka-js/tools';
 
const splitter = new TokenTextSplitter({
  chunkSize: 500,                    // Tokens cibles par chunk
  chunkOverlap: 50,                  // Chevauchement en tokens
  estimatedTokensPerChar: 0.25       // ~4 caractères par token (anglais)
});
 
const text = `Document long...`;
const chunks = splitter.split(text);
 
// Chaque chunk fait environ 500 tokens

⚠️ Estimation de Tokens

Ce découpeur utilise une estimation basée sur les caractères. Pour un comptage précis des tokens, considérez l'utilisation d'une bibliothèque de tokenisation comme tiktoken ou gpt-tokenizer.

Comparaison

Découpeur	Idéal Pour	Préserve
RecursiveCharacter	Texte général, articles, livres	Paragraphes, phrases
Markdown	Documentation, READMEs	En-têtes, blocs de code
Code	Fichiers de code source	Classes, fonctions
Token	Limites de contexte LLM	Limites de tokens

Exemple Complet

Voici un pipeline complet montrant comment charger, découper et indexer des documents :

import { createOrka } from '@orka-js/core';
import { MarkdownLoader, RecursiveCharacterTextSplitter } from '@orka-js/tools';
 
const orka = createOrka({ /* config */ });
 
// 1. Charger les documents
const loader = new MarkdownLoader('./docs/guide.md');
const documents = await loader.load();
 
// 2. Découper en chunks
const splitter = new RecursiveCharacterTextSplitter({
  chunkSize: 1000,
  chunkOverlap: 200
});
const chunks = splitter.splitDocuments(documents);
 
// 3. Créer la base de connaissances
await orka.knowledge.create({
  name: 'documentation',
  source: chunks.map(c => ({
    text: c.content,
    metadata: c.metadata
  }))
});
 
// 4. Interroger
const result = await orka.ask({
  knowledge: 'documentation',
  question: 'How do I configure Orka AI?'
});

Imports Tree-shakeable

Importez uniquement ce dont vous avez besoin pour minimiser la taille du bundle :

// ✅ Importez uniquement ce dont vous avez besoin
import { RecursiveCharacterTextSplitter } from '@orka-js/tools';
import { MarkdownTextSplitter } from '@orka-js/tools';
 
// ✅ Ou importez depuis l'index
import { RecursiveCharacterTextSplitter, CodeTextSplitter } from '@orka-js/tools';