Temel Arayüzler

SmartRAG'ın temel arayüzleri ve servisleri.

IDocumentService

Belge işlemleri için ana servis arayüzü.

public interface IDocumentService
{
    Task<Document> UploadDocumentAsync(IFormFile file);
    Task<Document> GetDocumentByIdAsync(string id);
    Task<IEnumerable<Document>> GetAllDocumentsAsync();
    Task<bool> DeleteDocumentAsync(string id);
    Task<IEnumerable<DocumentChunk>> SearchDocumentsAsync(string query, int maxResults = 5);
    Task<RagResponse> GenerateRagAnswerAsync(string query, int maxResults = 5);
}

IDocumentParserService

Farklı dosya formatlarını ayrıştırmak için servis.

public interface IDocumentParserService
{
    Task<string> ParseDocumentAsync(IFormFile file);
    bool CanParse(string fileName);
    Task<IEnumerable<string>> ChunkTextAsync(string text, int chunkSize = 1000, int overlap = 200);
}

IDocumentSearchService

Belge arama ve RAG işlemleri için servis.

public interface IDocumentSearchService
{
    Task<List<DocumentChunk>> SearchDocumentsAsync(string query, int maxResults = 5);
    Task<RagResponse> GenerateRagAnswerAsync(string query, int maxResults = 5);
}

IAIService

AI sağlayıcıları ile etkileşim için servis.

public interface IAIService
{
    Task<float[]> GenerateEmbeddingAsync(string text);
    Task<string> GenerateTextAsync(string prompt);
    Task<string> GenerateTextAsync(string prompt, string context);
}

Modeller

SmartRAG'da kullanılan temel veri modelleri.

Document

public class Document
{
    public string Id { get; set; }
    public string FileName { get; set; }
    public string Content { get; set; }
    public string ContentType { get; set; }
    public long FileSize { get; set; }
    public DateTime UploadedAt { get; set; }
    public List<DocumentChunk> Chunks { get; set; }
}

DocumentChunk

public class DocumentChunk
{
    public string Id { get; set; }
    public string DocumentId { get; set; }
    public string Content { get; set; }
    public float[] Embedding { get; set; }
    public int ChunkIndex { get; set; }
    public DateTime CreatedAt { get; set; }
}

RagResponse

public class RagResponse
{
    public string Answer { get; set; }
    public List<SearchSource> Sources { get; set; }
    public DateTime SearchedAt { get; set; }
    public RagConfiguration Configuration { get; set; }
}

SearchSource

public class SearchSource
{
    public string DocumentId { get; set; }
    public string DocumentName { get; set; }
    public string Content { get; set; }
    public float SimilarityScore { get; set; }
    public int ChunkIndex { get; set; }
}

Enumlar

SmartRAG'da kullanılan enum değerleri.

AIProvider

public enum AIProvider
{
    OpenAI,
    Anthropic,
    Gemini,
    AzureOpenAI,
    Custom
}

StorageProvider

public enum StorageProvider
{
    Qdrant,
    Redis,
    SQLite,
    InMemory,
    FileSystem
}

RetryPolicy

public enum RetryPolicy
{
    None,
    FixedDelay,
    ExponentialBackoff,
    LinearBackoff
}

Servis Kaydı

SmartRAG servislerini uygulamanıza nasıl kaydedeceğiniz.

Temel Kayıt

// Program.cs veya Startup.cs
services.AddSmartRAG(configuration, options =>
{
    options.AIProvider = AIProvider.Anthropic;
    options.StorageProvider = StorageProvider.Qdrant;
    options.MaxChunkSize = 1000;
    options.ChunkOverlap = 200;
    options.MaxRetryAttempts = 3;
    options.RetryDelayMs = 1000;
    options.RetryPolicy = RetryPolicy.ExponentialBackoff;
});

Gelişmiş Konfigürasyon

services.AddSmartRAG(configuration, options =>
{
    options.AIProvider = AIProvider.OpenAI;
    options.StorageProvider = StorageProvider.Redis;
    options.MaxChunkSize = 1500;
    options.MinChunkSize = 100;
    options.ChunkOverlap = 300;
    options.MaxRetryAttempts = 5;
    options.RetryDelayMs = 2000;
    options.RetryPolicy = RetryPolicy.ExponentialBackoff;
    options.EnableFallbackProviders = true;
    options.FallbackProviders = new List<AIProvider> 
    { 
        AIProvider.Anthropic, 
        AIProvider.Gemini 
    };
});

Kullanım Örnekleri

SmartRAG API'sini nasıl kullanacağınız.

Belge Yükleme

[HttpPost("upload")]
public async Task<ActionResult<Document>> UploadDocument(IFormFile file)
{
    try
    {
        var document = await _documentService.UploadDocumentAsync(file);
        return Ok(document);
    }
    catch (Exception ex)
    {
        return BadRequest(ex.Message);
    }
}

Belge Arama

[HttpGet("search")]
public async Task<ActionResult<IEnumerable<DocumentChunk>>> SearchDocuments(
    [FromQuery] string query, 
    [FromQuery] int maxResults = 10)
{
    try
    {
        var results = await _documentService.SearchDocumentsAsync(query, maxResults);
        return Ok(results);
    }
    catch (Exception ex)
    {
        return BadRequest(ex.Message);
    }
}

RAG Yanıt Üretme

[HttpPost("ask")]
public async Task<ActionResult<RagResponse>> AskQuestion([FromBody] string question)
{
    try
    {
        var response = await _documentService.GenerateRagAnswerAsync(question, 5);
        return Ok(response);
    }
    catch (Exception ex)
    {
        return BadRequest(ex.Message);
    }
}

Hata Yönetimi

SmartRAG'da hata yönetimi ve istisna türleri.

Önemli

Tüm SmartRAG servisleri uygun hata yönetimi ile tasarlanmıştır. API çağrılarınızı try-catch blokları ile sarmalayın.

Yaygın Hatalar

ArgumentException: Geçersiz parametreler
FileNotFoundException: Dosya bulunamadı
UnauthorizedAccessException: API anahtarı geçersiz
HttpRequestException: Ağ bağlantı sorunları
TimeoutException: İstek zaman aşımı

Hata Yönetimi Örneği

try
{
    var document = await _documentService.UploadDocumentAsync(file);
    return Ok(document);
}
catch (ArgumentException ex)
{
    _logger.LogWarning("Invalid argument: {Message}", ex.Message);
    return BadRequest("Invalid file or parameters");
}
catch (UnauthorizedAccessException ex)
{
    _logger.LogError("Authentication failed: {Message}", ex.Message);
    return Unauthorized("Invalid API key");
}
catch (HttpRequestException ex)
{
    _logger.LogError("Network error: {Message}", ex.Message);
    return StatusCode(503, "Service temporarily unavailable");
}
catch (Exception ex)
{
    _logger.LogError(ex, "Unexpected error occurred");
    return StatusCode(500, "Internal server error");
}

Loglama

SmartRAG'da loglama ve izleme.

Log Seviyeleri

Information: Normal işlemler
Warning: Uyarılar ve beklenmeyen durumlar
Error: Hatalar ve istisnalar
Debug: Detaylı hata ayıklama bilgileri

Loglama Konfigürasyonu

// appsettings.json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "SmartRAG": "Debug",
      "Microsoft": "Warning"
    }
  }
}

Performans Değerlendirmeleri

SmartRAG'da performans optimizasyonu.

Önerilen Ayarlar

Chunk Size: 1000-1500 karakter
Chunk Overlap: 200-300 karakter
Max Results: 5-10 sonuç
Retry Attempts: 3-5 deneme

Performans İpuçları

Büyük dosyaları önceden işleyin
Uygun chunk boyutları kullanın
Cache mekanizmalarını etkinleştirin
Asenkron işlemleri tercih edin

Yardıma mı ihtiyacınız var?

API ile ilgili sorularınız için:

API Referansı