Bilgi

Doküman işleme ve vektör aramayla RAG entegrasyonu Güvenilir Astreus agent sistemleri oluşturmak için gereken kurulum kalıplarını, API'leri ve pratik...

Doküman işleme ve vektör aramayla RAG entegrasyonu

Genel Bakış

Bilgi (Knowledge) sistemi, ajanların yanıtlarında harici dokümanlara erişip bunları kullanmasına olanak tanıyan getirim destekli üretim (RAG) yetenekleri sağlar. Dokümanları otomatik olarak işler, vektör gömmeleri (embedding) oluşturur ve ilgili bilgiler için anlamsal aramayı mümkün kılar. Bilgiye sahip ajanlar, dokümanlarınıza dayanarak daha doğru ve bağlamsal yanıtlar verebilir.

Bilgiyi Etkinleştirme

Bir ajan için knowledge seçeneğini true olarak ayarlayarak bilgiyi etkinleştirin:

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

Doküman Ekleme

Metin İçeriği Ekleyin

İçeriği doğrudan bir string olarak ekleyin:

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

Dosyadan Ekleyin

Desteklenen dosya türlerinden içerik ekleyin:

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

Dizinden Ekleyin

Bir dizindeki tüm desteklenen dosyaları işleyin:

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

Desteklenen Dosya Türleri

Metin dosyaları: .txt, .md, .json
PDF dosyaları: .pdf (metin çıkarımıyla)

Nasıl Çalışır

Bilgi sistemi sofistike bir işlem hattını takip eder:

Doküman İşleme

Dokümanlar, meta veriyle birlikte bilgi veritabanında saklanır ve indekslenir.

Metin Parçalama

İçerik, optimal getirim için parçalara bölünür (300 karakter örtüşmeli 1500 karakter).

Örtüşme, bağlam sürekliliğini garanti eder: $\text{overlap ratio} = \frac{300}{1500} = 0.2 = 20\%$

Bu, önemli bilgilerin parça sınırları arasında bölünmesini önler.

Vektör Gömmeleri

Her parça, OpenAI, Gemini veya Ollama gömme modelleri kullanılarak vektör gömmelerine dönüştürülür.

Yaygın gömme boyutları:

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

Vektörler arasındaki Öklid mesafesi de kullanılabilir: $d(\vec{p}, \vec{q}) = \sqrt{\sum_{i=1}^{n}(p_i - q_i)^2}$

Anlamsal Arama

Ajanlar sorgu aldığında, ilgili parçalar kosinüs benzerlik araması kullanılarak getirilir.

Sorgu ve doküman vektörleri arasındaki benzerlik şu şekilde hesaplanır:

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

Burada:

$\vec{A}$ sorgu gömme vektörüdür
$\vec{B}$ doküman parçası gömme vektörüdür
Daha yüksek değerler (1'e daha yakın) daha fazla benzerlik gösterir

Bağlam Entegrasyonu

Getirilen bilgi, geliştirilmiş yanıtlar için otomatik olarak ajanın bağlamına eklenir.

Örnek Kullanım

Bir ajanla bilgi kullanımının eksiksiz bir örneği:

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

Bilgiyi Yönetme

Kullanılabilir Metodlar

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

Yapılandırma

Ortam Değişkenleri

# 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

Gömme Modeli Yapılandırması

Gömme modelini doğrudan ajan yapılandırmasında belirtin:

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

Yanıt Tipleri

Bilgi metodlarının yanıtlarını anlamak, verilerle etkili biçimde çalışmanıza yardımcı olur.

Bilgi Ekleme Yanıtı

Bilgi eklemek, oluşturulan dokümanın UUID'sini döndürür:

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)

Bilgi Arama Yanıtı

Arama, içerik, meta veri ve benzerlik skorlarına sahip parçalardan oluşan bir dizi döndürür:

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

Bilgi Bağlamı Alma Yanıtı

Bağlam getirme, ilgili parçaların birleştirilmiş bir string'ini döndürür:

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

Bilgi Dokümanlarını Alma Yanıtı

Dokümanları listelemek, saklanan tüm dokümanlar için meta veri döndürür:

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

Bilgi Bağlamını Genişletme Yanıtı

Bağlam genişletme, parça string'lerinden oluşan bir dizi döndürür:

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

Silme Yanıtları

Silme işlemleri, başarıyı gösteren boolean değerler döndürür:

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

Bilgiyi Temizleme Yanıtı

Tüm bilgiyi temizlemek void döndürür (dönüş değeri yok):

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

Dosya İşlemleri Yanıtı

Dosya tabanlı bilgi işlemleri, başarı durumunda void döndürür veya hatada fırlatır:

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

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

Son güncelleme: 6 Temmuz 2026

Bu bölümde

Giriş

Gerçek dünya görevlerini etkili biçimde çözen otonom sistemler kurmak için açık kaynaklı AI ajan framework'ü.

Kurulum

Astreus'u npm, yarn veya pnpm ile kurun, gerekli Node.js sürümünü doğrulayın ve framework ile AI ajanları oluşturmak için yerel bir proje hazırlayın.

Hızlı Başlangıç

2 dakikadan kısa sürede Astreus ile ilk AI ajanınızı oluşturun Güvenilir Astreus agent sistemleri oluşturmak için gereken kurulum kalıplarını, API'leri ve...

Ajan

Modüler yetenekler ve decorator tabanlı kompozisyona sahip temel AI varlığı Güvenilir Astreus agent sistemleri oluşturmak için gereken kurulum kalıplarını,...

Zamanlayıcı

LLM