Knowledge base

Integrazione RAG con elaborazione dei documenti e ricerca vettoriale Scopri i pattern di configurazione, le API e gli esempi pratici necessari per creare...

Integrazione RAG con elaborazione dei documenti e ricerca vettoriale

Panoramica

Il sistema Knowledge fornisce capacità di retrieval-augmented generation (RAG), permettendo agli agent di accedere e utilizzare documenti esterni nelle loro risposte. Elabora automaticamente i documenti, crea embedding vettoriali e abilita la ricerca semantica per le informazioni rilevanti. Gli agent con knowledge possono fornire risposte più accurate e contestuali basate sui tuoi documenti.

Abilitare la Knowledge

Abilita la knowledge per un agent impostando l'opzione knowledge su 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
});

Aggiungere documenti

Aggiungi contenuto testuale

Aggiungi contenuto direttamente come stringa:

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

Aggiungi da file

Aggiungi contenuto da tipi di file supportati:

// 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');

Aggiungi da directory

Elabora tutti i file supportati in una directory:

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

Tipi di file supportati

File di testo: .txt, .md, .json
File PDF: .pdf (con estrazione del testo)

Come funziona

Il sistema knowledge segue una pipeline di elaborazione sofisticata:

Elaborazione dei documenti

I documenti vengono memorizzati e indicizzati nel database knowledge con i relativi metadati.

Suddivisione del testo in chunk

Il contenuto viene suddiviso in chunk (1500 caratteri con 300 caratteri di sovrapposizione) per un recupero ottimale.

La sovrapposizione garantisce la continuità del contesto: $\text{overlap ratio} = \frac{300}{1500} = 0.2 = 20\%$

Questo impedisce che informazioni importanti vengano suddivise tra i confini dei chunk.

Embedding vettoriali

Ogni chunk viene convertito in embedding vettoriali usando i modelli di embedding di OpenAI, Gemini o Ollama.

Dimensioni di embedding comuni:

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

Può essere usata anche la distanza euclidea tra i vettori: $d(\vec{p}, \vec{q}) = \sqrt{\sum_{i=1}^{n}(p_i - q_i)^2}$

Ricerca semantica

Quando gli agent ricevono query, i chunk rilevanti vengono recuperati usando la ricerca per similarità coseno.

La similarità tra i vettori della query e del documento viene calcolata usando:

$\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}}$

Dove:

$\vec{A}$ è il vettore di embedding della query
$\vec{B}$ è il vettore di embedding del chunk del documento
Valori più alti (vicini a 1) indicano una maggiore similarità

Integrazione nel contesto

Le informazioni recuperate vengono aggiunte automaticamente al contesto dell'agent per risposte migliori.

Esempio di utilizzo

Ecco un esempio completo di utilizzo della knowledge con 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}`);
});

Gestire la Knowledge

Metodi disponibili

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

Configurazione

Variabili d'ambiente

# 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

Configurazione del modello di Embedding

Specifica il modello di embedding direttamente nella configurazione dell'agent:

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

Tipi di risposta

Capire le risposte dei metodi knowledge ti aiuta a lavorare con i dati in modo efficace.

Risposta di Add Knowledge

Aggiungere knowledge restituisce l'UUID del documento creato:

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)

Risposta di Search Knowledge

La ricerca restituisce un array di chunk con contenuto, metadati e punteggi di 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
  }
]

Risposta di Get Knowledge Context

Il recupero del contesto restituisce una stringa concatenata di chunk rilevanti:

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..."

Risposta di Get Knowledge Documents

Elencare i documenti restituisce i metadati di tutti i documenti memorizzati:

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"
  }
]

Risposta di Expand Knowledge Context

L'espansione del contesto restituisce un array di stringhe di chunk:

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..."
]

Risposte di eliminazione

Le operazioni di eliminazione restituiscono booleani che indicano il successo:

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

Risposta di Clear Knowledge

Cancellare tutta la knowledge restituisce void (nessun valore di ritorno):

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

Risposta delle operazioni sui file

Le operazioni knowledge basate su file restituiscono void in caso di successo o generano un'eccezione in caso di errore:

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

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

Ultimo aggiornamento: 6 luglio 2026

In questa sezione

Introduzione

Framework AI agent open-source per costruire sistemi autonomi che risolvono in modo efficace problemi del mondo reale.

Installazione

Installa Astreus con npm, yarn o pnpm, verifica la versione richiesta di Node.js e prepara un progetto locale per costruire agenti AI con il framework.

Avvio rapido

Costruisci il tuo primo agente AI con Astreus in meno di 2 minuti Scopri i pattern di configurazione, le API e gli esempi pratici necessari per creare...

Agente

Entità AI centrale con funzionalità modulari e composizione basata su decoratori Scopri i pattern di configurazione, le API e gli esempi pratici necessari...

Pianificatore

LLM