Kern-Interfaces

Die grundlegenden Interfaces und Services von SmartRAG.

IDocumentService

Hauptservice-Interface für Dokumentoperationen.

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

Service zum Parsen verschiedener Dateiformate.

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

Service für Dokumentensuche und RAG-Operationen.

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

IAIService

Service für die Interaktion mit AI-Providern.

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

Modelle

Die grundlegenden Datenmodelle, die in SmartRAG verwendet werden.

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

Enums

Die in SmartRAG verwendeten Enum-Werte.

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
}

Service-Registrierung

Wie Sie SmartRAG-Services in Ihrer Anwendung registrieren.

Grundlegende Registrierung

// Program.cs oder 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;
});

Erweiterte Konfiguration

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

Verwendungsbeispiele

Wie Sie die SmartRAG-API verwenden.

Dokument hochladen

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

Dokumente suchen

[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-Antwort generieren

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

Fehlerbehandlung

Fehlerbehandlung und Ausnahmetypen in SmartRAG.

Wichtig

Alle SmartRAG-Services sind mit angemessener Fehlerbehandlung entworfen. Wickeln Sie Ihre API-Aufrufe in try-catch-Blöcke ein.

Häufige Fehler

ArgumentException: Ungültige Parameter
FileNotFoundException: Datei nicht gefunden
UnauthorizedAccessException: Ungültiger API-Schlüssel
HttpRequestException: Netzwerkverbindungsprobleme
TimeoutException: Anforderungs-Timeout

Fehlerbehandlungsbeispiel

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

Protokollierung

Protokollierung und Überwachung in SmartRAG.

Protokollstufen

Information: Normale Operationen
Warning: Warnungen und unerwartete Situationen
Error: Fehler und Ausnahmen
Debug: Detaillierte Debugging-Informationen

Protokollierungskonfiguration

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

Leistungsüberlegungen

Leistungsoptimierung in SmartRAG.

Empfohlene Einstellungen

Chunk Size: 1000-1500 Zeichen
Chunk Overlap: 200-300 Zeichen
Max Results: 5-10 Ergebnisse
Retry Attempts: 3-5 Versuche

Leistungstipps

Verarbeiten Sie große Dateien im Voraus
Verwenden Sie angemessene Chunk-Größen
Aktivieren Sie Cache-Mechanismen
Bevorzugen Sie asynchrone Operationen

Benötigen Sie Hilfe?

Für Fragen zur API:

API-Referenz