Организация кода и исследований для Kaggle

Расскажи мне, и я забуду. Обучи меня, и я запомню. Вовлеки меня, и я усвою.

Этот принцип полностью применим, а обучение через практику остается одним из наиболее эффективных способов освоения новых умений. В области науки о данных и машинного обучения участие в конкурсах представляет собой один из лучших методов получения практического опыта и совершенствования компетенций.

Kaggle — крупнейшее сообщество специалистов по науке о данных в мире, а его соревнования высоко ценятся в профессиональной среде. Многие ведущие конференции по машинному обучению (например, NeurIPS), компании (например, Google) и университеты (например, Stanford) проводят конкурсы на платформе Kaggle.

В престижных соревнованиях Kaggle награждают медалями лучших участников по результатам приватного лидерборда. Участие в таком конкурсе, как NeurIPS – Ariel Data Challenge 2025, часть трека соревнований NeurIPS 2025, демонстрирует, насколько платформа проверяет не только навыки в машинном обучении.

Соревнования на Kaggle оценивают умения в программировании и инженерии ПО. Они требуют грамотной организации кодовой базы для оперативной итерации и тестирования идей, а также четкого ведения учета экспериментов и результатов.

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

В целом, подобный опыт способствует глубокому пониманию и усвоению уроков за пределами машинного обучения.

Цель материала — передать эти уроки, не связанные напрямую с ML. Все они основаны на ключевом принципе: организация, организация, организация.

Сначала будет показано, почему четкая структура кода и организация процессов не являются пустой тратой времени или приятным дополнением, а представляют собой неотъемлемую часть участия в Kaggle и любого удачного проекта в науке о данных. Затем будут описаны применяемые техники и вынесенные уроки по структурированию кода и процессу экспериментов.

Важно отметить, что подходы здесь не претендуют на абсолютную экспертизу. Они основаны на начальном этапе пути и предназначены для помощи в избежании типичных ошибок. Дополнительные рекомендации приветствуются для коллективного обучения.

1 Золотое правило науки: Организуйте

Известно, что естественные ученые ведут подробные записи о своей работе и исследовательском процессе. Неясные этапы могут привести к ошибочным выводам и пониманию. Невоспроизводимая работа — это проклятие науки. Для специалистов по данным ничего не меняется.

1.1 Но скорость имеет значение!

Частый контраргумент заключается в том, что наука о данных — это динамичная и итеративная область. Эксперименты обычно недороги и быстры; мало кто предпочитает документирование кодингу и созданию моделей.

Хотя эта точка зрения понятна и быстрые результаты привлекательны, такой подход недальновиден. Помните, конечная цель любого проекта в науке о данных — предоставить точные, воспроизводимые результаты или инсайты, которые можно применить на практике.

Представьте ситуацию: для каждого эксперимента используется отдельный ноутбук на Kaggle, выполняющий все от загрузки и предобработки данных до обучения модели, оценки и отправки. После десятков экспериментов обнаруживается ошибка в функции загрузки данных, примененной во всех случаях. Исправление потребует проверки каждого ноутбука, устранения дефекта, проверки на новые проблемы и повторного запуска всего. Этого можно избежать с помощью модульной и переиспользуемой структуры кода.

Drivendata (2022) приводит пример неудачного проекта в науке о данных, который занял месяцы и стоил миллионов долларов. Провал произошел из-за ранней ошибки: баг в очистке данных исказил информацию и привел к неверным выводам. Лучший учет источников и трансформаций позволил бы выявить проблему раньше и сэкономить средства.

Главный вывод раздела: организация — это не опция, а фундаментальная часть любого проекта в науке о данных. Без четкой структуры кода и процессов неизбежны ошибки, потеря времени и невоспроизводимые результаты.

1.3 Что отслеживать и организовывать?

Три ключевых аспекта заслуживают внимания для организации:

1. Кодовая база
2. Результаты экспериментов и конфигурации
3. Исследования и обучение

2 Кодовая база

Код — основа любого проекта в науке о данных. Здесь полезно перенять опыт инженеров ПО.

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

Любая продуманная структура кодовой базы уже является успехом.

Универсальной структуры не существует и не появится. Раздел субъективен и отражает предпочтения. Описана общая структура, которая применяется.

Работа начинается с популярного шаблона Cookiecutter Data Science (ccds). Инициализация создает папку со следующей структурой.¹

├── LICENSE <- Лицензия с открытым исходным кодом, если выбрана
├── Makefile <- Makefile с удобными командами, такими как `make data` или `make train`
├── README.md <- Основной README для разработчиков, использующих проект.
├── data
│   ├── external <- Данные из внешних источников.
│   ├── interim <- Промежуточные данные после трансформаций.
│   ├── processed <- Финальные наборы данных для моделирования.
│   └── raw <- Исходные неизменяемые данные.
│   ├── docs <- Проект mkdocs по умолчанию; см. www.mkdocs.org для деталей
│   ├── models <- Обученные и сериализованные модели, предсказания или обзоры моделей
│   ├── notebooks <- Jupyter-ноутбуки. Конвенция именования: номер (для сортировки),
│   инициалы создателя и краткое описание с `-`, напр.
│   `1.0-jqp-initial-data-exploration`.
│   ├── pyproject.toml <- Файл конфигурации проекта с метаданными пакета для
│   {{ cookiecutter.module_name }} и настройками инструментов вроде black
│   ├── references <- Словари данных, руководства и другие объясняющие материалы.
│   ├── reports <- Сгенерированный анализ в HTML, PDF, LaTeX и т.д.
│   └── figures <- Сгенерированные графики и фигуры для отчетов
│   ├── requirements.txt <- Файл требований для воспроизведения среды анализа, напр.
│   сгенерированный `pip freeze > requirements.txt`
│   ├── setup.cfg <- Файл конфигурации для flake8
│   └── {{ cookiecutter.module_name }} <- Исходный код для проекта.
│       ├── __init__.py <- Делает {{ cookiecutter.module_name }} модулем Python
│       ├── config.py <- Хранение полезных переменных и конфигураций
│       ├── dataset.py <- Скрипты для загрузки или генерации данных
│       ├── features.py <- Код для создания признаков для моделирования
│       ├── modeling
│       │   ├── __init__.py
│       │   ├── predict.py <- Код для инференса с обученными моделями
│       │   └── train.py <- Код для обучения моделей
│       └── plots.py <- Код для создания визуализаций

2.1.1 Управление окружением

При использовании ccds предлагается выбрать менеджер окружений. Предпочтение отдается uv от Astral. Он фиксирует все пакеты в файле pyproject.toml и позволяет воссоздать окружение командой uv sync.

Под капотом uv применяет venv. Управление им проще, чем прямое ведение виртуальных окружений, поскольку pyproject.toml удобнее requirements.txt.

Кроме того, uv проще conda, так как ориентирован исключительно на Python, в отличие от универсального conda.

2.1.2 Сгенерированный модуль

Ключевой элемент шаблона — директория {{ cookiecutter.module_name }}. Здесь формируется пакет Python, содержащий все важные компоненты кода (функции предобработки, определения моделей, инференс и т.д.).

Использование пакета минимизирует дублирование и обеспечивает единый источник истины для операций с данными.

В проектах по науке о данных некоторые действия повторяются во всех workflow: чтение файлов, трансформация данных, определения моделей. Дублирование в ноутбуках или скриптах утомительно. Модуль позволяет написать код один раз и импортировать везде.

Это также снижает ошибки: исправление бага в модуле автоматически затрагивает все импортирующие скрипты и ноутбуки.

2.1.3 Гибкость

Структура не идеальна и не полна. Не обязательно использовать все от ccds; ее следует адаптировать под нужды проекта. Шаблон дает отличную отправную точку для настройки.

2.2 Контроль версий

Git стал indispensable для проектов с кодом. Он отслеживает изменения, позволяет откатываться и, с GitHub, облегчает командную работу.

Git — это машина времени, исправляющая ошибки в коде. Сегодня его использование обязательно.

2.3 Три типа кода

Выбор между скриптами Python и Jupyter-ноутбуками — предмет споров в сообществе по науке о данных. Здесь представлена позиция по этому вопросу.

Код разделяется на три директории:

1. Модуль
2. Скрипты
3. Ноутбуки

2.3.1 Модуль

Модуль содержит все ключевые функции и классы.

Он минимизирует избыточность и создает единый источник для важных операций с данными.

В проектах некоторые операции повторяются: чтение данных, трансформации, определения моделей. Дублирование скучно. Модуль позволяет писать код раз и импортировать.

Это уменьшает ошибки: фикс бага в одном месте обновляет все.

2.3.2 Скрипты

Директория скриптов содержит .py-файлы — единственный источник генерации выходных данных проекта. Они интерфейс для взаимодействия с модулем.

Основные применения: обучение и инференс. Модели создаются запуском скриптов, подачи на Kaggle — тоже.

Скрипты обеспечивают воспроизводимость. Для повторения старого результата клонируется версия репо и запускается соответствующий скрипт.².

Поскольку скрипты запускаются из CLI, библиотеки для аргументов упрощают код. Для простых — typer, для сложных — hydra (подробнее ниже).

2.3.3 Ноутбуки

Jupyter-ноутбуки идеальны для исследования и прототипирования благодаря быстрой обратной связи.

Часто код начинается в ноутбуке для теста и выявления ошибок, затем переносится в модуль.

Однако ноутбуки не подходят для финальных результатов: трудно воспроизводить и отслеживать изменения. Всегда используйте скрипты для выходных данных.

3 Запуск кодовой базы на Kaggle

С учетом описанной структуры для запуска на Kaggle следуют шаги:

1. Клонирование репо
2. Установка пакетов
3. Запуск скрипта

Kaggle предоставляет интерфейс Jupyter-ноутбуков, но с ограничениями на интернет, подачи не так просты, как локальный запуск. Ниже описаны шаги для Kaggle.

3.1 Клонирование репо

Прямое клонирование с GitHub в ноутбуке подачи невозможно из-за ограничений интернета. Однако Kaggle позволяет импортировать выходы других ноутбуков. Решение: создать отдельный ноутбук для клонирования и установки, импортировать его выход в основной.

Для приватного репо используйте personal access token (PAT) с GitHub по руководству. Создайте PAT специально для Kaggle с минимальными правами.

В ноутбуке клонирования код:

from kaggle_secrets import UserSecretsClient
user_secrets = UserSecretsClient()
github_token = user_secrets.get_secret("GITHUB_TOKEN")
user = "YOUR_GITHUB_USERNAME"
CLONE_URL = f"https://oauth2:{github_token}@github.com/{user}/YOUR_REPO_NAME.git"
get_ipython().system(f"git clone {CLONE_URL}")

Этот код скачивает репо в рабочую директорию. PAT хранится в секрете Kaggle GITHUB_TOKEN. Активируйте секрет в настройках перед запуском.

3.2 Установка пакетов

В том же ноутбуке устанавливайте пакеты. Для uv соберите модуль и зависимости:

cd ariel-2025 && uv build

Это создает wheel в dist/. Установите в кастомную директорию:³

pip install /path/to/wheel/file --target /path/to/custom/dir

Замените пути: wheel в REPO_NAME/dist/, custom_dir — любая. Запомните путь для импортов в других ноутбуках.

Клонирование и установка в одном ноутбуке, названном как репо, упрощает импорт.

3.3 Запуск скрипта

В последующих ноутбуках импортируйте ноутбук с репо: Kaggle сохранит /kaggle/working/ в /kaggle/input/REPO_NAME/, где REPO_NAME — имя репо.⁴.

Скрипты часто генерируют выходы относительно своих путей. /kaggle/input/ — только чтение, копируйте в /kaggle/working/ (чтение-запись):

cp -r /kaggle/input/REPO_NAME/REPO_NAME/ /kaggle/working/

Прямой запуск из /kaggle/working/scripts/ вызовет ошибки импорта. Обновите PYTHONPATH и запустите:

! export PYTHONPATH=/kaggle/input/REPO_NAME/custom_dir:$PYTHONPATH && cd /kaggle/working/REPO_NAME/scripts && python your_script.py --arg1 val1 --arg2 val2

Называйте ноутбук по имени скрипта. При перезапуске версионируйте хешем Git-коммита для отслеживания.⁵.

3.4 Сбор всего вместе

Нужны два ноутбука:

1. Клонирующий: клонирует репо и устанавливает пакеты.
2. Скриптовый: запускает скрипт.

Могут потребоваться дополнительные для пайплайна, напр. для обучения и инференса, с той же структурой.

Разделение шагов (предобработка, обучение, инференс) полезно для долгих этапов. В Ariel Data Challenge предобработка занимала >7 часов. В одном ноутбуке это замедлило бы итерации, а лимиты Kaggle сделали бы невозможным полный запуск.

Каждый ноутбук импортирует выход предыдущего. Делайте пути к файлам/моделям аргументами скриптов для гибкости.

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

3.5 Стоит ли усилий?

Однозначно да!

Пайплайн добавляет начальный overhead, но экономит время долгосрочно. Код пишется локально и запускается на Kaggle без конфликтов.

Для новой модели копируйте скриптовый ноутбук и меняйте скрипт. Изменения отслеживаются Git. Старые результаты воспроизводятся чеком аутом коммита и перезапуском ноутбуков.

Разработка возможна на любой машине: локально, в облаке или на Kaggle. Все централизовано в GitHub, окружение едино.

Это малая цена за удобство. После настройки фокус на исследованиях и моделях!

4 Фиксация знаний и исследований

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

4.1 Отслеживание чтения

Rajpurkar (2023) рекомендует список всех прочитанных статей и бумаг. Это позволяет обзору и быстрому возврату.

Аннотируйте звездами: 1 — нерелевантно (не знали заранее), 2 — релевантно, 3 — высоко релевантно. Для быстрой фильтрации.

Ведите заметки по каждой: как относится к проекту, кратко, но с ключевыми идеями. Связывайте заметки с бумагами в списке.

Храните аннотации: highlights в PDF или на e-Ink, сохраняйте аннотированные версии и ссылайтесь. Для бумажных — сканируйте.

4.2 Инструменты

Для документов предпочтительны Google Docs: доступ везде, поддержка Markdown (используется здесь).

Zotero — отличный для бумаг: хранение, организация. Коллекции по проектам, импорт через расширение браузера, экспорт в BibTeX прост.

5 Отслеживание экспериментов

В проектах по науке о данных проводятся множество экспериментов. Легко запутаться.

Структура кода и скрипты — шаг вперед, но есть инструменты для улучшения.

5.1 Wandb

Weights and Biases (wandb) — инструмент для трекинга экспериментов (произносится “w-and-b”, “wand-b” или “wan-db”). Сохраняет конфигурации и результаты в центре.

Wandb дает дашборд для сравнения результатов, гиперпараметров, кривых обучения. Отслеживает метрики: GPU, CPU.

Интегрируется с Hugging Face, упрощая трекинг с transformers.

При множестве экспериментов wandb indispensable.

5.2 Hydra

Hydra от Meta упрощает управление конфигурациями. Определяет в YAML, переопределяет из CLI.

Гибкий для случаев. Руководство по использованию для экспериментов.

6 Полный процесс

Figure 2 суммирует процесс. Сначала исследуются идеи, фиксируются знания. Затем эксперименты в локальных Jupyter-ноутбуках. При рабочей идее код рефакторится в модуль, создаются скрипты. Эксперименты запускаются на Kaggle. Результаты трекаются.

Благодаря трекингу предвидятся проблемы, быстрый возврат к исследованиям или разработке.

7 Заключение

Беспорядок — источник всех бед в проектах по науке о данных. Для надежной воспроизводимой работы нужна организация и ясность процессов. Соревнования Kaggle — не исключение.

В статье рассмотрены техники организации кодовой базы, советы по трекингу исследований и инструменты для экспериментов. Figure 2 суммирует подход.

7.1 Ссылки

Drivendata. (2022). The 10 Rules of Reliable Data Science.

Rajpurkar, P. (2023). Harvard CS197: AI Research Experiences. https://www.cs197.seas.harvard.edu

Сноски

1. Структура папок скопирована с сайта ccds на момент публикации.
2. Предполагается использование seed во всех генераторах случайных чисел.
3. При запуске bash-команд в ячейке Jupyter префиксуйте !.
4. В Kaggle текущая директория — /kaggle/working/. Предыдущие cd игнорируются. Указывайте пути от /kaggle/working/ или начинайте с cd PATH &&.
5. Если забыли путь, скопируйте из вкладки ноутбука в правой панели.
6. При обновлении перезапустите клонирующий ноутбук, проверьте обновления перед скриптовым.