API-Referenz
Vollständige API-Dokumentation für SmartRAG mit Beispielen und Verwendungsmustern
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: