Speaker Retrieval Hackathon Repo

Репозиторий для хакатонного решения по устойчивому поиску ближайших голосовых соседей в искажённом аудио. Каркас сразу заточен под uv, Docker, эксперименты в отдельных ветках и воспроизводимый CLI.

Что уже заложено

• main для стабильных состояний, dev для интеграции, exp/* для отдельных экспериментов.
• GPU-first Docker на Ubuntu 20.04 с Python 3.13.
• единый Python-корень source/ для всего кода;
• YAML-конфиги в configs/;
• журнал экспериментов в experiments/README.md;
• базовый CLI:
  • train
  • infer
  • validate-submission

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

.
├── README.md
├── pyproject.toml
├── uv.lock
├── Dockerfile
├── compose.yaml
├── configs/
├── data/
│   ├── organizers/
│   ├── external/
│   ├── processed/
│   └── cache/
├── experiments/
│   ├── README.md
│   └── templates/
├── source/
├── tests/
└── outputs/

Быстрый старт локально

Требования:

• установлен uv;
• доступен Python 3.13 через uv;
• Git и Docker поставлены локально.

Установка:

uv sync --all-groups
uv run pre-commit install

Проверка:

uv run python -m source.cli --help
uv run pytest

Docker

Сборка:

docker compose build

Запуск dev-контейнера:

docker compose run --rm app

Образ:

• базируется на Ubuntu 20.04;
• ориентирован на GPU-сценарий;
• ставит Python 3.13 через uv.

Данные

В git не коммитятся:

• конкурсные аудиофайлы;
• внешние датасеты;
• кэши и препроцессинг;
• веса моделей и чекпойнты;
• submission.csv.

Назначение каталогов:

• data/organizers/ — исходные данные от организаторов и их manifests;
• data/external/ — внешние открытые датасеты, manifests и заметки по лицензиям;
• data/processed/ — промежуточные данные, препроцессинг, шардирование;
• data/cache/ — временные кэши даталоадеров и пайплайнов;
• outputs/ — предсказания, логи, служебные результаты запуска.

Подробности по раскладке данных лежат в README внутри этих папок.

Конфиги

Рекомендуемая логика:

• configs/data/ — расположение данных и manifests;
• configs/train/ — параметры обучения;
• configs/infer/ — параметры инференса и формата submission.

В стартовом шаблоне поле submission.path_column выставлено в auto: CLI возьмёт имя колонки пути из входного manifest-файла, чтобы не конфликтовать с шаблоном организаторов.

Базовые команды

Обучение:

uv run python -m source.cli train --config configs/train/baseline.yaml

Инференс:

uv run python -m source.cli infer \
  --config configs/infer/baseline.yaml \
  --input-dir data/organizers \
  --input-csv data/organizers/test_public.csv \
  --output outputs/submission.csv

Проверка submission:

uv run python -m source.cli validate-submission --submission outputs/submission.csv

Сейчас infer реализован как smoke-ready заглушка: он создаёт корректный по структуре submission.csv, чтобы можно было отладить репозиторий, CI и формат вывода до интеграции настоящей модели.

Политика веток

Целевой поток:

main <- dev <- exp/*

Правила:

• прямой push в main запрещён;
• основная разработка идёт в dev;
• каждый эксперимент открывается из dev в ветке exp/YYYYMMDD-short-name;
• удачные эксперименты вливаются в dev;
• только стабильное состояние попадает из dev в main.

Пример жизненного цикла:

git switch dev
git pull --ff-only
git switch -c exp/20260411-baseline-retrieval

Для каждого эксперимента нужно:

1. создать папку experiments/EXP-YYYYMMDD-short-name/;
2. заполнить README.md с гипотезой, конфигами и метриками;
3. обновить журнал в experiments/README.md.

GitHub-настройки, которые нужно включить вручную

Через GitHub UI для веток main и dev:

• Require a pull request before merging;
• запрет прямого push;
• запрет force push;
• обязательный зелёный CI для merge в main.

Эксперименты

Журнал и правила ведения экспериментов:

• experiments/README.md
• experiments/templates/experiment-report.md

Что дальше

Следующий слой разработки:

1. подключить реальный speaker embedding backend;
2. реализовать train/infer pipeline поверх конфигов;
3. добавить retrieval и локальную валидацию на Precision@K;
4. завести первые exp/* ветки под baseline-модель и аугментации.