Conhecimento

Integração RAG com processamento de documentos e busca vetorial Aprenda os padrões de configuração, as APIs e os exemplos práticos necessários para criar...

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:

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

Adicionando Documentos

Adicionar Conteúdo de Texto

Adicione conteúdo diretamente como uma string:

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

Adicionar a Partir de Arquivo

Adicione conteúdo de tipos de arquivo suportados:

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

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: $\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(\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:

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

$\vec{A}$ é o vetor de embedding da consulta
$\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:

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

Gerenciando o Knowledge

Métodos Disponíveis

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

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

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

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:

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:

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:

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:

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:

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

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:

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

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

Última atualização: 6 de julho de 2026

Nesta seção

Introdução

Framework de agentes de IA open-source para construir sistemas autônomos que resolvem tarefas do mundo real de forma eficaz.

Instalação

Instale o Astreus com npm, yarn ou pnpm, confirme a versão necessária do Node.js e prepare um projeto local para construir agentes de IA com o framework.

Início Rápido

Construa seu primeiro agente de IA com Astreus em menos de 2 minutos Aprenda os padrões de configuração, as APIs e os exemplos práticos necessários para...

Agente

Entidade central de IA com capacidades modulares e composição baseada em decorators Aprenda os padrões de configuração, as APIs e os exemplos práticos...

Agendador

LLM