Conhecimento

Integração RAG com processamento de documentos e busca vetorial

Visão Geral#

O sistema Knowledge (Conhecimento) fornece capacidades de geração aumentada por recuperação (RAG), permitindo que os agentes acessem e utilizem documentos externos em suas respostas. Ele processa documentos automaticamente, cria embeddings vetoriais e permite busca semântica por informações relevantes. Agentes com conhecimento podem fornecer respostas mais precisas e contextuais com base em seus documentos.

Habilitando o Knowledge#

Habilite o conhecimento para um agente definindo a opção knowledge como 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
});

Adicionando Documentos#

Adicionar Conteúdo de Texto#

Adicione conteúdo diretamente como uma string:

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

Adicionar a Partir de Arquivo#

Adicione conteúdo de tipos de arquivo suportados:

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

Adicionar a Partir de Diretório#

Processe todos os arquivos suportados em um diretório:

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

Tipos de Arquivo Suportados#

  • Arquivos de texto: .txt, .md, .json
  • Arquivos PDF: .pdf (com extração de texto)

Como Funciona#

O sistema de conhecimento segue um pipeline de processamento sofisticado:

Processamento de Documentos#

Documentos são armazenados e indexados no banco de dados de conhecimento com metadados.

Fragmentação de Texto#

O conteúdo é dividido em fragmentos (1500 caracteres com sobreposição de 300 caracteres) para recuperação ideal.

A sobreposição garante continuidade do contexto: overlap ratio=3001500=0.2=20%\text{overlap ratio} = \frac{300}{1500} = 0.2 = 20\%

Isso evita que informações importantes sejam divididas entre os limites dos fragmentos.

Embeddings Vetoriais#

Cada fragmento é convertido em embeddings vetoriais usando modelos de embedding da OpenAI, Gemini ou Ollama.

Dimensões comuns de embedding:

  • text-embedding-3-small: 1536 dimensões (OpenAI)
  • text-embedding-3-large: 3072 dimensões (OpenAI)
  • text-embedding-ada-002: 1536 dimensões (OpenAI)
  • text-embedding-004: 768 dimensões (Gemini)

A distância euclidiana entre vetores também pode ser usada: d(p⃗,q⃗)=∑i=1n(pi−qi)2d(\vec{p}, \vec{q}) = \sqrt{\sum_{i=1}^{n}(p_i - q_i)^2}

Busca Semântica#

Quando os agentes recebem consultas, os fragmentos relevantes são recuperados usando busca por similaridade de cosseno.

A similaridade entre os vetores de consulta e documento é calculada usando:

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

Onde:

  • A⃗\vec{A} é o vetor de embedding da consulta
  • B⃗\vec{B} é o vetor de embedding do fragmento do documento
  • Valores mais altos (mais próximos de 1) indicam maior similaridade

Integração de Contexto#

As informações recuperadas são adicionadas automaticamente ao contexto do agente para respostas aprimoradas.

Exemplo de Uso#

Aqui está um exemplo completo de uso do conhecimento com um 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}`);
});

Gerenciando o Knowledge#

Métodos Disponíveis#

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

Configuração#

Variáveis de Ambiente#

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

Configuração do Modelo de Embedding#

Especifique o modelo de embedding diretamente na configuração do 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 Resposta#

Entender as respostas dos métodos de conhecimento ajuda a trabalhar com os dados de forma eficaz.

Resposta de Adição de Conhecimento#

Adicionar conhecimento retorna o UUID do documento criado:

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)

Resposta de Busca de Conhecimento#

A busca retorna um array de fragmentos com conteúdo, metadados e pontuações de similaridade:

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

Resposta de Obtenção de Contexto de Conhecimento#

A recuperação de contexto retorna uma string 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..."

Resposta de Documentos de Conhecimento#

Listar documentos retorna metadados de todos os documentos armazenados:

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

Resposta de Expansão de Contexto de Conhecimento#

A expansão de contexto retorna um array de strings 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..."
]

Respostas de Exclusão#

Operações de exclusão retornam booleanos indicando sucesso:

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

Resposta de Limpeza de Conhecimento#

Limpar todo o conhecimento retorna void (sem valor de retorno):

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

Resposta de Operações com Arquivos#

Operações de conhecimento baseadas em arquivo retornam void em caso de sucesso ou lançam um erro em caso de falha:

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

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