Base de conocimiento

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:

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

const agent = await Agent.create({
  name: 'KnowledgeAgent',
  model: 'gpt-6-astra',
  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:

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

Añadir desde un archivo#

Añade contenido desde tipos de archivo soportados:

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

typescript
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: overlap ratio=3001500=0.2=20%\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(p⃗,q⃗)=∑i=1n(pi−qi)2d(\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:

cosine similarity=cos⁡(θ)=A⃗⋅B⃗∣∣A⃗∣∣⋅∣∣B⃗∣∣=∑i=1nAiBi∑i=1nAi2⋅∑i=1nBi2\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:

  • A⃗\vec{A} es el vector de embedding de la consulta
  • B⃗\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:

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

// Create agent with knowledge enabled
const agent = await Agent.create({
  name: 'DocumentAssistant',
  model: 'gpt-6-astra',
  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#

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

bash
# 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:

typescript
const agent = await Agent.create({
  name: 'KnowledgeAgent',
  model: 'gpt-6-astra',
  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:

typescript
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:

typescript
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:

typescript
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:

typescript
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:

typescript
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:

typescript
// 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):

typescript
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:

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

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