# Участнику: обучаем марсоход и отправляем решение

## Что за задача

Марсоход видит датчики, выбирает действия и получает награду за поведение. **Обучение
с подкреплением (RL)** меняет нейросеть так, чтобы действия приносили больше награды.
В шаблоне уже есть **PPO** — алгоритм обучения, и **GRU** — сеть с памятью о прошлых
попытках. Начать можно с готового решения, без опыта RL или Kubernetes.

Один тестовый мир даёт 120 секунд **времени симуляции**. После гибели ровер начинает
снова, но часы не сбрасываются; память сети сохраняется. В новом мире память очищается.
Score — средняя максимальная координата X за испытания, до 800 метров. Больше — лучше.
Два часа **реального времени** на обучение — отдельный серверный бюджет.

## 1. Войдите и подготовьте ZIP

Войдите на сайте через Authentik. Организатор привяжет университетский или временный
аккаунт к команде. В локальном тестовом стенде вместо Authentik используется выданная
пара логин/пароль. Данные для Harbor и Docker push вам не нужны.

Скопируйте каталог `participant` и изменяйте его содержимое. Минимальный пакет:

```text
solution.zip
├── Dockerfile
├── train.py
├── README.md
└── biomes/       # необязательно: собственный банк только для обучения
```

`Dockerfile` описывает, какие файлы и библиотеки попадут в контейнер. **Образ** —
собранная программа с библиотеками; **контейнер** — её запуск. Сборку и хранение образа
в Harbor выполняет платформа. Начало Dockerfile строго фиксировано:

```dockerfile
FROM arena-base
USER root
WORKDIR /submission
COPY . /submission/
# Если нужна дополнительная библиотека:
# RUN python -m pip install package==version
USER 10000:10000
CMD ["python", "/submission/train.py"]
```

`arena-base` сервер заменяет на контрольную сумму подготовленного образа организаторов.
В нём уже есть Python 3.12, PyTorch, публичная среда и код GRU/PPO. Родитель — указанный
организаторами CUDA 13.3.1 / Ubuntu 26.04 image. Нельзя менять FROM, добавлять stages,
Dockerfile frontend extensions, COPY --from или специальные RUN --mount/--security.
Обычные RUN, COPY, WORKDIR, ENV, USER, CMD, ENTRYPOINT, LABEL разрешены.

Библиотеки ставьте на этапе RUN: у обучения нет интернета. Сборка имеет ограниченный
доступ к HTTPS package sources. HTTP-only репозитории не поддерживаются; фиксируйте
версии зависимостей. Не используйте heredoc Dockerfile; многострочные команды с `\`
поддерживаются. Дополнительный код можно разнести по модулям и включить в ZIP.

Упаковка из корня платформы (достаточно обычного Python):

```bash
python scripts/package.py --source participant --output solution.zip
```

Можно создать ZIP и обычным архиватором. Обязательные файлы должны быть **в корне**,
а не внутри ещё одного каталога. Максимум 32 МиБ ZIP / 128 МиБ распакованных файлов /
512 файлов; ссылки и специальные файлы запрещены. Не кладите секреты, .venv, Git,
готовые .pt или safetensors. Упаковщик исключает типичные лишние файлы.

## 2. Сохраните именованную версию

На сайте укажите название, например «PPO — экономия энергии», выберите ZIP и нажмите
«Сохранить версию». Название остаётся вашим, номер версии присваивается автоматически.
Изменённый ZIP под тем же названием создаёт v2, v3 и далее. Идентичный ZIP с тем же
названием возвращает уже существующую версию — повторная загрузка не нужна.

Сохранённую версию нельзя незаметно переписать. Её исходный ZIP можно скачать.
На команду выделено до 100 версий и суммарно 256 МиБ исходных ZIP. Сохранение версии
само по себе не расходует квоту обучения.

## 3. Запустите обучение и следите за ходом

Нажмите «Собрать и обучить». Этапы:

1. **Очередь сборки / сборка** — сервер проверяет Dockerfile и устанавливает зависимости.
2. **Harbor** — доверенный процесс сохраняет готовый образ с фиксированным digest.
3. **Очередь GPU / обучение** — образ запускается на свободной RTX 5090.
4. **Оценка** — контейнер участника удаляется; другой процесс читает только веса.
5. **Готово / ошибка** — появляется score либо объяснение проблемы.

Кнопка «Журнал» открывает события и последние 256 КиБ stdout/stderr сборки или обучения.
Обновление раз в 5 секунд. Используйте `print(..., flush=True)`; можно печатать loss,
reward, шаги и свою оценку прогресса. Общий процент обучения не вычисляется автоматически:
у каждого алгоритма свой формат. Baseline уже печатает JSON-метрики после обновлений.

## 4. Что менять в обучении

В `train.py` начните с learning_rate, entropy, числа кадров, числа параллельных сред,
seed или shaping награды. Меняйте по одному параметру и записывайте гипотезу в README.
Алгоритм обучения свободный; inference контракт фиксирован: **GRU-128**, действия и
preprocessing из [PROTOCOL.ru.md](PROTOCOL.ru.md). Менять форму сети нельзя.

`ARENA_SEED` передаёт выбранный на сайте seed. Baseline его использует; свой алгоритм
должен сам применить его к Python/NumPy/PyTorch и генератору среды. Повтор с другим seed
полезен из-за случайности обучения; повтор с тем же seed полезен для воспроизводимости.
Сервер не может гарантировать, что произвольный скрипт соблюдает seed.

Собственный банк разрешён **только для обучения**. В текущей среде банк скомпилирован
в C++, поэтому одного JSON недостаточно. Если меняете банк, включите соответствующий
header/manifest или исходную среду в ZIP и пересоберите расширение через RUN. Для
внешнего include поддерживается `MARS_ROVER_BANK_INCLUDE`. Не меняйте observation/action
контракт. Локальная валидация доступна на публичных биомах; серверные тесты независимо
выбирают банк организаторов и не читают ваши biomes.

## 5. Результат, повторный запуск и финал

Обязательный результат — `/output/policy.safetensors`. Экспорт через
`arena.protocol.export` встроен в шаблон после каждого обновления. Формат pickle .pt,
ONNX или исполняемый Python policy на оценку не принимаются. Размер весов ≤4 МиБ.
Процесс обучения запускается как `python /submission/train.py`, независимо от CMD,
UID/GID 10000. Root filesystem read-only; пишите в `/tmp` и `/output`.

После завершения можно нажать «Обучить снова» у той же версии. Создаётся **новый запуск**
с отдельным seed, логами, весами и score. Уже собранный образ берётся из Harbor, повторная
сборка не нужна. Повтор расходует ту же квоту, что новый запуск: 5 за последние 24 часа,
один активный запуск команды, до 2 часов обучения. Ошибочные принятые запуски тоже
расходуют квоту. Работа завершается с exit code 0 до дедлайна; baseline пытается
остановиться после очередного обновления примерно на 110-й минуте.

По умолчанию финальный — **лучший успешный запуск** команды на public suite. Кнопка
«В финал» переопределяет этот выбор. Кнопка «Выбирать лучший автоматически» возвращает автоматический выбор. В финале повторно оцениваются сохранённые веса
на закрытом наборе, без нового обучения. Равный точный score — совместное место.

## Частые ошибки

| Этап | Что проверить |
|---|---|
| ZIP / Dockerfile | Обязательные файлы в корне, размер, FROM arena-base, допустимые инструкции |
| Build / pip | Название и версия пакета, наличие Linux/amd64 wheel, C++ зависимости; подробности в build log |
| Harbor | Ошибка registry относится к площадке; сообщите ID организатору |
| Pending | Очередь, нехватка CPU/RAM/GPU, image pull; причина в событиях |
| OOMKilled | Уменьшите число сред/размер батча/буферы: RAM или VRAM исчерпаны |
| Exit code / deadline | Исправьте traceback в train log; сохраняйте веса и завершайтесь до 2 часов |
| Веса отсутствуют | Используйте точное имя /output/policy.safetensors |
| Shape/dtype/NaN | Сохраните GRU-128, float32, rms.mean/rms.var; проверьте численную устойчивость |
| 409 / 429 | Уже есть активный запуск / достигнута квота |
| Ошибка закрытой среды | Передайте ID организатору; внутренние тестовые данные участникам не выдаются |

## Как начать эксперимент, если RL для вас новое

Сначала отправьте неизменённый baseline и сохраните его score. Затем сформулируйте
одну гипотезу, например «более осторожные обновления весов помогут обучению».
В `ppo.Config(...)` добавьте `learning_rate=1e-4` вместо значения по умолчанию 3e-4.
Сохраните отдельную версию с понятным именем и запустите с тем же seed. Сравнивайте
не только последний training reward, но и серверный score: награда при обучении
может расти без улучшения способности проходить новые миры.

- **Learning rate** — размер шага изменения весов. Слишком большой шаг может ломать
  уже найденное поведение; слишком маленький замедляет обучение.
- **Entropy** — поощрение разнообразия действий. Помогает исследовать среду,
  но чрезмерное значение мешает закрепить полезную стратегию.
- **Batch** — порция опыта для одного обновления. Большие буферы требуют больше RAM/VRAM.
- **Seed** — начальное состояние генераторов случайных чисел. Несколько seed помогают
  отличить устойчивое улучшение от удачного запуска; каждый запуск расходует квоту.
- **Validation** — проверка на других мирах. Не пытайтесь угадать конкретные скрытые
  карты: старайтесь обучить правило поведения, которое переносится на новые биомы.

В README записывайте алгоритм, изменённый параметр, причину изменения и наблюдение.
Для первых опытов хватит 2–3 осмысленных изменений; сложный DevOps не требуется.