Три файла: prepare.py, train.py, program.md
Вся структура держится на трёх файлах. prepare.py — фиксированная подготовка (загрузка данных, обучение токенизатора, утилиты), его не трогают. train.py — единственный редактируемый файл с архитектурой GPT, оптимизатором (Muon + AdamW), циклом обучения; здесь «всё в игре»: архитектура, гиперпараметры, размер батча, размер модели. program.md — базовые инструкции агенту, которые правит человек, чтобы задать направление. Понимание этого разделения и есть ответ на вопрос «как агент ищет улучшения и где у него рамки».
Три файла: prepare.py, train.py, program.md
В предыдущем подмодуле мы разобрали цикл: гипотеза → правим код → 5 минут обучения → смотрим val_bpb → оставляем или откатываем. Теперь — как именно устроено то, что агент правит и что читает. Вся конструкция держится на трёх файлах, и понимание их разделения — это и есть ответ на вопрос «где у агента свобода, а где рамки».
flowchart LR
H[👤 Человек] -->|редактирует| PM[program.md\nИнструкции агенту]
PM -->|читает| AG[🤖 Агент]
AG -->|единственный\nфайл для правки| TR[train.py\nМодель + оптимизатор\n+ цикл обучения]
TR -->|запускает| RUN[uv run train.py\n→ run.log]
RUN -->|парсит метрику| AG
PR[prepare.py\nДанные + токенизатор\n+ eval-утилиты] -->|импортируется| TR
PR -.->|❌ нельзя менять| AG
style PR fill:#f0f0f0,stroke:#999
style PM fill:#e8f4e8,stroke:#4a9
style TR fill:#e8eaf6,stroke:#57a---
prepare.py — фундамент, который не трогают
prepare.py — это инфраструктура разового запуска. Он делает три вещи:
1. Скачивает обучающие данные — сырые шарды из Hugging Face (датасет climbmix-400b-shuffle) с retry-логикой и параллельными воркерами.
2. Обучает BPE-токенизатор — используя библиотеку rustbpe, сохраняет его и таблицы побайтовых длин для честной оценки.
3. Предоставляет утилиты рантайма — датачитер с «best-fit packing» (упаковывает документы без лишнего паддинга) и функцию подсчёта val_bpb.
Последний пункт критически важен: именно в prepare.py живёт логика вычисления метрики. Агенту запрещено его менять — иначе он мог бы «улучшить» val_bpb, просто подправив формулу. Это защита от читерства.
Практически: вы запускаете prepare.py один раз перед стартом авторесёрча, и дальше он просто лежит нетронутым.
---
train.py — единственная арена
Это единственный файл, который агент имеет право редактировать. Посмотрим, что внутри.
Модель. Классический GPT-стек: CausalSelfAttention с ротационными эмбеддингами (RoPE) и flash-attention, MLP с двумя проекциями, Block с residual-соединениями и layer norm, и GPT — основной класс, который всё это собирает. Дата-класс GPTConfig задаёт форму модели: длину последовательности (по умолчанию 2048), размер словаря, число слоёв, голов, размерность эмбеддингов.
Оптимизатор. Гибридная схема:
- Muon — для двумерных матричных параметров (веса слоёв внимания и MLP). Использует momentum Нестерова и полярную ортогонализацию.
- AdamW — для эмбеддингов, выходной головы и скалярных параметров.
Базовая конфигурация. 8 слоёв, aspect ratio 64, батч — 524 тысячи токенов за шаг с градиентной аккумуляцией.
Цикл обучения. Тренировочный луп сам следит за оставшимся бюджетом времени, обрывает прогон если loss взрывается или уходит в NaN, и логирует val_bpb и peak_vram_mb — именно эти строки агент потом парсит из run.log.
Всё, что в этом файле, — «в игре»: агент может поменять архитектуру, добавить слой, сменить функцию активации, уменьшить батч, попробовать другой schedule для lr. Рамка одна — 5 минут на GPU.
---
program.md — мост между человеком и агентом
program.md — это то, что человек пишет для агента. Не Python-код, не конфиг, а текст на естественном языке: что делать, в каком порядке, какие правила соблюдать.
Файл структурирован в две части.
Setup — что агент делает один раз в начале:
- заводит датированную ветку
autoresearch/<tag> - читает
README.md,prepare.py,train.py— чтобы понять текущее состояние - проверяет, что данные скачаны
- инициализирует
results.tsvс заголовком для записи результатов
Экспериментальная петля — то, что агент крутит до остановки:
1. смотрит текущий git-статус
2. вносит изменение в train.py, коммитит
3. запускает uv run train.py > run.log 2>&1
4. извлекает метрики: grep "^val_bpb:|^peak_vram_mb:" run.log
5. если val_bpb улучшился — ветка продвигается (коммит остаётся)
6. если нет — git reset к предыдущему состоянию
7. записывает результат в results.tsv
8. повторяет
И финальная директива автономности: агент не останавливается и не задаёт вопросов — работает до ручной остановки.
Человек редактирует program.md, чтобы задать направление: например, вписать «сосредоточься на снижении числа параметров» или «попробуй альтернативы RoPE». Это ваш рычаг управления без правки Python.
---
Почему такое разделение работает
Три файла решают три разные задачи одновременно:
| Файл | Кто меняет | Зачем фиксировать |
|---|---|---|
prepare.py | Никто | Защита честности метрики |
train.py | Агент | Пространство экспериментов |
program.md | Человек | Направление без лишнего контроля |
Если бы агент мог трогать prepare.py — он мог бы сломать оценку. Если бы человек был вынужден писать Python для задания направления — порог входа был бы высок. Разделение элегантно: каждый участник работает в своей зоне ответственности.
---
Мини-проверка
Поставьте себе мысленный вопрос: если вы хотите, чтобы агент уделял больше внимания вариантам без RoPE — в какой файл вы идёте? Ответ: program.md, и только туда. Если хотите посмотреть, как устроен датачитер — prepare.py, только читать. Если хотите сами попробовать одно изменение руками — train.py, та же арена, что и у агента.
Самопроверка
- Метрика val_bpb вычисляется в prepare.py, и агент не имеет права его менять. Почему?
- Где хранится гибридная схема оптимизатора (Muon для матриц, AdamW для скаляров)?
- Если человек хочет направить поиск агента на более компактные модели, в какой файл он пишет это направление?
- После каждого 5-минутного прогона агент парсит метрики из run.log. Какие значения он ищет?
- Стратегия упаковки документов (best-fit packing) в prepare.py не редактируется агентом. Что это означает?
- Раздел Setup в program.md описывает разовые действия перед экспериментальным циклом. Какое действие НЕ входит в Setup?
- Разделение трёх файлов (prepare.py недоступен, train.py редактируется агентом, program.md пишет человек) защищает в первую очередь что?
Домашние задания
Определите правильный файлtext
Четыре ситуации. Для каждой решите: какой из трёх файлов (prepare.py, train.py, program.md) вы отредактируете или можете ли вообще трогать. Объясните логику. 1. Логика подсчёта val_bpb выглядит вам ошибочной для многобайтовых символов. 2. Вы хотите, чтобы агент сосредоточился на поиске альтернатив RoPE вместо стандартных ротационных эмбеддингов. 3. Размер батча 524K токенов кажется вам чрезмерным — вы хотите его уменьшить. 4. Функцию активации в MLP можно менять: попробовать SiLU вместо GELU. Для каждого пункта назовите файл и объясните: почему именно этот файл (или почему его нельзя трогать).
Правильно определяет файл для каждой ситуации (1 → prepare.py нельзя, 2 → program.md, 3 и 4 → train.py). Объясняет логику: какая защита или роль стоит за выбором. Показывает понимание трёх ролей файлов: prepare.py (защита честности метрики), train.py (арена экспериментов агента), program.md (рычаг управления человека).
Напишите директиву для агентаtext
Вы заметили, что размер модели растёт, а качество (val_bpb) растёт медленнее. Похоже, большинство параметров — пустая трата памяти. Вы решаете направить агента на исследование компактных архитектур. Напишите фрагмент program.md (3–6 строк на естественном русском языке), который объяснит агенту, что ищет, и как это проверять. Не пишите Python-код. Это инструкции, на основе которых агент сам будет генерировать гипотезы и менять train.py.
Директива чётко формулирует исследовательскую цель (компактность, эффективность параметров). Написана на русском языке, не на Python. Достаточно конкретна, чтобы агент понял, что искать, но не настолько, чтобы вы сами писали код изменений. Упоминает релевантные метрики (val_bpb, параметры, возможно peak_vram_mb). Согласуется с циклом из статьи: гипотеза → код → метрики → решение оставить или откатить.
Проследите полный циклtext
Вернитесь к директиве из предыдущего задания. Представьте, что агент её прочитал и начал первый шаг цикла. 1. Как агент интерпретирует 'компактную архитектуру'? Какую конкретную гипотезу он может выдвинуть на основе вашего текста? 2. Какое реальное изменение в train.py это может вызвать? Опишите суть (не нужен полный код): например, какие параметры модели могут измениться? 3. Агент запускает `uv run train.py > run.log 2>&1` и ждёт 5 минут. Какие две метрики он потом парсит из этого лога? 4. val_bpb улучшился на 0.002. Что происходит в следующие секунды? 5. Агент сформировал результат этого шага. Где это записывается? Ответьте связным текстом или по пунктам.
Объясняет механизм: как текст на русском в program.md становится Python-изменениями в train.py. Приводит конкретный пример архитектурного изменения (например, сокращение числа слоёв, голов внимания, размерности). Правильно называет две метрики: val_bpb и peak_vram_mb. Объясняет механизм обратной связи: улучшился → коммит остаётся, нет → git reset. Упоминает results.tsv как хранилище логика всех попыток за сессию.
Сдача и проверка заданий — в приложении Learn (Almost) Anything.