Дисклеймер: Данный бейзлайн является лишь отправной точкой для вашего собственного решения. Участники могут и должны модифицировать его по своему усмотрению. Мы настоятельно рекомендуем экспериментировать: пробовать разные модели, подходы к валидации, создавать новые признаки и строить ансамбли. Этот код не является обязательной частью вашего финального решения, а лишь помогает быстрее начать работу.
Baseline-решение для задачи предсказания оценок книг пользователями в рамках соревнования НТО 2025/2026 (Профиль «Искусственный интеллект»).
Модель предсказывает оценку (rating) от 0 до 10, которую пользователь поставит книге.
Модель: используется градиентный бустинг LightGBM
Валидация: применяется методологически корректное разделение по времени (temporal split). Обучение происходит на более ранних данных, а валидация — на более поздних, что симулирует реальную задачу
Признаки:
- Агрегированные: средние оценки и количество оценок для пользователей, книг и авторов.
- Метаданные: пол, возраст, год публикации, язык, издательство.
- Текстовые (TF-IDF): признаки на основе биграмм из описаний книг.
- Текстовые (BERT): эмбеддинги из русскоязычной модели
DeepPavlov/rubert-base-cased.
Перед установкой зависимостей рекомендуется создать и активировать виртуальное окружение, чтобы изолировать зависимости проекта.
# Создание виртуального окружения
python -m venv .venv
# Активация (Linux/macOS)
source .venv/bin/activate
# Активация (Windows, PowerShell)
.venv\\Scripts\\Activate.ps1Poetry используется для управления зависимостями проекта. Если у вас ещё не установлен Poetry, воспользуйтесь официальным способом установки.
Linux / macOS / WSL (Windows)
curl -sSL https://install.python-poetry.org | python3 -После установки может потребоваться добавить Poetry в PATH. Следуйте инструкциям в терминале.
Windows (PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -После успешной установки Poetry можно переходить к установке зависимостей проекта.
poetry installУбедитесь, что в директории data/raw/ находятся следующие файлы:
data/raw/
├── book_descriptions.csv
├── book_genres.csv
├── books.csv
├── genres.csv
├── sample_submission.csv
├── test.csv
├── train.csv
└── users.csv
Пайплайн разделён на отдельные этапы для эффективности и возможности повторного использования обработанных данных:
# 1. Подготовка данных (загрузка, фильтрация, feature engineering)
poetry run python -m src.baseline.prepare_data
# 2. Обучение модели (использует подготовленные данные)
poetry run python -m src.baseline.train
# 3. Предсказание (использует подготовленные данные и обученные модели)
poetry run python -m src.baseline.predict
# 4. Валидация submission
poetry run python -m src.baseline.validateИли через Makefile:
make prepare-data # Подготовка данных
make train # Обучение
make predict # Предсказание
make validate # Валидация
make run # Полный цикл (prepare-data + train + predict + validate)
make clean # Удаление всех сгенерированных файлов (данные, модели, сабмиты)Примечание: Подготовка данных (prepare-data) должна быть выполнена перед обучением и предсказанием. Подготовленные данные сохраняются в data/processed/ и используются повторно без пересчёта признаков.
.
├── data/
│ ├── raw/ # Исходные CSV-файлы
│ ├── interim/ # Промежуточные данные (при необходимости)
│ └── processed/ # Обработанные данные с признаками (parquet)
├── output/
│ ├── models/ # Обученные модели и TF-IDF векторайзер
│ └── submissions/ # Файлы submission
├── src/baseline/
│ ├── config.py # Конфигурация и параметры модели
│ ├── constants.py # Константы проекта (имена файлов, колонок)
│ ├── data_processing.py # Загрузка и объединение raw данных
│ ├── features.py # Feature engineering (агрегаты, жанры, TF-IDF, BERT)
│ ├── prepare_data.py # Подготовка данных (загрузка, обработка, сохранение)
│ ├── temporal_split.py # Утилиты для корректного временного разделения данных
│ ├── train.py # Обучение модели (использует prepared данные)
│ ├── predict.py # Генерация предсказаний (использует prepared данные)
│ ├── validate.py # Проверка формата submission
│ └── evaluate.py # Оценка качества предсказаний (метрики)
└── Makefile # Удобные команды
Корректная временная валидация. Пороговая дата определяется на основе параметра TEMPORAL_SPLIT_RATIO в config.py. Все взаимодействия до этой даты используются для обучения, а после — для валидации, что симулирует реальную задачу предсказания будущего.
Предотвращение утечек данных. Агрегатные признаки (средние оценки и т.д.) вычисляются после временного разделения. Для валидационной выборки агрегаты рассчитываются только на основе данных из обучающей части. При генерации предсказаний для теста, агрегаты считаются по всей обучающей выборке.
Разделенный пайплайн. Процесс разделён на три этапа для эффективности:
prepare-data: создание статичных признаков (жанры, текст) без вычисления агрегатов.train: выполнение временного сплита, вычисление динамических агрегатных признаков и обучение одной модели.predict: вычисление агрегатных признаков на всем обучающем датасете и генерация предсказаний.
Фильтрация обучающих данных. Используются только записи, где книга была прочитана и оценена (has_read=1).
Кэширование. BERT-эмбеддинги и обработанные данные сохраняются в output/models/ и data/processed/ для ускорения повторных запусков.
Качество кода. Используется ruff для линтинга и форматирования, а также полная типизация кода.
Для оценки качества предсказаний используется скрипт evaluate.py. Именно этот скрипт расположен на сервере и тестирует ваше решение. Вы можете создать свою test выборку и симулировать процесс оценки на сервере.
poetry run python -m src.baseline.evaluate --submission output/submissions/submission.csv --solution data/processed/custom_test_solution.csv
Score рассчитывается на основе RMSE и MAE:
Score = 1 - (0.5 * RMSE/10 + 0.5 * MAE/10)
Предсказания автоматически ограничиваются диапазоном [0, 10].
- Python >= 3.10
- pandas, scikit-learn, lightgbm, joblib
- transformers, torch, sentencepiece
- ruff, pre-commit (dev)