Описание архитектуры программного обеспечения Ассистент ПРО
Компоненты системы RAG для реестра программного обеспечения
1. Общая информация о программном обеспечении
1.1. Наименование программного обеспечения
RAG-система (Retrieval-Augmented Generation) — система интеллектуального поиска и генерации ответов на основе векторных эмбеддингов и больших языковых моделей.
1.2. Объем компьютерной программы
1.2.1. Статистика исходного кода
- Общее количество файлов исходного кода: 161 файл
- Общее количество строк кода: ~89,409 строк (суммарно)
- Распределение по типам файлов:
- Python файлы (*.py): ~59,522 строк (основной объем, ~66.6%)
- JavaScript/TypeScript файлы (*.js, *.ts): ~20,372 строк (админ-панель и виджет, ~22.8%)
- HTML файлы (*.html): ~4,885 строк (~5.5%)
- CSS файлы (*.css): ~4,630 строк (~5.2%)
- Конфигурационные файлы (YAML, TOML, JSON): ~500+ строк
1.2.2. Структура кодовой базы
- Основные модули Python: 12 модулей
- Веб-интерфейсы: 2 (админ-панель, виджет)
- Интеграции: 2 (Bitrix24, почта)
- Боты: 2 (Telegram, VK)
- Сервисы: 8 основных сервисов
2. Языки программирования
2.1. Основные языки
2.1.1. Python
- Версия: Python 3.10 - 3.12 (требование: >=3.10,<3.13)
- Использование:
- Backend API (FastAPI)
- Обработка документов и векторизация
- Интеграция с LLM
- Фоновые задачи (Celery workers)
- Боты для мессенджеров
- Процент кодовой базы: ~66.6% (~59,522 строк, основной язык)
2.1.2. JavaScript / TypeScript
- Версия: ES6+ (современный JavaScript)
- Использование:
- Админ-панель (SPA)
- Виджет чата для встраивания
- Клиентская логика веб-интерфейсов
- Процент кодовой базы: ~22.8% (~20,372 строк)
2.1.3. HTML/CSS
- Использование:
- Разметка веб-интерфейсов
- Стилизация компонентов
- Процент кодовой базы: ~10.7% (~9,515 строк: HTML ~4,885, CSS ~4,630)
2.2. Языки разметки и конфигурации
- YAML: Docker Compose конфигурации
- TOML: Конфигурация проекта (pyproject.toml)
- JSON: Конфигурации пакетов, метаданные
3. Системы управления базами данных (СУБД)
3.1. MongoDB
- Версия: MongoDB 8.0
- Назначение:
- Хранение документов и метаданных
- История диалогов и сессий
- Конфигурация проектов (мультитенантность)
- Пользовательские данные
- Хранение бинарных файлов через GridFS
- Драйверы:
- pymongo>=4.13.2 (синхронный)
- motor>=3.7.1 (асинхронный)
- Коллекции:
- projects — конфигурация проектов
- documents — метаданные документов
- conversations — история диалогов
- reading_pages — страницы для режима чтения
- GridFS buckets для бинарных файлов
3.2. Redis
- Версия: Redis 5.0+ (образ: bitnami/redis:latest)
- Назначение:
- Кэширование результатов поиска
- Брокер сообщений для Celery
- Хранение временных данных (сессии, отчеты краулера)
- Rate limiting
- Библиотека: redis>=5.0.4
- Использование:
- Кэш векторных поисков (TTL: 86400 секунд)
- Очередь задач Celery
- Хранение состояния краулера
3.3. Qdrant
- Версия: Qdrant latest (векторная база данных)
- Назначение:
- Хранение векторных эмбеддингов документов
- Семантический поиск (dense vector search)
- BM25 полнотекстовый поиск
- Гибридный поиск (RRF - Reciprocal Rank Fusion)
- Библиотека: qdrant-client>=1.9.0
- Порты:
- HTTP: 6333 (по умолчанию)
- gRPC: 6334 (по умолчанию)
- Параметры векторов:
- Размерность: определяется моделью эмбеддингов
- Метрика расстояния: COSINE (косинусное расстояние)
- Индексы: payload индексы для текста и проектов
4. Фреймворки и библиотеки
4.1. Backend фреймворки
4.1.1. FastAPI
- Версия: fastapi>=0.115.14
- Назначение: Асинхронный веб-фреймворк для REST API
- Дополнительные компоненты:
- fastapi-cli>=0.0.7
- uvicorn[standard]>=0.35.0 (ASGI сервер)
4.1.2. Celery
- Версия: celery>=5.5.3
- Назначение:
- Асинхронная обработка задач
- Планировщик периодических задач (Celery Beat)
- Обновление векторного хранилища
- Резервное копирование
- Брокер: Redis
4.2. Библиотеки для работы с LLM и эмбеддингами
4.2.1. LangChain
- Версии:
- langchain>=0.3.26
- langchain-community>=0.3.27
- langchain-huggingface>=0.1.0
- langchain-redis>=0.2.3
- Назначение: Оркестрация работы с LLM, цепочки обработки
4.2.2. Sentence Transformers
- Версия: sentence-transformers>=2.7.0
- Назначение: Генерация текстовых эмбеддингов
- Модель: deepvk/USER-bge-m3
4.2.3. PyTorch
- Версия: torch>=2.9.0
- Назначение:
- Базовый фреймворк для моделей машинного обучения
- Поддержка GPU/CPU вычислений
- Работа с эмбеддингами
4.2.4. Hugging Face Hub
- Версия: huggingface-hub>=0.33.1
- Назначение: Загрузка и управление моделями из Hugging Face
4.3. Библиотеки для обработки документов
- pypdf>=5.7.0 — обработка PDF файлов
- docx2txt>=0.9 — обработка DOCX файлов
- openpyxl>=3.1.5 — обработка Excel файлов (XLSX)
- beautifulsoup4>=4.12,<5 — парсинг HTML
- lxml>=5.2.0 — XML/HTML парсинг
- Pillow>=10.0 — обработка изображений
4.4. Библиотеки для работы с сетью
- aiohttp>=3.9.5 — асинхронные HTTP запросы
- requests>=2.32,<3 — синхронные HTTP запросы
- httpx>=0.28.1 (dev) — тестирование HTTP
4.5. Утилиты и вспомогательные библиотеки
- pydantic-settings>=2.2.1 — управление настройками
- structlog>=24.1.0 — структурированное логирование
- orjson>=3.10.18 — быстрая сериализация JSON
- python-dotenv>=1.0.1 — загрузка переменных окружения
- python-multipart>=0.0.9 — обработка multipart данных
- nltk>=3.8.1 — обработка естественного языка
- prometheus-client>=0.20.0 — метрики для мониторинга
- pynvml>=11.5.0 — мониторинг GPU (NVIDIA)
4.6. Библиотеки для ботов
- aiogram>=3.5.0 — Telegram Bot API
4.7. JavaScript/TypeScript библиотеки
4.7.1. Тестирование
- vitest>=1.6.0 — тестовый фреймворк
- @testing-library/dom>=9.3.1 — тестирование DOM
- @testing-library/user-event>=14.5.2 — симуляция пользовательских событий
- jsdom>=24.0.0 — DOM окружение для тестов
5. Модели машинного обучения и AI
5.1. Модели эмбеддингов (Embeddings)
5.1.1. Основная модель
- Название: deepvk/USER-bge-m3
- Тип: Sentence Transformer
- Назначение: Генерация векторных представлений текста
- Размерность векторов: 1024
- Устройство: CUDA (если доступно) или CPU
- Кэширование: LRU кэш на 128 запросов
5.2. Большие языковые модели (LLM)
5.2.1. Ollama Runtime
- Образ: ollama/ollama:latest
- Назначение: Локальный runtime для запуска GGUF моделей
- Поддержка кластера: Да (через backend.ollama_cluster)
5.2.2. Поддерживаемые модели
- Модель по умолчанию: yandex/YandexGPT-5-Lite-8B-instruct-GGUF:latest (4.5 GB)
- Альтернативные модели:
- mistral:7b (4.1 GB)
- llama3.1:8b (4.9 GB)
- qwen2.5:14b (8.6 GB)
- phi3:mini (2.7 GB)
5.2.3. Интеграция с внешними LLM
- Поддержка внешних API через backend.llm_client
- Интеграция с YaLLM (Yandex LLM API)
6. Инфраструктура и контейнеризация
6.1. Docker
- Базовый образ: python:3.10-slim
- Multi-stage сборка: Да (build + runtime stages)
- Кэширование:
- APT кэш
- UV кэш для зависимостей
- Hugging Face кэш для моделей
6.2. Docker Compose
- Файлы конфигурации:
- compose.yaml — основная конфигурация
- compose.override.yaml — локальные переопределения
- compose.gpu.yaml — конфигурация для GPU
- Сервисы:
- app — FastAPI приложение
- celery_worker — воркер для фоновых задач
- celery_beat — планировщик задач
- mongo — MongoDB
- redis — Redis
- qdrant — Qdrant векторная БД
- ollama — Ollama runtime (опционально)
- telegram-bot — Telegram бот
6.3. Системные зависимости
- Build stage:
- build-essential — компилятор и инструменты сборки
- git — система контроля версий
- cmake — система сборки
- ninja-build — система сборки
- pkg-config — конфигурация пакетов
- curl — HTTP клиент
- libopenblas-dev — библиотеки для линейной алгебры
- python3-dev — заголовки Python
- Runtime stage:
- libopenblas0-pthread — рантайм библиотеки OpenBLAS
- curl — для healthcheck
- ca-certificates — SSL сертификаты
- MongoDB Database Tools — для резервного копирования
7. Архитектурные компоненты
7.1. RAG Pipeline (Retrieval-Augmented Generation)
7.1.1. Компоненты поиска
1. Векторный поиск (Dense Search)
- Генерация эмбеддинга запроса
- Поиск похожих векторов в Qdrant
- Кэширование результатов в Redis
2. BM25 поиск (Sparse Search)
- Полнотекстовый поиск по ключевым словам
- Реализован в Qdrant
3. Reciprocal Rank Fusion (RRF)
- Объединение результатов векторного и BM25 поиска
- Константа RRF: 60
- Сортировка по итоговому score
4. Reranking (опционально)
- Переранжирование результатов с помощью cross-encoder
7.1.2. Компоненты генерации
1. Инъекция контекста
- Добавление найденных документов в промпт LLM
- Форматирование контекста
2. Генерация ответа
- Запрос к LLM через Ollama или внешний API
- Стриминг ответа через Server-Sent Events (SSE)
7.2. Обработка документов
7.2.1. Поддерживаемые форматы
- PDF — через PyPDFLoader
- DOCX — через Docx2txtLoader
- TXT — через TextLoader
- XLS/XLSX — через openpyxl и кастомные парсеры
- HTML — через BeautifulSoup и lxml
- Изображения — через Pillow (OCR опционально)
7.2.2. Процесс обработки
1. Загрузка документа
2. Извлечение текста
3. Сегментация текста (при необходимости)
4. Генерация эмбеддингов для сегментов
5. Сохранение в Qdrant с метаданными
6. Сохранение исходного файла в GridFS (MongoDB)
7.3. Краулер веб-сайтов
7.3.1. Компоненты
- Парсинг HTML страниц
- Рендеринг JavaScript (опционально через Playwright)
- Дедупликация URL
- Очистка текста (удаление навигации, футера)
- Сохранение в MongoDB + GridFS
- Отчет о прогрессе в Redis
- Сегментация для режима чтения книг
8. Интеграции
8.1. Bitrix24
- Модуль: integrations/bitrix.py
- Назначение: Интеграция с CRM Bitrix24 через webhooks
- Функции: Получение контекста из Bitrix для ответов
8.2. Почта (Email)
- Модуль: integrations/mail.py
- Назначение:
- Получение писем из почтовых ящиков
- Суммаризация сообщений
- Отправка ответов
- Протоколы: IMAP/SMTP
8.3. Telegram Bot
- Модуль: tg_bot/
- Библиотека: aiogram 3.5+
- Назначение: Чат-бот для Telegram
8.4. VK Bot
- Модуль: vk_bot/
- Назначение: Чат-бот для ВКонтакте
9. Веб-интерфейсы
9.1. Админ-панель
- Расположение: admin/
- Технологии: Vanilla JavaScript (ES6+)
- Функции:
- Управление проектами
- Управление знаниями (документами)
- Мониторинг системы
- Управление пользователями
- Настройки интеграций
- Статистика и аналитика
9.2. Виджет чата
- Расположение: widget/
- Технологии: Vanilla JavaScript
- Назначение: Встраиваемый виджет для сайтов
- Функции:
- Чат-интерфейс
- Голосовой ввод (опционально)
- Аватар (опционально)
10. Безопасность
10.1. Компоненты безопасности
- Валидация входных данных: Pydantic модели
- Фильтрация вредоносных запросов: Эвристическая проверка промпт-инъекций
- Аутентификация: Поддержка токенов и сессий
- SSL/TLS: Опциональная поддержка HTTPS
- Rate Limiting: Ограничение частоты запросов
10.2. Резервное копирование
- Модуль: backup/service.py
- Инструменты: MongoDB Database Tools (mongodump/mongorestore)
- Хранение: Локальное или удаленное хранилище
11. Мониторинг и логирование
11.1. Логирование
- Библиотека: structlog>=24.1.0
- Формат: Структурированные JSON логи
- Уровни: DEBUG, INFO, WARNING, ERROR
11.2. Метрики
- Библиотека: prometheus-client>=0.20.0
- Метрики:
- Производительность API
- Использование ресурсов
- Статистика запросов
11.3. Healthchecks
- Эндпоинты: /healthz, /health
- Проверки:
- Состояние MongoDB
- Состояние Redis
- Состояние Qdrant
- Состояние Ollama
12. Тестирование
12.1. Backend тестирование
- Фреймворк: pytest>=8.4.1
- Конфигурация: conftest.py
- Покрытие: Unit и интеграционные тесты
12.2. Frontend тестирование
- Фреймворк: vitest>=1.6.0
- Библиотеки: Testing Library
- Окружение: jsdom
12.3. Линтинг и форматирование
- Ruff: ruff>=0.12.1 — линтер и форматтер для Python
13. Системные требования
13.1. Минимальные требования
- CPU: 2+ ядра
- RAM: 8 GB (рекомендуется 16 GB)
- Диск: 50+ GB (для моделей и данных)
- ОС: Linux (рекомендуется), macOS, Windows (с Docker)
13.2. Рекомендуемые требования
- CPU: 4+ ядра
- RAM: 16+ GB
- Диск: 100+ GB SSD
- GPU: Опционально (NVIDIA GPU для ускорения эмбеддингов и LLM)
13.3. Распределение памяти по сервисам
- app (FastAPI): 8 GB лимит, 2 GB резерв
- celery_worker: 4 GB лимит, 1 GB резерв
- celery_beat: 512 MB лимит, 256 MB резерв
- telegram-bot: 1 GB лимит, 256 MB резерв
14. Версионирование и зависимости
14.1. Система управления зависимостями
- UV: Современный менеджер пакетов Python (>=0.8)
- Lock файл: uv.lock — детерминированные версии зависимостей
- Конфигурация: pyproject.toml
14.2. Версия проекта
- Текущая версия: 0.1.1 (из pyproject.toml)
- Версионирование: Семантическое версионирование
15. Лицензии и открытый исходный код
15.1. Основные библиотеки (открытый исходный код)
- FastAPI — MIT
- LangChain — MIT
- Sentence Transformers — Apache 2.0
- PyTorch — BSD-style
- MongoDB — Server Side Public License (SSPL)
- Redis — BSD 3-Clause
- Qdrant — Apache 2.0
- Ollama — MIT
15.2. Модели
- Модели эмбеддингов и LLM могут иметь различные лицензии (требуется проверка для каждой модели)
16. Дополнительные технические детали
16.1. Асинхронность
- Backend: Полностью асинхронный (async/await)
- Event loop: uvloop (опционально, uvloop>=0.17.0)
- ASGI сервер: Uvicorn с поддержкой WebSockets и SSE
16.2. Кэширование
- Redis кэш:
- Векторные поиски (TTL: 24 часа)
- Сессии пользователей
- Временные данные
- In-memory кэш: LRU кэш для эмбеддингов (128 запросов)
16.3. Масштабируемость
- Горизонтальное масштабирование:
- Несколько экземпляров FastAPI приложения
- Несколько Celery workers
- Кластер Ollama (поддержка нескольких нод)
- Вертикальное масштабирование:
- Увеличение ресурсов контейнеров
- Использование GPU для ускорения
17. Итоговая сводка компонентов
17.1. Языки программирования
1. Python 3.10-3.12 — основной язык (75% кода)
2. JavaScript (ES6+) — клиентская часть (20% кода)
3. HTML/CSS — разметка и стили (5% кода)
17.2. СУБД
1. MongoDB 8.0 — документная БД
2. Redis 5.0+ — кэш и брокер
3. Qdrant — векторная БД
17.3. Объем программы
- Файлов: 161
- Строк кода: ~89,409 (суммарно)
- Python: ~59,522 строк (~66.6%)
- JavaScript/TypeScript: ~20,372 строк (~22.8%)
- HTML: ~4,885 строк (~5.5%)
- CSS: ~4,630 строк (~5.2%)
- Модулей Python: 12+
- Веб-интерфейсов: 2
17.4. Ключевые технологии
- FastAPI, Celery, LangChain, Sentence Transformers, PyTorch
- Ollama, Qdrant, MongoDB, Redis
- Docker, Docker Compose
- Hugging Face Hub
Компоненты системы RAG для реестра программного обеспечения
1. Общая информация о программном обеспечении
1.1. Наименование программного обеспечения
RAG-система (Retrieval-Augmented Generation) — система интеллектуального поиска и генерации ответов на основе векторных эмбеддингов и больших языковых моделей.
1.2. Объем компьютерной программы
1.2.1. Статистика исходного кода
- Общее количество файлов исходного кода: 161 файл
- Общее количество строк кода: ~89,409 строк (суммарно)
- Распределение по типам файлов:
- Python файлы (*.py): ~59,522 строк (основной объем, ~66.6%)
- JavaScript/TypeScript файлы (*.js, *.ts): ~20,372 строк (админ-панель и виджет, ~22.8%)
- HTML файлы (*.html): ~4,885 строк (~5.5%)
- CSS файлы (*.css): ~4,630 строк (~5.2%)
- Конфигурационные файлы (YAML, TOML, JSON): ~500+ строк
1.2.2. Структура кодовой базы
- Основные модули Python: 12 модулей
- Веб-интерфейсы: 2 (админ-панель, виджет)
- Интеграции: 2 (Bitrix24, почта)
- Боты: 2 (Telegram, VK)
- Сервисы: 8 основных сервисов
2. Языки программирования
2.1. Основные языки
2.1.1. Python
- Версия: Python 3.10 - 3.12 (требование: >=3.10,<3.13)
- Использование:
- Backend API (FastAPI)
- Обработка документов и векторизация
- Интеграция с LLM
- Фоновые задачи (Celery workers)
- Боты для мессенджеров
- Процент кодовой базы: ~66.6% (~59,522 строк, основной язык)
2.1.2. JavaScript / TypeScript
- Версия: ES6+ (современный JavaScript)
- Использование:
- Админ-панель (SPA)
- Виджет чата для встраивания
- Клиентская логика веб-интерфейсов
- Процент кодовой базы: ~22.8% (~20,372 строк)
2.1.3. HTML/CSS
- Использование:
- Разметка веб-интерфейсов
- Стилизация компонентов
- Процент кодовой базы: ~10.7% (~9,515 строк: HTML ~4,885, CSS ~4,630)
2.2. Языки разметки и конфигурации
- YAML: Docker Compose конфигурации
- TOML: Конфигурация проекта (pyproject.toml)
- JSON: Конфигурации пакетов, метаданные
3. Системы управления базами данных (СУБД)
3.1. MongoDB
- Версия: MongoDB 8.0
- Назначение:
- Хранение документов и метаданных
- История диалогов и сессий
- Конфигурация проектов (мультитенантность)
- Пользовательские данные
- Хранение бинарных файлов через GridFS
- Драйверы:
- pymongo>=4.13.2 (синхронный)
- motor>=3.7.1 (асинхронный)
- Коллекции:
- projects — конфигурация проектов
- documents — метаданные документов
- conversations — история диалогов
- reading_pages — страницы для режима чтения
- GridFS buckets для бинарных файлов
3.2. Redis
- Версия: Redis 5.0+ (образ: bitnami/redis:latest)
- Назначение:
- Кэширование результатов поиска
- Брокер сообщений для Celery
- Хранение временных данных (сессии, отчеты краулера)
- Rate limiting
- Библиотека: redis>=5.0.4
- Использование:
- Кэш векторных поисков (TTL: 86400 секунд)
- Очередь задач Celery
- Хранение состояния краулера
3.3. Qdrant
- Версия: Qdrant latest (векторная база данных)
- Назначение:
- Хранение векторных эмбеддингов документов
- Семантический поиск (dense vector search)
- BM25 полнотекстовый поиск
- Гибридный поиск (RRF - Reciprocal Rank Fusion)
- Библиотека: qdrant-client>=1.9.0
- Порты:
- HTTP: 6333 (по умолчанию)
- gRPC: 6334 (по умолчанию)
- Параметры векторов:
- Размерность: определяется моделью эмбеддингов
- Метрика расстояния: COSINE (косинусное расстояние)
- Индексы: payload индексы для текста и проектов
4. Фреймворки и библиотеки
4.1. Backend фреймворки
4.1.1. FastAPI
- Версия: fastapi>=0.115.14
- Назначение: Асинхронный веб-фреймворк для REST API
- Дополнительные компоненты:
- fastapi-cli>=0.0.7
- uvicorn[standard]>=0.35.0 (ASGI сервер)
4.1.2. Celery
- Версия: celery>=5.5.3
- Назначение:
- Асинхронная обработка задач
- Планировщик периодических задач (Celery Beat)
- Обновление векторного хранилища
- Резервное копирование
- Брокер: Redis
4.2. Библиотеки для работы с LLM и эмбеддингами
4.2.1. LangChain
- Версии:
- langchain>=0.3.26
- langchain-community>=0.3.27
- langchain-huggingface>=0.1.0
- langchain-redis>=0.2.3
- Назначение: Оркестрация работы с LLM, цепочки обработки
4.2.2. Sentence Transformers
- Версия: sentence-transformers>=2.7.0
- Назначение: Генерация текстовых эмбеддингов
- Модель: deepvk/USER-bge-m3
4.2.3. PyTorch
- Версия: torch>=2.9.0
- Назначение:
- Базовый фреймворк для моделей машинного обучения
- Поддержка GPU/CPU вычислений
- Работа с эмбеддингами
4.2.4. Hugging Face Hub
- Версия: huggingface-hub>=0.33.1
- Назначение: Загрузка и управление моделями из Hugging Face
4.3. Библиотеки для обработки документов
- pypdf>=5.7.0 — обработка PDF файлов
- docx2txt>=0.9 — обработка DOCX файлов
- openpyxl>=3.1.5 — обработка Excel файлов (XLSX)
- beautifulsoup4>=4.12,<5 — парсинг HTML
- lxml>=5.2.0 — XML/HTML парсинг
- Pillow>=10.0 — обработка изображений
4.4. Библиотеки для работы с сетью
- aiohttp>=3.9.5 — асинхронные HTTP запросы
- requests>=2.32,<3 — синхронные HTTP запросы
- httpx>=0.28.1 (dev) — тестирование HTTP
4.5. Утилиты и вспомогательные библиотеки
- pydantic-settings>=2.2.1 — управление настройками
- structlog>=24.1.0 — структурированное логирование
- orjson>=3.10.18 — быстрая сериализация JSON
- python-dotenv>=1.0.1 — загрузка переменных окружения
- python-multipart>=0.0.9 — обработка multipart данных
- nltk>=3.8.1 — обработка естественного языка
- prometheus-client>=0.20.0 — метрики для мониторинга
- pynvml>=11.5.0 — мониторинг GPU (NVIDIA)
4.6. Библиотеки для ботов
- aiogram>=3.5.0 — Telegram Bot API
4.7. JavaScript/TypeScript библиотеки
4.7.1. Тестирование
- vitest>=1.6.0 — тестовый фреймворк
- @testing-library/dom>=9.3.1 — тестирование DOM
- @testing-library/user-event>=14.5.2 — симуляция пользовательских событий
- jsdom>=24.0.0 — DOM окружение для тестов
5. Модели машинного обучения и AI
5.1. Модели эмбеддингов (Embeddings)
5.1.1. Основная модель
- Название: deepvk/USER-bge-m3
- Тип: Sentence Transformer
- Назначение: Генерация векторных представлений текста
- Размерность векторов: 1024
- Устройство: CUDA (если доступно) или CPU
- Кэширование: LRU кэш на 128 запросов
5.2. Большие языковые модели (LLM)
5.2.1. Ollama Runtime
- Образ: ollama/ollama:latest
- Назначение: Локальный runtime для запуска GGUF моделей
- Поддержка кластера: Да (через backend.ollama_cluster)
5.2.2. Поддерживаемые модели
- Модель по умолчанию: yandex/YandexGPT-5-Lite-8B-instruct-GGUF:latest (4.5 GB)
- Альтернативные модели:
- mistral:7b (4.1 GB)
- llama3.1:8b (4.9 GB)
- qwen2.5:14b (8.6 GB)
- phi3:mini (2.7 GB)
5.2.3. Интеграция с внешними LLM
- Поддержка внешних API через backend.llm_client
- Интеграция с YaLLM (Yandex LLM API)
6. Инфраструктура и контейнеризация
6.1. Docker
- Базовый образ: python:3.10-slim
- Multi-stage сборка: Да (build + runtime stages)
- Кэширование:
- APT кэш
- UV кэш для зависимостей
- Hugging Face кэш для моделей
6.2. Docker Compose
- Файлы конфигурации:
- compose.yaml — основная конфигурация
- compose.override.yaml — локальные переопределения
- compose.gpu.yaml — конфигурация для GPU
- Сервисы:
- app — FastAPI приложение
- celery_worker — воркер для фоновых задач
- celery_beat — планировщик задач
- mongo — MongoDB
- redis — Redis
- qdrant — Qdrant векторная БД
- ollama — Ollama runtime (опционально)
- telegram-bot — Telegram бот
6.3. Системные зависимости
- Build stage:
- build-essential — компилятор и инструменты сборки
- git — система контроля версий
- cmake — система сборки
- ninja-build — система сборки
- pkg-config — конфигурация пакетов
- curl — HTTP клиент
- libopenblas-dev — библиотеки для линейной алгебры
- python3-dev — заголовки Python
- Runtime stage:
- libopenblas0-pthread — рантайм библиотеки OpenBLAS
- curl — для healthcheck
- ca-certificates — SSL сертификаты
- MongoDB Database Tools — для резервного копирования
7. Архитектурные компоненты
7.1. RAG Pipeline (Retrieval-Augmented Generation)
7.1.1. Компоненты поиска
1. Векторный поиск (Dense Search)
- Генерация эмбеддинга запроса
- Поиск похожих векторов в Qdrant
- Кэширование результатов в Redis
2. BM25 поиск (Sparse Search)
- Полнотекстовый поиск по ключевым словам
- Реализован в Qdrant
3. Reciprocal Rank Fusion (RRF)
- Объединение результатов векторного и BM25 поиска
- Константа RRF: 60
- Сортировка по итоговому score
4. Reranking (опционально)
- Переранжирование результатов с помощью cross-encoder
7.1.2. Компоненты генерации
1. Инъекция контекста
- Добавление найденных документов в промпт LLM
- Форматирование контекста
2. Генерация ответа
- Запрос к LLM через Ollama или внешний API
- Стриминг ответа через Server-Sent Events (SSE)
7.2. Обработка документов
7.2.1. Поддерживаемые форматы
- PDF — через PyPDFLoader
- DOCX — через Docx2txtLoader
- TXT — через TextLoader
- XLS/XLSX — через openpyxl и кастомные парсеры
- HTML — через BeautifulSoup и lxml
- Изображения — через Pillow (OCR опционально)
7.2.2. Процесс обработки
1. Загрузка документа
2. Извлечение текста
3. Сегментация текста (при необходимости)
4. Генерация эмбеддингов для сегментов
5. Сохранение в Qdrant с метаданными
6. Сохранение исходного файла в GridFS (MongoDB)
7.3. Краулер веб-сайтов
7.3.1. Компоненты
- Парсинг HTML страниц
- Рендеринг JavaScript (опционально через Playwright)
- Дедупликация URL
- Очистка текста (удаление навигации, футера)
- Сохранение в MongoDB + GridFS
- Отчет о прогрессе в Redis
- Сегментация для режима чтения книг
8. Интеграции
8.1. Bitrix24
- Модуль: integrations/bitrix.py
- Назначение: Интеграция с CRM Bitrix24 через webhooks
- Функции: Получение контекста из Bitrix для ответов
8.2. Почта (Email)
- Модуль: integrations/mail.py
- Назначение:
- Получение писем из почтовых ящиков
- Суммаризация сообщений
- Отправка ответов
- Протоколы: IMAP/SMTP
8.3. Telegram Bot
- Модуль: tg_bot/
- Библиотека: aiogram 3.5+
- Назначение: Чат-бот для Telegram
8.4. VK Bot
- Модуль: vk_bot/
- Назначение: Чат-бот для ВКонтакте
9. Веб-интерфейсы
9.1. Админ-панель
- Расположение: admin/
- Технологии: Vanilla JavaScript (ES6+)
- Функции:
- Управление проектами
- Управление знаниями (документами)
- Мониторинг системы
- Управление пользователями
- Настройки интеграций
- Статистика и аналитика
9.2. Виджет чата
- Расположение: widget/
- Технологии: Vanilla JavaScript
- Назначение: Встраиваемый виджет для сайтов
- Функции:
- Чат-интерфейс
- Голосовой ввод (опционально)
- Аватар (опционально)
10. Безопасность
10.1. Компоненты безопасности
- Валидация входных данных: Pydantic модели
- Фильтрация вредоносных запросов: Эвристическая проверка промпт-инъекций
- Аутентификация: Поддержка токенов и сессий
- SSL/TLS: Опциональная поддержка HTTPS
- Rate Limiting: Ограничение частоты запросов
10.2. Резервное копирование
- Модуль: backup/service.py
- Инструменты: MongoDB Database Tools (mongodump/mongorestore)
- Хранение: Локальное или удаленное хранилище
11. Мониторинг и логирование
11.1. Логирование
- Библиотека: structlog>=24.1.0
- Формат: Структурированные JSON логи
- Уровни: DEBUG, INFO, WARNING, ERROR
11.2. Метрики
- Библиотека: prometheus-client>=0.20.0
- Метрики:
- Производительность API
- Использование ресурсов
- Статистика запросов
11.3. Healthchecks
- Эндпоинты: /healthz, /health
- Проверки:
- Состояние MongoDB
- Состояние Redis
- Состояние Qdrant
- Состояние Ollama
12. Тестирование
12.1. Backend тестирование
- Фреймворк: pytest>=8.4.1
- Конфигурация: conftest.py
- Покрытие: Unit и интеграционные тесты
12.2. Frontend тестирование
- Фреймворк: vitest>=1.6.0
- Библиотеки: Testing Library
- Окружение: jsdom
12.3. Линтинг и форматирование
- Ruff: ruff>=0.12.1 — линтер и форматтер для Python
13. Системные требования
13.1. Минимальные требования
- CPU: 2+ ядра
- RAM: 8 GB (рекомендуется 16 GB)
- Диск: 50+ GB (для моделей и данных)
- ОС: Linux (рекомендуется), macOS, Windows (с Docker)
13.2. Рекомендуемые требования
- CPU: 4+ ядра
- RAM: 16+ GB
- Диск: 100+ GB SSD
- GPU: Опционально (NVIDIA GPU для ускорения эмбеддингов и LLM)
13.3. Распределение памяти по сервисам
- app (FastAPI): 8 GB лимит, 2 GB резерв
- celery_worker: 4 GB лимит, 1 GB резерв
- celery_beat: 512 MB лимит, 256 MB резерв
- telegram-bot: 1 GB лимит, 256 MB резерв
14. Версионирование и зависимости
14.1. Система управления зависимостями
- UV: Современный менеджер пакетов Python (>=0.8)
- Lock файл: uv.lock — детерминированные версии зависимостей
- Конфигурация: pyproject.toml
14.2. Версия проекта
- Текущая версия: 0.1.1 (из pyproject.toml)
- Версионирование: Семантическое версионирование
15. Лицензии и открытый исходный код
15.1. Основные библиотеки (открытый исходный код)
- FastAPI — MIT
- LangChain — MIT
- Sentence Transformers — Apache 2.0
- PyTorch — BSD-style
- MongoDB — Server Side Public License (SSPL)
- Redis — BSD 3-Clause
- Qdrant — Apache 2.0
- Ollama — MIT
15.2. Модели
- Модели эмбеддингов и LLM могут иметь различные лицензии (требуется проверка для каждой модели)
16. Дополнительные технические детали
16.1. Асинхронность
- Backend: Полностью асинхронный (async/await)
- Event loop: uvloop (опционально, uvloop>=0.17.0)
- ASGI сервер: Uvicorn с поддержкой WebSockets и SSE
16.2. Кэширование
- Redis кэш:
- Векторные поиски (TTL: 24 часа)
- Сессии пользователей
- Временные данные
- In-memory кэш: LRU кэш для эмбеддингов (128 запросов)
16.3. Масштабируемость
- Горизонтальное масштабирование:
- Несколько экземпляров FastAPI приложения
- Несколько Celery workers
- Кластер Ollama (поддержка нескольких нод)
- Вертикальное масштабирование:
- Увеличение ресурсов контейнеров
- Использование GPU для ускорения
17. Итоговая сводка компонентов
17.1. Языки программирования
1. Python 3.10-3.12 — основной язык (75% кода)
2. JavaScript (ES6+) — клиентская часть (20% кода)
3. HTML/CSS — разметка и стили (5% кода)
17.2. СУБД
1. MongoDB 8.0 — документная БД
2. Redis 5.0+ — кэш и брокер
3. Qdrant — векторная БД
17.3. Объем программы
- Файлов: 161
- Строк кода: ~89,409 (суммарно)
- Python: ~59,522 строк (~66.6%)
- JavaScript/TypeScript: ~20,372 строк (~22.8%)
- HTML: ~4,885 строк (~5.5%)
- CSS: ~4,630 строк (~5.2%)
- Модулей Python: 12+
- Веб-интерфейсов: 2
17.4. Ключевые технологии
- FastAPI, Celery, LangChain, Sentence Transformers, PyTorch
- Ollama, Qdrant, MongoDB, Redis
- Docker, Docker Compose
- Hugging Face Hub
