Chargeurs de Documents

Chargez des données depuis diverses sources : PDF, CSV, JSON, Markdown, fichiers texte et dossiers.

Vue d'ensemble

Les chargeurs de documents transforment les données brutes de différentes sources en un format Document unifié qu'Orka AI peut traiter. Chaque chargeur gère des types de fichiers spécifiques et une logique d'extraction.

Qu'est-ce qu'un Document ?

Tous les loaders retournent un tableau d'objets Document avec cette structure :

interface Document {
  id: string;              // Unique identifier
  content: string;         // The actual text content
  metadata: {
    source?: string;       // File path or URL
    loader?: string;       // Loader name
    ...customFields        // Your custom metadata
  };
}

# TextLoader

Charge des fichiers texte brut avec support d'encodage personnalisé. Le loader le plus simple — lit un fichier et retourne son contenu comme un seul document.

import { TextLoader } from 'orkajs/loaders/text';
 
const loader = new TextLoader('./document.txt', {
  encoding: 'utf-8',
  metadata: { source: 'documentation' }
});
 
const documents = await loader.load();
// [{ id: '...', content: '...', metadata: { source: 'documentation', loader: 'TextLoader' } }]

Paramètres du Constructeur

path: string

Chemin absolu ou relatif vers le fichier texte.

options.encoding?: string

Encodage de caractères (défaut : 'utf-8'). Supporte 'utf-8', 'ascii', 'latin1', etc.

options.metadata?: Record<string, unknown>

Métadonnées personnalisées à attacher au document. Utile pour la catégorisation, le filtrage ou le suivi.

# CSVLoader

Parse des fichiers CSV avec support de séparateurs personnalisés, sélection de colonnes et extraction de contenu. Chaque ligne devient un document séparé, ce qui le rend parfait pour charger des données structurées comme des catalogues de produits, des listes d'utilisateurs ou des bases de FAQ.

import { CSVLoader } from 'orkajs/loaders/csv';
 
// Option 1: Use specific column as content
const loader = new CSVLoader('./data.csv', {
  separator: ',',
  contentColumn: 'description',  // Use this column as document content
  metadata: { type: 'product_data' }
});
 
// Option 2: Combine multiple columns
const loader2 = new CSVLoader('./users.csv', {
  columns: ['name', 'bio', 'interests'],  // Combine these columns
});
 
const documents = await loader.load();
// Each row becomes a separate document

💡 Fonctionnalités CSV

✅ Gère les champs entre guillemets avec virgules
✅ Séparateurs personnalisés (virgule, point-virgule, tabulation)
✅ Extraction automatique de métadonnées depuis les colonnes

# JSONLoader

Charge des fichiers JSON ou objets avec support JSONPath pour l'extraction de données imbriquées. Gère à la fois les objets uniques et les tableaux, avec un mapping flexible des champs pour le contenu et les métadonnées.

import { JSONLoader } from 'orkajs/loaders/json';
 
// Load from file
const loader = new JSONLoader('./data.json', {
  contentField: 'text',           // Use this field as content
  metadataFields: ['author', 'date'],  // Extract these as metadata
  jsonPath: '$.articles'          // Extract nested array
});
 
// Load from object
const data = [
  { text: 'Article 1', author: 'Alice' },
  { text: 'Article 2', author: 'Bob' }
];
const loader2 = new JSONLoader(data, {
  contentField: 'text'
});
 
const documents = await loader.load();

# MarkdownLoader

Charge des fichiers Markdown avec extraction du frontmatter et parsing des en-têtes. Parfait pour la documentation, les articles de blog ou tout contenu avec des métadonnées frontmatter YAML.

import { MarkdownLoader } from 'orkajs/loaders/markdown';
 
const loader = new MarkdownLoader('./README.md', {
  removeFrontmatter: true,   // Extract YAML frontmatter
  includeHeaders: true,      // Extract all headers as metadata
  metadata: { type: 'documentation' }
});
 
const documents = await loader.load();
// Frontmatter fields are added to metadata
// Headers are available in metadata.headers

Exemple Markdown avec Frontmatter

---
title: Getting Started
author: Alice
date: 2024-01-15
---
 
# Introduction
 
This is the content...

# PDFLoader

Extrait le texte des fichiers PDF avec sélection de pages et extraction de métadonnées. Chaque page devient un document séparé avec suivi du numéro de page, idéal pour les articles de recherche, rapports ou manuels.

📦 Installation Requise

PDFLoader nécessite le package pdf-parse :

npm install pdf-parse

import { PDFLoader } from 'orkajs/loaders/pdf';
 
// Load entire PDF
const loader = new PDFLoader('./document.pdf', {
  metadata: { source: 'research_paper' }
});
 
// Load specific pages
const loader2 = new PDFLoader('./report.pdf', {
  pages: [1, 2, 3],      // Only pages 1, 2, 3
  maxPages: 10           // Or limit to first 10 pages
});
 
const documents = await loader.load();
// Each page becomes a separate document with page number in metadata

# DirectoryLoader

Charge récursivement tous les fichiers supportés d'un dossier avec détection automatique du chargeur. Le loader le plus puissant — scanne des arborescences de répertoires entières, détecte les types de fichiers et applique automatiquement le loader approprié.

import { DirectoryLoader } from 'orkajs/loaders/directory';
 
const loader = new DirectoryLoader('./docs', {
  recursive: true,                    // Scan subdirectories
  glob: '*.md',                       // Filter by pattern
  exclude: ['node_modules', '.git'],  // Exclude folders
  metadata: { project: 'orka-docs' }
});
 
const documents = await loader.load();
// Automatically detects and uses the right loader for each file type

Extension	Chargeur
`.txt`	TextLoader
`.md, .mdx`	MarkdownLoader
`.csv`	CSVLoader
`.json, .jsonl`	JSONLoader
`.ts, .js, .py, .html, .css`	TextLoader

Utilisation avec Knowledge

Les chargeurs s'intègrent parfaitement avec le système Knowledge d'Orka. Voici un pipeline complet du chargement de documents à la création d'une base de connaissances consultable :

create-knowledge-base.ts

import { createOrka } from 'orkajs';
import { DirectoryLoader } from 'orkajs/loaders/directory';
import { RecursiveCharacterTextSplitter } from 'orkajs/splitters/recursive';
 
const orka = createOrka({ /* config */ });
 
// Load documents
const loader = new DirectoryLoader('./knowledge-base');
const documents = await loader.load();
 
// Split into chunks
const splitter = new RecursiveCharacterTextSplitter({
  chunkSize: 1000,
  chunkOverlap: 200
});
const chunks = splitter.splitDocuments(documents);
 
// Create knowledge base
await orka.knowledge.create({
  name: 'my-knowledge',
  source: documents.map(d => ({ text: d.content, metadata: d.metadata }))
});

Imports Tree-shakeable

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

// ❌ Imports everything
import { CSVLoader, PDFLoader } from 'orkajs';
 
// ✅ Tree-shakeable - only bundles CSVLoader
import { CSVLoader } from 'orkajs/loaders/csv';
 
// ✅ Import all loaders from index
import { CSVLoader, PDFLoader, JSONLoader } from 'orkajs/loaders';