RAG Система

⚠️ ВНИМАНИЕ: Данный проект предназначен ТОЛЬКО для демонстрации и просмотра.

Лицензия: Proprietary - All Rights Reserved
Автор: Роберт Юсупов (aka turkprogrammer)
GitHub: https://github.com/turkprogrammer

ЗАПРЕЩЕНО: Использование, копирование, модификация или распространение кода без письменного разрешения автора.
РАЗРЕШЕНО: Просмотр и изучение архитектуры для образовательных целей.

Подробности см. в файле LICENSE.

---

Простая система Retrieval-Augmented Generation (RAG) с чистой архитектурой, использующая внешнее AI API и SQLite базу данных.

Архитектура

Система реализована по принципам чистой архитектуры:

• Domain: Содержит бизнес-сущности и интерфейсы
• Application: Содержит бизнес-логику (сервисы)
• Infrastructure: Содержит реализации интерфейсов (база данных, API клиент)

Зависимости

• github.com/jmoiron/sqlx - для работы с SQLite
• github.com/mattn/go-sqlite3 - драйвер SQLite
• gopkg.in/yaml.v3 - для парсинга YAML конфигурации
• github.com/rs/zerolog - для логирования (опционально)
• github.com/stretchr/testify - для тестирования (опционально)

Установка и настройка

1. Убедитесь, что у вас установлен Go
2. Инициализируйте модули:

go mod tidy

3. Настройте конфигурацию в config/config.yaml
4. Укажите API ключ в config/config.yaml (поле ai.api_key)

ВАЖНО: API ключ указывается в config/config.yaml. Опционально можно переопределить через переменную окружения AI_API_KEY:

export AI_API_KEY="ваш_api_ключ"  # Переопределяет значение из config.yaml

Для production рекомендуется использовать secret management системы (Kubernetes Secrets, Vault, AWS Secrets Manager и т.д.).

Использование

Запуск демо-режима:

go run main.go -action=demo

Индексация документа:

go run main.go -action=index -doc=path/to/your/document.txt

Поиск с генерацией ответа:

go run main.go -action=search -query="Ваш поисковый запрос"

Параметры запуска:

• -config - путь к файлу конфигурации (по умолчанию config/config.yaml)
• -db - путь к файлу базы данных SQLite (по умолчанию ./rag_system.db)
• -action - действие: serve, index, search, demo
• -doc - путь к документу для индексации (для действия index)
• -query - поисковый запрос (для действия search)

Функциональность

• Индексация документов: Загрузка документов и разбиение на фрагменты
• Поиск: Нахождение релевантных фрагментов по поисковому запросу
• Генерация: Создание ответа на основе найденных фрагментов с использованием AI
• Хранение: Использование SQLite для хранения документов и фрагментов
• Конфигурация: Поддержка конфигурации через YAML файл и переменные окружения

Текущие ограничения поиска

Реализовано:

• ✅ FTS5 полнотекстовый поиск с автоматическим ранжированием результатов через bm25() алгоритм
• ✅ Автоматический fallback на LIKE поиск, если FTS5 недоступен в версии SQLite
• ✅ Сортировка по релевантности - результаты отсортированы по similarity (лучшие первыми)
• ✅ Нормализация similarity - значения от 0 до 1 для совместимости с threshold

Ограничения:

• Чанки фиксированы по 500 символов, без токенизации и перекрытий
• Поиск через SQLite FTS5 (если доступен) или LIKE (fallback) - текстовый поиск без семантики
• Векторизация отсутствует - нет эмбеддингов и векторного хранилища; поиск основан на текстовом совпадении
• Контекст для AI не ограничен по токенам - при больших данных возможны ошибки модели (требуется доработка)
• FTS5 не поддерживает русскую морфологию из коробки (ограниченная поддержка языков)

Структура проекта

rag-system/
├── main.go                 # Главный исполняемый файл
├── config/
│   └── config.yaml         # Файл конфигурации
├── src/
│   ├── domain/             # Доменные сущности и интерфейсы
│   │   ├── models.go
│   │   └── repository.go
│   ├── application/        # Сервисы приложения
│   │   ├── service.go
│   │   └── rag_service.go
│   └── infrastructure/     # Реализация инфраструктурных компонентов
│       ├── repository.go   # Репозиторий документов
│       └── ai/             # Клиент для работы с AI API
│           └── client.go
├── go.mod
├── go.sum
├── tests/                  # Тесты (будут добавлены)
└── docs/                   # Документация (будет добавлена)

TODO (ключевые доработки)

Выполнено ✅

• ✅ FTS5 полнотекстовый поиск - реализован с автоматическим fallback на LIKE, добавлена сортировка по similarity через bm25()
• ✅ Безопасность секретов - убраны реальные секреты из config.yaml, добавлена валидация обязательного API ключа через env
• ✅ Надежность AI клиента - добавлены ретраи с exponential backoff (429/5xx), кэширование ответов, структурированное логирование, санитаризация данных, управление ресурсами
• ✅ Улучшение тестов - удалены тривиальные тесты, улучшен MockRepository, добавлены тесты граничных случаев, ошибок и производительности

В работе / Планируется

• Ограничение размера контекста для AI - усечение по токенам/символам перед отправкой в AI, приоритизация наиболее релевантных чанков
• Векторизация и семантический поиск - переход на векторное хранилище (pgvector/Qdrant/Milvus) для семантического поиска с эмбеддингами
• Усиление валидации ввода - лимиты длины запроса/документа, допустимые пути к файлам, проверки limit/threshold
• Расширение тестов - мок HTTP сервер для AI в интеграционных тестах, более детальные тесты на разбиение чанков
• Метрики и мониторинг - добавление метрик производительности (latency, throughput, cache hit rate) и интеграция с системами мониторинга

Безопасность

Управление секретами

• API ключ указывается в config/config.yaml (поле ai.api_key)
• Опционально можно переопределить через переменную окружения AI_API_KEY (имеет приоритет)
• При отсутствии ключа в config.yaml или если указан плейсхолдер YOUR_API_KEY_HERE, система выдаст понятную ошибку при запуске
• Для production рекомендуется использовать secret management системы:
  • Kubernetes Secrets
  • HashiCorp Vault
  • AWS Secrets Manager
  • Azure Key Vault
  • Google Secret Manager

Другие меры безопасности

• Все ошибки обрабатываются корректно
• Ввод пользователя валидируется (требуется доработка - см. TODO)

Тестирование

Запуск всех тестов:

Для запуска всех тестов в проекте:

go test ./...

Для запуска модульных тестов:

go test ./tests/unit/... -v

Для запуска интеграционных тестов:

go test ./tests/integration/... -v

Типы тестов:

Модульные тесты (tests/unit/):

• ai_test.go - тесты AI клиента (конфигурация, построение промптов)
• repository_test.go - тесты репозитория с реальной SQLite БД
• service_test.go - тесты с mock репозиторием
• edge_cases_test.go - тесты граничных случаев:
  • Пустые документы
  • Очень большие документы (>100KB)
  • Специальные символы в запросах и содержимом
  • Unicode символы (кириллица, китайский, японский, эмодзи)
  • Пустые запросы
  • Отрицательные и нулевые лимиты
  • Высокие threshold значения
• ai_error_handling_test.go - тесты обработки ошибок AI:
  • Таймауты
  • HTTP 429 (rate limit)
  • HTTP 500 (серверные ошибки)
  • Сетевые ошибки
  • Невалидный JSON
  • Пустые ответы
• performance_test.go - тесты производительности:
  • Индексация больших документов (1MB+)
  • Индексация множества документов (100+)
  • Поиск в большой БД (200+ документов)
  • Параллельная индексация
  • Используйте -short флаг для пропуска тестов производительности

Интеграционные тесты (tests/integration/):

• full_flow_test.go - тесты полного потока RAG системы
  • TestFullRAGFlow - полный цикл индексации, поиска и генерации ответа
  • TestMultipleDocumentsFlow - тесты с несколькими документами
• file_ai_test.go - тест с реальным файлом через AI
  • TestFileWithAI - читает test_doc.txt, индексирует, ищет и генерирует ответ через AI
  • Требует установленный AI_API_KEY (пропускается, если не установлен)

Запуск тестов производительности:

# Все тесты включая производительность
go test ./tests/unit/... -v

# Без тестов производительности (быстрее)
go test ./tests/unit/... -short

Результаты тестов

Результаты модульных тестов:

✅ Все модульные тесты проходят успешно

=== RUN   TestAIClientInitialization
--- PASS: TestAIClientInitialization (0.00s)

=== RUN   TestBuildPrompt
--- PASS: TestBuildPrompt (0.00s)

=== RUN   TestSQLiteRepository
--- PASS: TestSQLiteRepository (0.02s)

=== RUN   TestSQLiteRepositoryWithMultipleDocuments
--- PASS: TestSQLiteRepositoryWithMultipleDocuments (0.04s)

=== RUN   TestMockRepository
--- PASS: TestMockRepository (0.00s)

=== RUN   TestEmptyDocument
--- PASS: TestEmptyDocument (0.00s)

=== RUN   TestVeryLargeDocument
--- PASS: TestVeryLargeDocument (0.13s)
    performance_test.go:45: Индексация 1MB документа заняла: 117.110797ms

=== RUN   TestSpecialCharactersInQuery
--- PASS: TestSpecialCharactersInQuery (0.01s)

=== RUN   TestUnicodeCharacters
--- PASS: TestUnicodeCharacters (0.01s)

=== RUN   TestIndexingPerformance
--- PASS: TestIndexingPerformance (0.13s)

=== RUN   TestIndexingMultipleDocuments
--- PASS: TestIndexingMultipleDocuments (0.33s)
    performance_test.go:82: Индексация 100 документов заняла: 319.908985ms

=== RUN   TestSearchPerformance
--- PASS: TestSearchPerformance (0.14s)

=== RUN   TestConcurrentIndexing
--- PASS: TestConcurrentIndexing (0.23s)
    performance_test.go:203: Параллельная индексация 20 документов заняла: 217.118241ms

PASS
ok  	rag-system/tests/unit	2.413s

Результаты интеграционных тестов:

✅ Все интеграционные тесты проходят успешно

=== RUN   TestFileWithAI
[AI] Загружена конфигурация: base_url=https://api.intelligence.io.solutions/api/v1, model=Intel/Qwen3-Coder-480B-A35B-Instruct-int4-mixed-ar
[AI] Финальная конфигурация: base_url=https://api.intelligence.io.solutions/api/v1, model=Intel/Qwen3-Coder-480B-A35B-Instruct-int4-mixed-ar
    file_ai_test.go:63: AI клиент успешно инициализирован из config.yaml
--- PASS: TestFileWithAI/Search_компания (0.00s)
--- PASS: TestFileWithAI/Search_2020 (0.00s)
--- PASS: TestFileWithAI/AI_Generation (0.00s)
    file_ai_test.go:208: AI успешно сгенерировал ответ на основе test_doc.txt: Компания была основана в 2020 году.
--- PASS: TestFileWithAI/SearchAndGenerate (0.00s)
    file_ai_test.go:224: Полный цикл RAG с test_doc.txt успешен. Ответ: В компании работает более 100 сотрудников.
--- PASS: TestFileWithAI (0.02s)

=== RUN   TestFullRAGFlow
--- PASS: TestFullRAGFlow (0.00s)

=== RUN   TestMultipleDocumentsFlow
--- PASS: TestMultipleDocumentsFlow (0.00s)

PASS
ok  	rag-system/tests/integration	0.036s

Результаты запуска демо-режима:

=== Демонстрация RAG системы ===
База данных уже содержит 3 документов
Тестовые документы успешно проиндексированы!

Запрос: Когда была основана компания?
Найдено 1 релевантных фрагментов
Фрагменты:
  1. [Similarity: 0.50] Наша компания была основана в 2020 году. Мы специализиру...
Ответ: Компания была основана в 2020 году.

Запрос: Какие продукты предлагает компания?
Найдено 1 релевантных фрагментов
Фрагменты:
  1. [Similarity: 0.25] Мы предлагаем широкий спектр решений: веб-приложения, ...
Ответ: Компания предлагает веб-приложения, мобильные приложения, системы анализа данных и искусственного интеллекта.

Запрос: Где находится главный офис?
Найдено 1 релевантных фрагментов
Фрагменты:
  1. [Similarity: 0.50] Главный офис находится в Москве. Адрес: улица Тверская,...
Ответ: Главный офис находится в Москве.

Итоговая статистика тестирования:

✅ Все тесты проходят успешно:

• Модульные тесты: ✅ PASS (2.413s)
• Интеграционные тесты: ✅ PASS (0.449s)
• Тесты производительности: ✅ PASS
• Тесты граничных случаев: ✅ PASS
• Тесты обработки ошибок: ✅ PASS

✅ Демо-режим работает корректно:

• Индексация документов в SQLite базу данных ✅
• Поиск релевантных фрагментов по запросу ✅
• Генерация осмысленных ответов с использованием внешнего AI API ✅
• Кэширование ответов AI для повышения производительности ✅
• Автоматические ретраи при ошибках API (429/5xx) ✅

Система готова к использованию и полностью функциональна.