Connaissances

Intégration RAG avec traitement de documents et recherche vectorielle Découvrez les schémas de configuration, les API et les exemples pratiques nécessaires...

Intégration RAG avec traitement de documents et recherche vectorielle

Vue d'ensemble

Le système Knowledge offre des capacités de génération augmentée par récupération (RAG), permettant aux agents d'accéder à des documents externes et de les utiliser dans leurs réponses. Il traite automatiquement les documents, crée des embeddings vectoriels, et permet une recherche sémantique d'informations pertinentes. Les agents dotés de connaissances peuvent fournir des réponses plus précises et contextuelles basées sur vos documents.

Activer Knowledge

Activez les connaissances pour un agent en définissant l'option knowledge sur true :

import { Agent } from '@astreus-ai/astreus';

const agent = await Agent.create({
  name: 'KnowledgeAgent',
  model: 'gpt-4o',
  knowledge: true,  // Enable knowledge base access (default: false)
  embeddingModel: 'text-embedding-3-small' // Optional: specify embedding model
});

Ajouter des documents

Ajouter du contenu texte

Ajoutez du contenu directement sous forme de chaîne de caractères :

await agent.addKnowledge(
  'Your important content here',
  'Document Title',
  { category: 'documentation' }
);

Ajouter depuis un fichier

Ajoutez du contenu à partir de types de fichiers pris en charge :

// Add PDF file
await agent.addKnowledgeFromFile(
  '/path/to/document.pdf',
  { source: 'manual', version: '1.0' }
);

// Add text file
await agent.addKnowledgeFromFile('/path/to/notes.txt');

Ajouter depuis un dossier

Traitez tous les fichiers pris en charge d'un dossier :

await agent.addKnowledgeFromDirectory(
  '/path/to/docs',
  { project: 'documentation' }
);

Types de fichiers pris en charge

Fichiers texte : .txt, .md, .json
Fichiers PDF : .pdf (avec extraction de texte)

Fonctionnement

Le système Knowledge suit un pipeline de traitement sophistiqué :

Traitement des documents

Les documents sont stockés et indexés dans la base de connaissances avec des métadonnées.

Découpage du texte

Le contenu est découpé en fragments (1500 caractères avec 300 caractères de chevauchement) pour une récupération optimale.

Le chevauchement garantit la continuité du contexte : $\text{overlap ratio} = \frac{300}{1500} = 0.2 = 20\%$

Cela évite que des informations importantes ne soient coupées entre les limites de fragments.

Embeddings vectoriels

Chaque fragment est converti en embeddings vectoriels à l'aide des modèles d'embedding OpenAI, Gemini, ou Ollama.

Dimensions d'embedding courantes :

text-embedding-3-small : 1536 dimensions (OpenAI)
text-embedding-3-large : 3072 dimensions (OpenAI)
text-embedding-ada-002 : 1536 dimensions (OpenAI)
text-embedding-004 : 768 dimensions (Gemini)

La distance euclidienne entre vecteurs peut également être utilisée : $d(\vec{p}, \vec{q}) = \sqrt{\sum_{i=1}^{n}(p_i - q_i)^2}$

Recherche sémantique

Lorsque les agents reçoivent des requêtes, les fragments pertinents sont récupérés grâce à une recherche par similarité cosinus.

La similarité entre les vecteurs de la requête et du document est calculée avec :

$\text{cosine similarity} = \cos(\theta) = \frac{\vec{A} \cdot \vec{B}}{||\vec{A}|| \cdot ||\vec{B}||} = \frac{\sum_{i=1}^{n} A_i B_i}{\sqrt{\sum_{i=1}^{n} A_i^2} \cdot \sqrt{\sum_{i=1}^{n} B_i^2}}$

Où :

$\vec{A}$ est le vecteur d'embedding de la requête
$\vec{B}$ est le vecteur d'embedding du fragment de document
Des valeurs plus élevées (proches de 1) indiquent une plus grande similarité

Intégration au contexte

Les informations récupérées sont automatiquement ajoutées au contexte de l'agent pour des réponses enrichies.

Exemple d'utilisation

Voici un exemple complet d'utilisation de Knowledge avec un agent :

import { Agent } from '@astreus-ai/astreus';

// Create agent with knowledge enabled
const agent = await Agent.create({
  name: 'DocumentAssistant',
  model: 'gpt-4o',
  knowledge: true,
  embeddingModel: 'text-embedding-3-small', // Optional: specify embedding model
  systemPrompt: 'You are a helpful assistant with access to company documentation.'
});

// Add documentation
await agent.addKnowledgeFromFile('./company-handbook.pdf', {
  type: 'handbook',
  department: 'hr'
});

await agent.addKnowledge(`
Our API uses REST principles with JSON responses.
Authentication is done via Bearer tokens.
Rate limiting is 1000 requests per hour.
`, 'API Documentation', {
  type: 'api-docs',
  version: '2.0'
});

// Query with automatic knowledge retrieval
const response = await agent.ask('What is our API rate limit?');
console.log(response);
// The agent will automatically search the knowledge base and include relevant context

// Manual knowledge search
const results = await agent.searchKnowledge('API authentication', 5, 0.7);
results.forEach(result => {
  console.log(`Similarity: ${result.similarity}`);
  console.log(`Content: ${result.content}`);
});

Gérer Knowledge

Méthodes disponibles

// List all documents with metadata
const documents = await agent.getKnowledgeDocuments();
// Returns: Array<{ id: string; title: string; created_at: string }>

// Delete specific document by ID (documentId is UUID string)
const success = await agent.deleteKnowledgeDocument(documentId);
// Returns: boolean indicating success

// Delete specific chunk by ID (chunkId is UUID string)
const success = await agent.deleteKnowledgeChunk(chunkId);
// Returns: boolean indicating success

// Clear all knowledge for this agent
await agent.clearKnowledge();
// Returns: void

// Search with custom parameters
const results = await agent.searchKnowledge(
  'search query',
  10,    // limit: max results (default: 5)
  0.8    // threshold: similarity threshold (0-1, default: 0.7)
);
// Returns: Array<{ content: string; metadata: MetadataObject; similarity: number }>

// Get relevant context for a query
const context = await agent.getKnowledgeContext(
  'query text',
  5      // limit: max chunks to include (default: 5)
);
// Returns: string with concatenated relevant content

// Expand context around a specific chunk
const expandedChunks = await agent.expandKnowledgeContext(
  documentId,   // Document ID (UUID string)
  chunkIndex,   // Chunk index within document
  2,            // expandBefore: chunks to include before (default: 1)
  2             // expandAfter: chunks to include after (default: 1)
);
// Returns: Array<string> with expanded chunk content

Configuration

Variables d'environnement

# Database (required)
KNOWLEDGE_DB_URL=postgresql://user:password@host:port/database

# API key for embeddings
OPENAI_API_KEY=your_openai_key
# Or use dedicated embedding keys:
OPENAI_EMBEDDING_API_KEY=your_embedding_key
OPENAI_EMBEDDING_BASE_URL=https://api.openai.com/v1  # Optional: custom endpoint for embeddings
GEMINI_API_KEY=your_gemini_key
GEMINI_EMBEDDING_API_KEY=your_gemini_embedding_key

# For Ollama embeddings (local)
OLLAMA_BASE_URL=http://localhost:11434

Configuration du modèle d'embedding

Spécifiez le modèle d'embedding directement dans la configuration de l'agent :

const agent = await Agent.create({
  name: 'KnowledgeAgent',
  model: 'gpt-4o',
  embeddingModel: 'text-embedding-3-small',  // Specify embedding model here
  knowledge: true
});

Types de réponse

Comprendre les réponses des méthodes Knowledge vous aide à travailler efficacement avec les données.

Réponse Add Knowledge

Ajouter des connaissances retourne l'UUID du document créé :

const documentId = await agent.addKnowledge(
  "TypeScript is a typed superset of JavaScript...",
  "TypeScript Overview",
  { source: "documentation", version: "5.0" }
);

// Response: "550e8400-e29b-41d4-a716-446655440000" (UUID string)

Réponse Search Knowledge

La recherche retourne un tableau de fragments avec contenu, métadonnées et scores de similarité :

const results = await agent.searchKnowledge("TypeScript types", 5, 0.7);

// Response structure:
[
  {
    content: "TypeScript provides static typing which helps catch errors at compile time...",
    metadata: {
      title: "TypeScript Overview",
      source: "documentation",
      version: "5.0"
    },
    similarity: 0.95
  },
  {
    content: "Types in TypeScript include primitives like string, number, boolean...",
    metadata: {
      title: "Type System",
      source: "tutorial"
    },
    similarity: 0.87
  },
  {
    content: "Advanced types like generics and conditional types provide powerful abstractions...",
    metadata: {
      title: "Advanced Types",
      source: "documentation"
    },
    similarity: 0.79
  }
]

Réponse Get Knowledge Context

La récupération de contexte retourne une chaîne concaténée de fragments pertinents :

const context = await agent.getKnowledgeContext("TypeScript", 3);

// Response: concatenated string with separator
"TypeScript is a typed superset of JavaScript...\n\n---\n\nTypes help catch errors at compile time...\n\n---\n\nAdvanced types provide powerful abstractions..."

Réponse Get Knowledge Documents

Lister les documents retourne les métadonnées de tous les documents stockés :

const documents = await agent.getKnowledgeDocuments();

// Response structure:
[
  {
    id: "doc-uuid-1",                      // UUID string
    title: "TypeScript Overview",
    created_at: "2024-01-15T10:30:00Z"    // ISO 8601 timestamp
  },
  {
    id: "doc-uuid-2",
    title: "Advanced Types",
    created_at: "2024-01-16T14:20:00Z"
  },
  {
    id: "doc-uuid-3",
    title: "Best Practices",
    created_at: "2024-01-17T09:15:00Z"
  }
]

Réponse Expand Knowledge Context

L'expansion de contexte retourne un tableau de fragments :

const chunks = await agent.expandKnowledgeContext("doc-uuid", 5, 2, 2);

// Response structure (plain chunk content):
[
  "Earlier context before the target chunk...",
  "More context leading to the target...",
  "This is the target chunk with the main content...",
  "Following context after the target...",
  "Additional context for full understanding..."
]

Réponses Delete

Les opérations de suppression retournent des booléens indiquant le succès :

// Delete specific document
const docDeleted = await agent.deleteKnowledgeDocument("doc-uuid");
// Returns: true or false

// Delete specific chunk
const chunkDeleted = await agent.deleteKnowledgeChunk("chunk-uuid");
// Returns: true or false

Réponse Clear Knowledge

Effacer toutes les connaissances ne retourne rien (void) :

await agent.clearKnowledge();
// Returns: void (undefined)

Réponse des opérations sur fichiers

Les opérations de connaissances basées sur des fichiers ne retournent rien en cas de succès, ou lèvent une erreur en cas d'échec :

// Add from file
await agent.addKnowledgeFromFile('./document.pdf', { source: 'manual' });
// Returns: void

// Add from directory
await agent.addKnowledgeFromDirectory('./docs', { project: 'main' });
// Returns: void

Dernière mise à jour : 6 juillet 2026

Dans cette section

Introduction

Framework d'agent IA open-source pour construire des systèmes autonomes qui résolvent efficacement des tâches concrètes.

Installation

Installez Astreus avec npm, yarn ou pnpm, vérifiez la version requise de Node.js, et préparez un projet local pour créer des agents IA avec le framework.

Démarrage rapide

Créez votre premier agent IA avec Astreus en moins de 2 minutes Découvrez les schémas de configuration, les API et les exemples pratiques nécessaires pour...

Agent

Entité IA centrale avec des capacités modulaires et une composition basée sur des décorateurs

Planificateur

LLM