docs/ARCHITECTURE.md

Архитектура проекта

Обзор

SEO AI Editor построен на архитектуре клиент-сервер с использованием FastAPI для backend и простого HTML/JavaScript для frontend.

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

seo_ai_editor/
├── main.py              # Точка входа, FastAPI приложение
├── logic.py             # Бизнес-логика и алгоритмы анализа
├── models.py            # Pydantic модели данных
├── requirements.txt     # Python зависимости
├── templates/
│   └── index.html       # Frontend интерфейс
├── docs/                # Документация
│   ├── API.md
│   ├── ARCHITECTURE.md
│   └── DEVELOPMENT.md
└── README.md            # Основная документация

Компоненты системы

1. Backend (FastAPI)

main.py - Веб-сервер

Ответственность:

• Инициализация FastAPI приложения
• Роутинг HTTP запросов
• Предзагрузка моделей при старте
• Обработка запросов и формирование ответов

Ключевые функции:

• startup_event() - загрузка моделей при старте
• read_root() - отдача главной страницы
• analyze_text() - обработка запроса на анализ

logic.py - Бизнес-логика

Разделен на три модуля:

A. SPACY (Лингвистический анализ)

Модели:

• Глобальный словарь LoadedModels для кэширования загруженных spaCy моделей
• Поддержка 5 языков: en, ru, de, es, it

Функции:

• load_model_if_missing(lang) - ленивая загрузка моделей
• load_models() - предзагрузка всех моделей
• get_doc(text, lang) - получение spaCy документа
• is_valid_token(t) - фильтрация токенов (удаление мусора)
• get_lemmas_flat(text, lang) - получение списка лемм
• generate_ngrams_safe(text, lang, n) - генерация N-грамм с умной фильтрацией

Особенности:

• Сохранение стоп-слов внутри фраз для читаемости
• Фильтрация N-грамм, состоящих только из стоп-слов
• Обработка больших текстов (max_length = 2,000,000)

B. ANALYTICS (N-граммы и BM25)

Функции:

• calculate_ngram_stats() - статистика по N-граммам (1-4)
• parse_keywords() - парсинг ключевых фраз
• calculate_bm25_recommendations() - многоуровневый BM25 анализ

Алгоритм BM25 (с полной декомпозицией фраз):

1. Декомпозиция ключевых фраз: Для каждой ключевой фразы генерируются все возможные под-н-граммы длиной от 1 до 3 слов
   • Пример: фраза "chicken road casino" разбивается на:
     • Униграммы: "chicken", "road", "casino"
     • Биграммы: "chicken road", "road casino"
     • Триграммы: "chicken road casino"
   • Используется скользящее окно по токенам фразы
   • Дубликаты отслеживаются через set для оптимизации
2. Генерация N-грамм для целевого текста и конкурентов (униграммы, биграммы, триграммы)
3. Обучение BM25 модели на корпусе N-грамм для каждого уровня (1, 2, 3)
4. Расчет BM25 скоров для каждой декомпозированной фразы
5. Сравнение скоров целевого текста со средним скором конкурентов
6. Генерация рекомендаций (add/remove/ok) на основе пороговых значений
7. Сортировка результатов: сначала проблемные (add/remove), затем по длине фразы, затем алфавитно

Пороги:

• Униграммы: 0.5
• Биграммы: 0.25
• Триграммы: 0.15

Особенности:

• Полная декомпозиция позволяет анализировать не только целые фразы, но и их части
• Это особенно полезно для длинных ключевых фраз, которые могут встречаться в тексте частично
• Автоматическое удаление дубликатов при декомпозиции

C. BERT / VECTOR ANALYSIS

Модель:

• Глобальная переменная BertModel для кэширования
• Модель: paraphrase-multilingual-MiniLM-L12-v2
• Автоматическое определение устройства (CPU/GPU)

Функции:

• get_bert_model() - загрузка BERT модели
• perform_bert_analysis() - семантический анализ

Алгоритм BERT анализа:

1. Разбиение текстов на предложения (chunks)
2. Генерация эмбеддингов для всех chunks и ключевых фраз
3. Расчет косинусного сходства между ключевыми фразами и chunks
4. Global Score: средний максимальный score по всем ключам
5. Detailed Analysis: топ-5 наиболее релевантных chunks для каждой фразы

models.py - Модели данных

Pydantic модели:

• AnalysisRequest - входные данные для анализа
• AnalysisResponse - структура ответа API

2. Frontend

templates/index.html

Технологии:

• Bootstrap 5 для UI
• Vanilla JavaScript (без фреймворков)
• AJAX для взаимодействия с API

Компоненты:

• Форма ввода данных
• Табы для отображения результатов
• Динамическое добавление полей конкурентов
• Визуализация результатов анализа

Поток данных

1. Пользователь вводит данные в форму
   ↓
2. JavaScript собирает данные и отправляет POST /analyze
   ↓
3. FastAPI получает запрос, валидирует через Pydantic
   ↓
4. main.py вызывает функции из logic.py:
   - calculate_ngram_stats()
   - parse_keywords()
   - calculate_bm25_recommendations()
   - perform_bert_analysis()
   ↓
5. Каждая функция использует:
   - spaCy для лингвистики
   - BM25 для частотного анализа
   - BERT для семантики
   ↓
6. Результаты собираются в AnalysisResponse
   ↓
7. JSON ответ отправляется клиенту
   ↓
8. JavaScript рендерит результаты в UI

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

Backend

Глобальные переменные:

• LoadedModels - кэш загруженных spaCy моделей
• BertModel - кэш BERT модели

Стратегия:

• Модели загружаются один раз при первом использовании
• Предзагрузка spaCy моделей при старте (опционально)
• BERT модель загружается лениво при первом запросе

Frontend

Состояние:

• currentData - последние результаты анализа
• DOM состояние для табов и форм

Производительность

Оптимизации

1. Кэширование моделей:

   • spaCy модели загружаются один раз
   • BERT модель загружается один раз

2. Ленивая загрузка:

   • spaCy модели загружаются только для используемых языков
   • BERT модель загружается при первом запросе

3. GPU ускорение:

   • Автоматическое использование CUDA для BERT
   • Значительное ускорение на GPU

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

   • N-граммы ограничены 150 элементами на тип
   • Топ-5 chunks для BERT анализа

Ограничения

• Максимальная длина текста для spaCy: 2,000,000 символов
• Память: зависит от размера моделей и длины текстов
• Время обработки: зависит от длины текстов и наличия GPU

Масштабируемость

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

• Однопоточная обработка запросов
• Модели загружаются в память
• Нет кэширования результатов

Возможные улучшения

1. Асинхронность:

   • Использование async/await для I/O операций
   • Параллельная обработка конкурентов

2. Кэширование:

   • Redis для кэширования результатов
   • Кэширование эмбеддингов

3. Микросервисы:

   • Отдельный сервис для BERT
   • Отдельный сервис для spaCy

4. База данных:

   • Сохранение истории анализов
   • Статистика использования

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

Текущее состояние

• Нет аутентификации
• Нет ограничений на размер запросов
• Нет валидации входных данных (кроме Pydantic)

Рекомендации

1. Валидация:

   • Ограничение размера текстов
   • Санитизация входных данных

2. Аутентификация:

   • API ключи
   • OAuth 2.0

3. Rate Limiting:

   • Ограничение количества запросов
   • Защита от DDoS

Зависимости

Критические

• fastapi - веб-фреймворк
• spacy - NLP библиотека
• sentence-transformers - BERT модели
• rank-bm25 - BM25 алгоритм
• torch - глубокое обучение

Вспомогательные

• uvicorn - ASGI сервер
• pydantic - валидация данных
• jinja2 - шаблонизация
• numpy - численные вычисления

Расширяемость

Добавление нового языка

1. Установить spaCy модель для языка
2. Добавить в MODEL_NAMES в logic.py
3. Добавить опцию в UI (templates/index.html)

Добавление новой модели BERT

1. Изменить модель в get_bert_model()
2. Убедиться в совместимости с sentence-transformers

Добавление нового типа анализа

1. Создать функцию в logic.py
2. Добавить вызов в analyze_text() в main.py
3. Добавить поле в AnalysisResponse
4. Обновить UI для отображения результатов