docs/DEVELOPMENT.md

Руководство для разработчиков

Начало работы

Настройка окружения разработки

1. Клонируйте репозиторий
2. Создайте виртуальное окружение:

python -m venv venv
venv\Scripts\activate  # Windows
# или
source venv/bin/activate  # Linux/Mac

3. Установите зависимости:

pip install -r requirements.txt

4. Установите spaCy модели:

python -m spacy download en_core_web_sm
python -m spacy download ru_core_news_sm
python -m spacy download de_core_news_sm
python -m spacy download es_core_news_sm
python -m spacy download it_core_news_sm

Запуск в режиме разработки

python main.py

Или с автоматической перезагрузкой:

uvicorn main:app --host 127.0.0.1 --port 8001 --reload

Структура кода

Стиль кода

• Следуйте PEP 8 для Python
• Используйте type hints где возможно
• Документируйте функции docstrings
• Используйте понятные имена переменных

Организация кода

main.py:

• Только роутинг и обработка HTTP запросов
• Минимум бизнес-логики
• Делегирование в logic.py

logic.py:

• Вся бизнес-логика
• Разделение на модули (SPACY, ANALYTICS, BERT)
• Глобальные переменные для кэширования моделей

models.py:

• Только Pydantic модели
• Валидация данных
• Документация полей

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

Ручное тестирование

1. Используйте Swagger UI: http://127.0.0.1:8001/docs
2. Тестируйте через веб-интерфейс
3. Проверяйте различные языки и размеры текстов

Примеры тестовых данных

Русский язык:

{
  "target_text": "Это пример текста для анализа SEO оптимизации.",
  "competitors": ["Конкурентный текст номер один с похожим содержанием.", "Второй конкурентный текст."],
  "keywords": ["SEO анализ", "оптимизация текста"],
  "language": "ru"
}

Английский язык:

{
  "target_text": "This is an example text for SEO analysis.",
  "competitors": ["Competitor text number one.", "Second competitor text."],
  "keywords": ["SEO analysis", "text optimization"],
  "language": "en"
}

Отладка

Логирование

Добавьте логирование в ключевых местах:

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

logger.info("Loading model...")

Проверка моделей

Проверьте загрузку моделей:

# В Python консоли
import logic
logic.load_models()
print(logic.LoadedModels.keys())

Проверка BERT

import logic
model = logic.get_bert_model()
print(model.device)  # Должно показать 'cuda' или 'cpu'

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

Профилирование

Используйте cProfile для профилирования:

import cProfile
import pstats

profiler = cProfile.Profile()
profiler.enable()

# Ваш код

profiler.disable()
stats = pstats.Stats(profiler)
stats.sort_stats('cumulative')
stats.print_stats(10)

Оптимизация

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

   • Модели уже кэшируются
   • Рассмотрите кэширование результатов для одинаковых запросов

2. Параллелизация:

   • Обработка конкурентов может быть параллельной
   • Используйте asyncio или multiprocessing

3. Батчинг:

   • BERT может обрабатывать несколько текстов одновременно
   • Используйте батчи для эмбеддингов

Добавление новых функций

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

1. Создайте функцию в logic.py:

def my_new_analysis(target_text: str, competitors: List[str], lang: str) -> Dict:
    # Ваша логика
    return {"result": "data"}

2. Добавьте вызов в main.py:

my_result = logic.my_new_analysis(
    request.target_text,
    request.competitors,
    request.language
)

3. Добавьте поле в AnalysisResponse:

class AnalysisResponse(BaseModel):
    # ... существующие поля
    my_new_analysis: Dict

4. Обновите UI в templates/index.html

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

1. Установите spaCy модель:

python -m spacy download <lang>_core_news_sm

2. Добавьте в MODEL_NAMES:

MODEL_NAMES = {
    # ... существующие
    "new_lang": "new_lang_core_news_sm"
}

3. Добавьте опцию в UI:

<option value="new_lang">🇺🇸 New Language</option>

Работа с зависимостями

Обновление зависимостей

1. Обновите версии в requirements.txt
2. Установите:

pip install -r requirements.txt --upgrade

3. Протестируйте приложение

Добавление новой зависимости

1. Установите пакет:

pip install new-package

2. Добавьте в requirements.txt:

pip freeze > requirements.txt

3. Или добавьте вручную:

new-package==1.0.0

Git workflow

Коммиты

Используйте понятные сообщения коммитов:

feat: добавлен анализ тональности
fix: исправлена ошибка в BM25 расчетах
docs: обновлена документация API
refactor: рефакторинг функции analyze_text

Ветки

• main - стабильная версия
• develop - разработка
• feature/название - новая функция
• fix/название - исправление бага

Развертывание

Production настройки

1. Отключите debug режим:

app = FastAPI(title="SEO AI Editor", debug=False)

2. Используйте production сервер:

uvicorn main:app --host 0.0.0.0 --port 8001 --workers 4

3. Настройте переменные окружения:

import os
DEBUG = os.getenv("DEBUG", "False") == "True"

Docker (опционально)

Создайте Dockerfile:

FROM python:3.10-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8001"]

Известные проблемы

Память

• Большие тексты могут потреблять много памяти
• BERT модель занимает ~400MB RAM
• spaCy модели занимают ~50-100MB каждая

Решение: Ограничьте размер входных текстов или используйте потоковую обработку

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

• Первый запрос медленнее (загрузка BERT)
• Длинные тексты обрабатываются дольше

Решение: Предзагрузка BERT модели, оптимизация алгоритмов

Языковые модели

• Некоторые языки могут иметь ограниченную поддержку
• Качество анализа зависит от качества моделей

Решение: Используйте более качественные модели или обучите свои

Полезные ресурсы

• FastAPI документация
• spaCy документация
• Sentence Transformers
• BM25 алгоритм

Контакты и поддержка

Для вопросов и предложений:

• Создавайте issues в репозитории
• Предлагайте улучшения через pull requests
• Документируйте найденные баги