fnn

Описать эксперимент в JSON-конфиге.
Запустить обучение через main.py.
Получить артефакты эксперимента в отдельной папке.
При необходимости продолжить обучение из checkpoint или запустить инференс через chat.py.

Что есть в репозитории

main.py — CLI для запуска эксперимента обучения.
chat.py — CLI для инференса по сохранённым артефактам эксперимента.
src/fnn.py — реализация модели FNN.
src/runner.py — orchestration: загрузка конфига, подготовка датасета, создание модели, trainer, сохранение артефактов.
src/configs.py — Pydantic-схемы конфигурации эксперимента.
configs/ — примеры конфигов.
experiments/ — результаты запусков.
tests/ — автотесты.

Требования

Python 3.12+
uv как package manager и runner
PyTorch-совместимое окружение

Установка зависимостей:

Быстрый старт

Запуск эксперимента:

Или через переменную окружения:

Запуск инференса по сохранённому эксперименту:

Как запускается эксперимент

Команда:

main.py

принимает один обязательный параметр:

config — путь к JSON-конфигу эксперимента.

Пример:

Во время запуска

src.runner.run_experiment(...)

делает следующее:

Загружает ExperimentConfig из JSON.
Фиксирует seed для Python и Torch.
Создаёт директорию эксперимента <experiments_root>/<config.name>.
Копирует туда:
- исходный config.json
- tokenizer.json
- snapshot исходников src.zip
Собирает train/val датасеты.
Создаёт модель FNN по секции model.
Если существует model/chkpt.pth, автоматически загружает checkpoint в модель.
Создаёт Trainer по секции training.
Запускает обучение и валидацию.
Сохраняет итоговые метрики в metrics.json.

Параметры запуска и поведение runner

CLI `main.py`

Параметр CLI:

config — путь к JSON-файлу конфигурации эксперимента.

Если параметр CLI не передан,

main.py

использует

FNN_EXP_CONFIG

. Если заданы оба источника, CLI имеет приоритет.

Переменные окружения

Поддерживается переменная окружения:

FNN_EXP_FOLDER — корневая папка для артефактов экспериментов.
FNN_EXP_CONFIG — путь к JSON-конфигу эксперимента, если он не передан через CLI.

По умолчанию все результаты сохраняются в

experiments/<name>

Пример сохранения запусков в

runs/

Тогда артефакты попадут в:

Важно: этот же путь используется и для автоматического resume из checkpoint.

Docker

В репозитории добавлены:

Dockerfile — образ приложения для запуска эксперимента на CUDA GPU
docker-compose.yml — основной compose-файл для запуска контейнера приложения и optional ClearML-режима

Основной сервис

app

использует:

FNN_EXP_CONFIG=/workspace/configs/example_config.json
FNN_EXP_FOLDER=/workspace/experiments
FNN_DATA_FOLDER=/workspace/data

Тома в compose:

./experiments -> /workspace/experiments
./configs -> /workspace/configs
./data -> /workspace/data

Запуск эксперимента в контейнере:

Контейнер запускает:

При этом

main.py

читает конфиг из

FNN_EXP_CONFIG

, артефакты пишет в

FNN_EXP_FOLDER

, а данные должны быть доступны внутри контейнера по пути

FNN_DATA_FOLDER

GPU

docker-compose.yml

для основного сервиса задано:

gpus: all
NVIDIA_VISIBLE_DEVICES=all
NVIDIA_DRIVER_CAPABILITIES=compute,utility

Для запуска нужен

nvidia-container-toolkit

и рабочий Docker runtime с поддержкой GPU.

Optional ClearML

По умолчанию контейнер использует локальный logger backend и пишет артефакты только в папку эксперимента.

Если нужен ClearML, используйте профиль

clearml

В этом режиме:

FNN_USE_CLEARML=1
FNN_CLEARML_PROJECT=fnn
CLEARML_API_HOST
CLEARML_WEB_HOST
CLEARML_FILES_HOST

По умолчанию compose ожидает, что ClearML server доступен с хоста через

host.docker.internal

. При необходимости эти адреса можно переопределить через переменные окружения shell перед запуском

docker compose

Конфигурация эксперимента

Полная схема задаётся моделями в src/configs.py.

Подробная справка по полям и практическим ограничениям: docs/experiment-config-reference.md.

Корневой объект:

Корневые поля

name — уникальное имя эксперимента; имя папки с артефактами.
description — произвольное текстовое описание.
model — параметры модели FNN.
training — параметры обучения.
transforms — опциональные входные преобразования.
data — параметры датасета и токенизатора.

Секция `model`

Поля:

name — имя модели, используется в логах и артефактах.
input_size — длина входного окна модели. Должна быть положительной степенью двойки.
emb_size — размер токенных эмбеддингов.
vocab_size — размер словаря.
channels — число каналов в FastNN блоках.
kernel_size — размер ядра внутренних преобразований.
layers — число повторений блока FastNN.
pad_token_id — id pad-токена.

Замечания:

input_size критичен: модель валидирует, что это степень двойки.
vocab_size должен соответствовать реальному размеру токенизатора.
pad_token_id должен совпадать с tokenizer.json.

Секция `training`

Поля:

learning_rate — learning rate optimizer.
theta — коэффициент регуляризации модели.
weight_decay — weight decay optimizer.
dropout — поле присутствует в конфиге, но текущий runner напрямую его не использует.
batch_size — размер batch.
epochs — количество эпох.
device — устройство для обучения, например cpu, cuda, cuda:0. Если null, выбор остаётся за Trainer.
shuffle — перемешивать ли train dataset.
save_on_step — как часто сохранять checkpoint по шагам; null отключает периодическое сохранение.
model_folder — поле в конфиге есть, но текущий runner сохраняет checkpoint в <experiment_dir>/model и не использует это значение как источник пути.
autocast — включает mixed precision там, где это поддерживает Trainer.
load_checkpoint — поле в схеме присутствует, но текущий runner его не читает; resume сейчас происходит автоматически из <experiment_dir>/model/chkpt.pth.
compile_model — включить ли torch.compile, если это поддержано средой.
accumulation_steps — число шагов gradient accumulation.
log_on_step — частота step-level логирования.
seed — seed для воспроизводимости.

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

device
batch_size
epochs
learning_rate
save_on_step
compile_model
autocast

Секция `transforms`

Поля:

use_transforms — включает входное преобразование.
zeroize_to_pos — позиция, до которой применяется ZeroizeLeft.
zeroize_rand — использовать ли случайность при zeroize.

Если

use_transforms=false

, секция фактически игнорируется.

Секция `data`

Поля:

tokenizer_path — путь к tokenizer.json.
train_data_path — путь к train-корпусу или директории с данными.
val_data_path — путь к validation-корпусу; если null, validation будет получен split-ом train dataset.
test_data_path — зарезервировано в схеме, текущий runner не использует.
separator — разделитель между текстовыми sample-ами.
chunk_size — размер чанка при чтении корпуса.
limit — ограничение на объём считываемых данных.
output_size — длина target-окна.
val_split — доля train dataset, выделяемая под validation, если val_data_path не задан.

Практические замечания:

tokenizer_path должен указывать на токенизатор, совместимый с vocab_size и pad_token_id.
Если val_data_path не указан, runner автоматически делает split train dataset с использованием seed.
Если dataset слишком мал или val_split <= 0, validation dataset может не создаться.

Пример рабочего конфига

Артефакты эксперимента

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

Назначение файлов:

config.json — сохранённая копия фактически использованного конфига.
tokenizer.json — копия токенизатора для воспроизводимости.
src.zip — snapshot каталога src на момент запуска.
metrics.json — итоговые метрики обучения.
model/chkpt.pth — checkpoint модели.

Resume обучения

runner

автоматически пытается загрузить checkpoint из:

Это означает:

повторный запуск эксперимента с тем же name подхватит существующие веса автоматически;
если checkpoint битый или несовместимый, runner пишет warning и продолжает с новой моделью.

Если нужен полностью новый запуск, безопаснее использовать новый

name

в конфиге.

Инференс после обучения

Для генерации текста используется

chat.py

Поддерживаемые параметры:

config — путь к config.json эксперимента.
text — prompt.
--max-new-tokens — сколько токенов сгенерировать.
--temperature — температура семплирования.
--top-k — top-k filtering.
--device — override устройства для инференса.

chat.py

ищет рядом с конфигом:

tokenizer.json
model/chkpt.pth

Если рядом их нет, модуль пытается найти артефакты в стандартной папке экспериментов по

config.name

Полезные команды разработки

Запуск всех тестов:

Запуск отдельного файла тестов:

Линтер:

Проверка типов:

Типичные ошибки

input_size must be a positive power of two Причина: model.input_size не является степенью двойки.
Tokenizer file not found Причина: неверный data.tokenizer_path или отсутствует копия tokenizer.json в папке эксперимента.
checkpoint не подхватывается Причина: нет файла <experiments_root>/<name>/model/chkpt.pth или имя эксперимента изменилось.
OOM на GPU Причина: слишком большой batch_size, input_size, kernel_size или включён тяжёлый compile_model.

fnn

Описание

Языки

ISgurgutanexperiments 3-17 3 дня назад81c4c4f

FNN

Что есть в репозитории

Требования

Быстрый старт

Как запускается эксперимент

Параметры запуска и поведение runner

CLI main.py

Переменные окружения

Docker

GPU

Optional ClearML

Конфигурация эксперимента

Корневые поля

Секция model

Секция training

Секция transforms

Секция data

Пример рабочего конфига

Артефакты эксперимента

Resume обучения

Инференс после обучения

Полезные команды разработки

Типичные ошибки

Структура проекта

IS
gurgutan
experiments 3-17
3 дня назад
81c4c4f

CLI `main.py`

Секция `model`

Секция `training`

Секция `transforms`

Секция `data`