Base de conocimiento

Integración RAG con procesamiento de documentos y búsqueda vectorial Aprende los patrones de configuración, las APIs y los ejemplos prácticos necesarios...

Integración RAG con procesamiento de documentos y búsqueda vectorial

Descripción general

El sistema Knowledge ofrece capacidades de generación aumentada por recuperación (RAG), permitiendo que los agentes accedan a documentos externos y los utilicen en sus respuestas. Procesa automáticamente los documentos, crea embeddings vectoriales y habilita la búsqueda semántica de información relevante. Los agentes con conocimiento pueden ofrecer respuestas más precisas y contextuales basadas en tus documentos.

Habilitar el conocimiento

Habilita el conocimiento para un agente estableciendo la opción knowledge en 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
});

Añadir documentos

Añadir contenido de texto

Añade contenido directamente como una cadena de texto:

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

Añadir desde un archivo

Añade contenido desde tipos de archivo soportados:

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

Añadir desde un directorio

Procesa todos los archivos soportados en un directorio:

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

Tipos de archivo soportados

Archivos de texto: .txt, .md, .json
Archivos PDF: .pdf (con extracción de texto)

Cómo funciona

El sistema de conocimiento sigue un sofisticado pipeline de procesamiento:

Procesamiento de documentos

Los documentos se almacenan e indexan en la base de datos de conocimiento junto con sus metadatos.

Fragmentación de texto

El contenido se divide en fragmentos (1500 caracteres con 300 caracteres de solapamiento) para una recuperación óptima.

El solapamiento garantiza la continuidad del contexto: $\text{overlap ratio} = \frac{300}{1500} = 0.2 = 20\%$

Esto evita que información importante quede dividida entre los límites de los fragmentos.

Embeddings vectoriales

Cada fragmento se convierte en embeddings vectoriales utilizando modelos de embedding de OpenAI, Gemini u Ollama.

Dimensiones habituales de embedding:

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

También puede usarse la distancia euclídea entre vectores: $d(\vec{p}, \vec{q}) = \sqrt{\sum_{i=1}^{n}(p_i - q_i)^2}$

Búsqueda semántica

Cuando los agentes reciben consultas, los fragmentos relevantes se recuperan mediante búsqueda por similitud coseno.

La similitud entre los vectores de la consulta y del documento se calcula mediante:

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

Donde:

$\vec{A}$ es el vector de embedding de la consulta
$\vec{B}$ es el vector de embedding del fragmento del documento
Valores más altos (más cercanos a 1) indican mayor similitud

Integración de contexto

La información recuperada se añade automáticamente al contexto del agente para mejorar sus respuestas.

Ejemplo de uso

Aquí tienes un ejemplo completo de uso del conocimiento con un agente:

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}`);
});

Gestión del conocimiento

Métodos 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

Configuración

Variables de entorno

# 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

Configuración del modelo de embedding

Especifica el modelo de embedding directamente en la configuración del agente:

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

Tipos de respuesta

Entender las respuestas de los métodos de conocimiento te ayuda a trabajar con los datos de forma eficaz.

Respuesta de añadir conocimiento

Añadir conocimiento devuelve el UUID del documento creado:

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)

Respuesta de búsqueda de conocimiento

La búsqueda devuelve un array de fragmentos con contenido, metadatos y puntuaciones de similitud:

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

Respuesta de obtención de contexto de conocimiento

La recuperación de contexto devuelve una cadena concatenada de fragmentos relevantes:

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

Respuesta de obtención de documentos de conocimiento

Listar documentos devuelve los metadatos de todos los documentos almacenados:

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

Respuesta de expansión de contexto de conocimiento

La expansión de contexto devuelve un array de cadenas de fragmentos:

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

Respuestas de eliminación

Las operaciones de eliminación devuelven booleanos que indican éxito:

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

Respuesta de limpieza de conocimiento

Limpiar todo el conocimiento devuelve void (sin valor de retorno):

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

Respuesta de operaciones con archivos

Las operaciones de conocimiento basadas en archivos devuelven void en caso de éxito o lanzan un error:

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

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

Última actualización: 6 de julio de 2026

En esta sección

Introducción

Framework de agentes de IA de código abierto para construir sistemas autónomos que resuelven tareas del mundo real de forma eficaz.

Instalación

Instala Astreus con npm, yarn o pnpm, confirma la versión de Node.js requerida y prepara un proyecto local para construir agentes de IA con el framework.

Inicio rápido

Construye tu primer agente de IA con Astreus en menos de 2 minutos Aprende los patrones de configuración, las APIs y los ejemplos prácticos necesarios para...

Agente

Entidad de IA principal con capacidades modulares y composición basada en decoradores Aprende los patrones de configuración, las APIs y los ejemplos...

Planificador

LLM