Hack_Change_2025 — ML & Visualization Pipeline

| | | | __ _  | | () ___  | | ()  _ _ 
| || |/ |/ __| |/ / |/ _ \/ _ | |/ / | ' \ / _ \ '|
| _ | (| | (__| <| | __/ (| | <| | | | |  / |
| || |/ |/ __| |/ / |/ _ \/ ___
|___/

Автор ветки: Boris Cherkasov
Контакт: boris.cherkasov@example.com

📌 О проекте

Проект представляет собой полный пайплайн для анализа текстов, визуализации данных и классификации тональности.

Он включает:

• модуль с генерацией PNG-графиков;
• ML-пайплайн со всеми компонентами современного обучения (K-Fold, ensembles, stacking, pseudo-labeling);
• API для визуализации и инференса;
• фронтенд (HTML/JS) для просмотра графиков и работы с моделью.

Решение полностью подготовлено для развёртывания на бесплатных облаках и дальнейшего промышленного использования.

🗂 Структура репозитория

project/
│
├── train_pipeline.py # основной ML-пайплайн
├── stacker.py # stacking (meta-модель)
├── pseudo_label.py # pseudo-labeling
│
├── visualize/
│ ├── scripts/ # генерация графиков EDA
│ └── api/
│ └── main.py # FastAPI backend
│
├── eda_output/ # PNG графики
├── rubert_out_kfold/ # K-Fold результаты
├── rubert_out_pseudo/ # pseudo-label результаты
├── index.html # фронтенд-дэшборд
└── requirements.txt

⚙️ Подготовка окружения

Локально

python -m venv .venv
source .venv/bin/activate       # Linux / MacOS
.venv\Scripts\activate          # Windows

pip install --upgrade pip
pip install -r requirements.txt

Kaggle

1. Включить Internet (Settings -> ON)
2. Установить зависимости

pip install -q transformers datasets evaluate scikit-learn sentencepiece pymorphy3
pip install protobuf==3.20.1

3. Перезапустить ядро

🚀 Запуск пайплайна

python train_pipeline.py \
  --train_csv /kaggle/input/.../train.csv \
  --test_csv /kaggle/input/.../test.csv \
  --output_dir rubert_out_smoke \
  --epochs 1 \
  --batch_size 8

K-Fold прогон

python train_pipeline.py \
  --train_csv /kaggle/input/.../train.csv \
  --test_csv /kaggle/input/.../test.csv \
  --output_dir rubert_out_kfold \
  --model_name DeepPavlov/rubert-base-cased-sentiment \
  --epochs 3 \
  --batch_size 8 \
  --kfold 5 \
  --n_splits 5 \
  --save_metrics True

Stacking

python stacker.py \
  --oof_path rubert_out_kfold/oof_predictions.csv \
  --test_path rubert_out_kfold/test_predictions_ensemble.csv \
  --output_dir rubert_out_kfold/stacker_out

Pseudo-labeling

Создаем новый train

python pseudo_label.py \
  --train_csv /kaggle/input/.../train.csv \
  --predictions_csv rubert_out_kfold/stacker_out/stacked_predictions.csv \
  --threshold 0.95 \
  --output_dir pseudo_out \
  --retrain False

+ дообучение

python pseudo_label.py \
  --train_csv /kaggle/input/.../train.csv \
  --predictions_csv rubert_out_kfold/stacker_out/stacked_predictions.csv \
  --threshold 0.95 \
  --output_dir pseudo_out \
  --retrain True \
  --retrain_output_dir rubert_out_pseudo \
  --retrain_epochs 5 \
  --kfold 5

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

1. Через REST API

curl -X POST "http://localhost:8000/predict" \
-H "Content-Type: application/json" \
-d '{"text":"Мне понравилась работа сервиса"}'

Ответ:

{"label":1, "confidence":0.94}

2. Построение графика

curl http://localhost:8000/plot/distribution

Вернет изображение

🪩 FastAPI приложение

Запуск сервера

uvicorn visualize.api.main:app --host 0.0.0.0 --port 8000 --reload

Открыть фронтенд:

open index.html

Функции:

• генерация весх графиков;
• быстрый EDA;
• тестирование ML модели;
• кнопка очистки экрана

📊 Что создаёт pipeline

В output_dir формируются:

• oof_predictions.csv
• test_predictions_ensemble.csv
• stacker_out/stacked_predictions.csv
• predictions.csv
• metrics.json
• модели по фолдам: fold_*/pytorch_model.bin
• токенизатор: tokenizer.json, vocab.txt, tokenizer_config.json, * special_tokens_map.json
• Эти файлы подходят для деплоя модели в продакшен.

🧠 ML Архитектура

Используем:

• ruBERT (Tiny / Base)
• Weighted CrossEntropy
• Focal Loss
• Stratified K-Fold
• Soft Voting Ensemble
• Meta Stacking (TF-IDF + LogisticRegression)
• Pseudo-labeling (автоматическое самообучение)
• Gradient Accumulation
• Апсемплинг (опционально)
• Обученная модель стабильно даёт высокие значения F1-макро благодаря ансамблевым техникам.

🧩 Поддержка

По вопросам запуска, багам или расширению функционала:

• Email: boris.cherkasov@example.com
• Issue Tracker: используйте раздел Issues в репозитории
• Telegram: @bor1s_cherkas0v

🗺 Дорожная карта

• Краткосрочные задачи
• Hyperparameter tuning (Optuna)
• Продвинутая визуализация в UI
• Docker-контейнеры для деплоя
• Среднесрочные задачи
• Мульти-язычный сентимент-анализ
• Автоматическая проверка токсичности
• Интеграция аналитики через Grafana
• Долгосрочные задачи
• Полный MLOps: CI/CD + автоматический деплой
• Интеграция с MLflow
• Расширение на topic modeling

🤝 Внести свой вклад

Сделайте форк Создайте ветку:

git checkout -b feature/new-feature

Внесите изменения Запустите форматирование:

black .
flake8 .
Откройте Pull Request

🙏 Авторы и благодарности

Boris Cherkasov — разработка, ML, архитектура проекта Команда организаторов Hack&Change 2025

Open-source сообщество: Transformers, Datasets, Torch, Scikit-learn

📜 Лицензия

Проект распространяется под лицензией MIT.

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

Готово к демонстрации • Поддерживается • Принимает Pull Requests

Проект активно развивается — любые предложения приветствуются!