Основные интерфейсы

Основные интерфейсы и сервисы SmartRAG.

IDocumentService

Основной интерфейс сервиса для операций с документами.

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

Сервис для парсинга различных форматов файлов.

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

Сервис для поиска документов и RAG операций.

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

IAIService

Сервис для взаимодействия с AI провайдерами.

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

Модели

Основные модели данных, используемые в SmartRAG.

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

Перечисления

Значения перечислений, используемые в SmartRAG.

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
}

Регистрация сервисов

Как зарегистрировать SmartRAG сервисы в вашем приложении.

Базовая регистрация

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

Расширенная конфигурация

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

Примеры использования

Как использовать SmartRAG API.

Загрузка документа

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

Поиск документов

[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 ответа

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

Обработка ошибок

Обработка ошибок и типы исключений в SmartRAG.

Важно

Все сервисы SmartRAG разработаны с надлежащей обработкой ошибок. Оберните ваши API вызовы в try-catch блоки.

Частые ошибки

ArgumentException: Неверные параметры
FileNotFoundException: Файл не найден
UnauthorizedAccessException: Неверный API ключ
HttpRequestException: Проблемы с сетевым подключением
TimeoutException: Таймаут запроса

Пример обработки ошибок

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

Логирование

Логирование и мониторинг в SmartRAG.

Уровни логирования

Information: Обычные операции
Warning: Предупреждения и неожиданные ситуации
Error: Ошибки и исключения
Debug: Подробная отладочная информация

Конфигурация логирования

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

Соображения производительности

Оптимизация производительности в SmartRAG.

Советы по производительности

Обрабатывайте большие файлы заранее
Используйте подходящие размеры чанков
Включайте механизмы кэширования
Предпочитайте асинхронные операции

Нужна помощь?

По вопросам API:

Справочник API