Knowledge & RAG

Indexez des documents, effectuez des recherches sémantiques et construisez des pipelines RAG avecOrka JS.

Pourquoi Knowledge ?

L'API orka.knowledge ou Knowledge suit la philosophie de conception intent-based d'Orka. Au lieu de manipuler des concepts bas niveau comme les vecteurs, embeddings ou collections, vous travaillez avec une abstraction haut niveau appelée "knowledge" (connaissances).

Abstraction

Masque la complexité : découpage, génération d'embeddings, stockage et recherche sémantique sont automatisés.

API Fluide

Des méthodes naturelles : create(), search(). Votre code devient une lecture fluide et intuitive.

Configurable

Changez de VectorDB (Memory, Pinecone, Qdrant,...) instantanément sans modifier votre logique métier.

Cohérent

Suit le pattern universel Orka sur tous les modules : ask(), workflow(), agent() et knowledge().

Ce Qui Se Passe Sous le Capot

Quand vous appelez orka.knowledge.create(), Orka exécute un pipeline sophistiqué d'opérations :

Normalisation de la Source

Conversion de vos sources (texte, fichiers, URLs) en format Document[] uniforme avec IDs et métadonnées.

Découpage Intelligent

Découpage en morceaux avec chevauchement (overlap) pour préserver le contexte sémantique aux frontières.

Génération des Embeddings

Chaque chunk est transformé en vecteur de haute dimension capturant le sens sémantique profond.

Stockage Vectoriel

Création de la collection et insertion par lots (batches de 100) dans votre base de données vectorielle.

Référence API

`create(options)`

Crée une nouvelle base de connaissances à partir de vos documents sources. C'est le point d'entrée principal pour indexer du contenu.

const result = await orka.knowledge.create({
  name: 'my-docs',           // Requis : nom unique pour cette base de connaissances 
  source: [...],             // Requis : contenu à indexer (voir formats ci-dessous)
  chunkSize: 1000,           // Optionnel : nombre maximum de caractères par chunk (par défaut: 1000)
  chunkOverlap: 200,         // Optionnel : chevauchement entre les chunks (par défaut: 200)
  metadata: {                // Optionnel : métadonnées attachées à tous les documents
    category: 'support',
    version: '1.0',
  },
});
 
// Returns:
// {
//   name: 'my-docs',
//   documentCount: 5,      // Nombre de documents sources traités
//   chunkCount: 23,        // Total de chunks créés
// }

Comprendre Chunk Size & Overlap

chunkSize détermine combien de texte chaque vecteur représente. Petits chunks = récupération plus précise mais moins de contexte. Grands chunks = plus de contexte mais peuvent inclure des infos non pertinentes. chunkOverlap garantit que les informations importantes aux frontières des chunks ne sont pas perdues.

Formats de Source

Orka accepte plusieurs formats de source, détectant et traitant automatiquement chaque type :

Document Unique

Découpage automatique pour les contenus longs. Parfait pour les articles ou saisies manuelles.

STRING

await orka.knowledge.create({
  name: 'article',
  source: 'This is a very long article about AI...',
});

Tableau de Chaînes

Traite chaque élément du tableau comme une entrée indépendante avant le sous-découpage.

ARRAY<STR>

await orka.knowledge.create({
  name: 'faq',
  source: [
    'How do I reset my password? ...',
    'How do I contact support? ...'
  ],
});

Objets Structurés

Préserve les métadonnées par document pour le filtrage RAG avancé et les résultats.

OBJECTS

await orka.knowledge.create({
  name: 'products',
  source: [
    { text: 'iPhone 15...', metadata: { brand: 'Apple' } },
  ],
});

Système de Fichiers

Chargement récursif des .txt, .md, .json, etc. Idéal pour les dossiers de doc locaux.

FS_PATH

// Directory or Single File
await orka.knowledge.create({
  name: 'docs',
  source: { path: './documentation/' },
});

URL Distante

Récupération sécurisée avec validation, timeout de 30s et limite de 50MB.

HTTP_HTTPS

await orka.knowledge.create({
  name: 'web-source',
  source: { url: 'https://example.com/api' },
});

Référence API

`add(name, source, options?)`

Ajoute plus de documents à une base de connaissances existante. Utilise les mêmes formats de source que create().

// Ajoute de nouveaux documents à une base de connaissances existante
const { addedChunks } = await orka.knowledge.add('my-docs', [
  'New document content...',
  'Another new document...',
], {
  chunkSize: 1000,
  chunkOverlap: 200,
  metadata: { addedAt: '2024-01-15' },
});
 
console.log('Added ' + addedChunks + ' new chunks');

`search(name, query, options?)`

Effectue une recherche sémantique sur une base de connaissances. Retourne les chunks les plus pertinents basés sur la similarité vectorielle.

const results = await orka.knowledge.search('my-docs', 'how to reset password', {
  topK: 10,         // Nombre de résultats à retourner (par défaut: 5)
  minScore: 0.7,    // Score de similarité minimum 0-1 (optionnel)
});
 
// Each result contains:
for (const result of results) {
  console.log(result.id);        // ID unique du chunk
  console.log(result.content);   // Le texte du chunk
  console.log(result.score);     // Score de similarité (0-1, plus haut = plus pertinent)
  console.log(result.metadata);  // { documentId, chunkIndex, ...vos métadonnées }
}

Comment Fonctionne la Recherche Sémantique

Votre requête est convertie en vecteur d'embedding, puis comparée à tous les vecteurs stockés via la similarité cosinus. Cela trouve du contenu sémantiquement similaire même si les mots exacts ne correspondent pas. "reset password" correspondra à "changer mes identifiants" car ils ont un sens similaire.

`delete(name)`

Supprime une base de connaissances entière et tous ses vecteurs de la VectorDB.

await orka.knowledge.delete('my-docs');

Comment le RAG Fonctionne avec orka.ask()

RAG (Retrieval-Augmented Generation) combine votre base de connaissances avec la génération LLM. Quand vous appelez orka.ask() avec un paramètre knowledge, voici le flux complet :

Question Utilisateur→Embed Requête→Recherche Vectorielle→Top-K Chunks→Construire Prompt→LLM→Réponse

// Basic RAG query
const result = await orka.ask({
  question: 'How do I reset my password?',
  knowledge: 'my-docs',    // Nom de votre base de connaissances
  topK: 5,                 // Nombre de chunks à récupérer
});
console.log(result.answer);
 
// With context inspection (for debugging)
const { answer, context } = await orka.ask({
  question: 'How do I reset my password?',
  knowledge: 'my-docs',    // Nom de votre base de connaissances
  topK: 5,                 // Nombre de chunks à récupérer
  includeContext: true,    // Retourne les chunks utilisés
});
 
console.log('Réponse:', answer);
console.log('Sources utilisées:');
for (const chunk of context) {
  console.log('- [' + chunk.score.toFixed(2) + '] ' + chunk.content.slice(0, 100) + '...');
}

Exemple Complet

Voici un exemple complet montrant comment construire un système de Q&A sur de la documentation :

knowledge-qa-example.ts

import { Orka } from '@orka-js/core';
import { OpenAIAdapter } from '@orka-js/openai';
import { MemoryVectorAdapter } from '@orka-js/memory';
 
// 1. Initialiser Orka avec des adaptateurs 
const orka = new Orka({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY }),
  vectorDB: new MemoryVectorAdapter(),
  defaults: {
    chunkSize: 800,      // Plus petits chunks pour une récupération précise
    chunkOverlap: 100,   // Chevauchement entre les chunks pour la continuité du contexte
    topK: 3,             // Nombre de chunks à récupérer
  },
});
 
// 2. Créer une base de connaissances à partir de vos documents
const { chunkCount } = await orka.knowledge.create({
  name: 'product-docs',
  source: { path: './docs/' },
  metadata: { source: 'official-docs' },
});
console.log('Indexed ' + chunkCount + ' chunks');
 
// 3. Ajouter plus de contenu plus tard
await orka.knowledge.add('product-docs', [
  { text: 'New feature: Dark mode is now available...', metadata: { type: 'release-note' } },
]);
 
// 4. Requête avec RAG
const { answer, context } = await orka.ask({
  question: 'How do I enable dark mode?',
  knowledge: 'product-docs',
  includeContext: true,
});
 
console.log('Réponse:', answer);
console.log('Basé sur', context.length, sources);
 
// 5. Recherche directe (sans LLM)
const results = await orka.knowledge.search('product-docs', 'dark mode', { topK: 5 });
for (const r of results) {
  console.log('[' + r.score.toFixed(2) + '] ' + r.content.slice(0, 80) + '...');
}

Conseils Pro

💡 Choisir la bonne taille de chunk

Pour Q&A : 500-1000 caractères. Pour résumé : 1500-2000 caractères. Pour code : 300-500 caractères. Expérimentez pour trouver ce qui fonctionne le mieux pour votre contenu.

💡 Utiliser les métadonnées pour filtrer

Ajoutez des métadonnées de catégorie, date, auteur ou type. Cela permet des recherches filtrées et aide à tracer quels documents ont contribué aux réponses.

💡 Déboguer avec includeContext

Utilisez toujours includeContext: true pendant le développement. Cela montre exactement quels chunks le LLM a utilisés, inestimable pour ajuster votre pipeline RAG.

💡 Considérer minScore

Définissez minScore (ex: 0.7) pour filtrer les résultats peu pertinents. Cela évite que le LLM soit confus par du contexte non pertinent.

Adaptateurs VectorDB Supportés

orka.knowledge fonctionne avec n'importe quel adaptateur VectorDB. Changez d'adaptateur sans modifier votre code applicatif :

Adaptateur	Vitesse	Évolutivité	Configuration
Memory	Ultra-Fast	Low	Zero-Config
Pinecone	Fast	Infinite	API Key
Qdrant	Fast	High	Docker / Cloud
Chroma	Moderate	Medium	Easy

MemoryVectorAdapter

local

En mémoire, parfait pour le développement et les tests.

PineconeAdapter

cloud

Base vectorielle cloud managée, scale à des milliards.

QdrantAdapter

hybrid

Haute performance, auto-hébergé ou cloud-native.

ChromaAdapter

embedded

Open-source, architecture embarquée ou client-serveur.

// Développement: en mémoire
import { MemoryVectorAdapter } from '@orka-js/memory';
const vectorDB = new MemoryVectorAdapter();
 
// Production: Pinecone
import { PineconeAdapter } from '@orka-js/pinecone';
const vectorDB = new PineconeAdapter({
  apiKey: process.env.PINECONE_API_KEY,
  environment: 'us-east-1',
  indexName: 'my-index',
});
 
// La même API orka.knowledge fonctionne avec les deux!