Справочник конфига

Полный список полей, типов, значений по умолчанию и правил валидации. Конфиг — это JSONC-файл: поддерживаются комментарии // … и висящие запятые. Пропущенные поля заполняются дефолтами — двустрочный JSON является валидным конфигом.

JSONC: комментарии и висящие запятые #

jsonc

{
  // строчный комментарий
  "project": "test", /* блочный комментарий */
  "train": {
    "epochs": 40,   // допустима висящая запятая
  },
}

Кузня убирает комментарии и висящие запятые перед разбором — можно писать конфиги как обычный код.

Корень #

Путь	Тип	По умолчанию	Описание
`project`	`string`	`"untitled"`	Имя проекта. Показывается в Discord и заголовке рана.
`run_name`	`string`	`"auto"`	`"auto"` — генерирует читаемое случайное имя, например `yasnyy-gorn-k3f9`.
`task`	`enum`	`"supervised"`	Тип задачи: `supervised` или `rl`.
`seed`	`int`	`1337`	Seed для воспроизводимости (torch, numpy, random). Диапазон [0, 2³¹−1].
`device`	`enum`	`"auto"`	Устройство: `auto` (выбирает CUDA > MPS > CPU), `cpu`, `cuda`, `mps`.

Раздел: `model` #

Путь	Тип	По умолчанию	Описание
`model.input_dim`	`int ≥1`	`2`	Размерность входа. При загрузке CSV/NPZ автоматически исправляется под реальные данные.
`model.output_dim`	`int ≥1`	`3`	Размерность выхода (число классов для классификации, 1 для регрессии).
`model.layers`	`layers[]`	2×linear(64)+relu	Слои скрытой части. Последний linear-head добавляется автоматически.

Типы слоёв

Тип	Параметры	Примечание
`linear`	`units` (обязательно), `bias` (bool, default true)	Полносвязный слой. Последний head добавляется автоматически.
`relu`, `gelu`, `tanh`, `sigmoid`, `silu`	—	Активационные функции без параметров.
`leaky_relu`	`negative_slope` (default 0.01)	LeakyReLU с настраиваемым наклоном.
`dropout`	`p` (default 0.1, диапазон [0, 1))	Случайное обнуление нейронов при обучении.
`batchnorm`	—	`BatchNorm1d` для линейных слоёв.
`layernorm`	—	`LayerNorm`. Нельзя использовать после `conv2d`.
`flatten`	—	Разворачивает тензор. Нужен перед `linear` после `conv2d`.
`conv2d`	`channels` (обязательно), `kernel_size` (default 3), `stride`, `padding`	Требует `python:`-хука для загрузки изображений.
`maxpool2d`, `avgpool2d`	—	Только после `conv2d`.
`lstm`, `gru`	`hidden_size` (default 64), `num_layers` (default 1), `bidirectional` (bool)	Рекуррентные слои для последовательностей.
`embedding`	`num_embeddings` (обязательно), `embedding_dim` (default 32)	Таблица эмбеддингов.

Раздел: `data` #

Путь	Тип	По умолчанию	Описание
`data.source`	`string`	`"builtin:spirals"`	Источник данных (см. форматы ниже).
`data.n_samples`	`int ≥16`	`3000`	Число семплов для встроенных генераторов. Игнорируется для CSV/NPZ.
`data.val_split`	`float [0, 0.9]`	`0.2`	Доля валидационной выборки. 0 — без валидации.
`data.batch_size`	`int ≥1`	`64`	Размер батча. Автоматически уменьшается, если больше датасета.
`data.normalize`	`bool`	`true`	Нормализация по статистикам обучающей выборки.
`data.noise`	`float ≥0`	`0.08`	Уровень шума для встроенных генераторов.

Форматы `data.source`

Формат	Пример	Описание
`builtin:*`	`builtin:spirals`	Встроенные: `spirals`, `moons`, `xor`, `blobs`, `sine`.
Путь к CSV	`data/iris.csv`	Авто-определение заголовка и разделителя. Последняя колонка — метка.
Путь к NPZ	`data/dataset.npz`	Ожидает массивы `X` и `y` (или `inputs`/`labels`).
`python:модуль:функция`	`python:mydata:load`	Функция возвращает кортеж `(X, y)`.

Раздел: `train` #

Путь	Тип	По умолчанию	Описание
`train.epochs`	`int ≥1`	`40`	Число эпох.
`train.loss`	`enum`	`"cross_entropy"`	Функция потерь (см. таблицу ниже).
`train.grad_clip`	`float ≥0`	`1.0`	Clipping градиентов. `0` — выключить.
`train.log_every`	`int ≥1`	`1`	Логировать каждые N эпох. Увеличьте до 5–10 при rate-limit Discord.

Подраздел: `train.optimizer`

Путь	Тип	По умолчанию	Описание
`train.optimizer.name`	`enum`	`"adamw"`	Оптимизатор: `adam`, `adamw`, `sgd`, `rmsprop`, `adagrad`, `nadam`.
`train.optimizer.lr`	`float [1e-8, 10]`	`0.003`	Learning rate.
`train.optimizer.weight_decay`	`float ≥0`	`0.01`	L2-регуляризация.
`train.optimizer.momentum`	`float [0, 1]`	`0.9`	Momentum (только для SGD и RMSprop; игнорируется Adam-подобными).

Подраздел: `train.scheduler`

Путь	Тип	По умолчанию	Описание
`train.scheduler.name`	`enum`	`"cosine"`	Планировщик: `none`, `cosine`, `step`, `exponential`, `plateau`, `onecycle`.
`train.scheduler.warmup_epochs`	`int ≥0`	`2`	Линейный прогрев LR. `0` — выключить. Сбрасывается в 0 если ≥ epochs.
`train.scheduler.step_size`	`int ≥1`	`10`	Шаг для `step` и half-patience для `plateau`.
`train.scheduler.gamma`	`float [0, 1]`	`0.5`	Множитель для `step`, `exponential`, `plateau`.

Подраздел: `train.early_stop`

Путь	Тип	По умолчанию	Описание
`train.early_stop.enabled`	`bool`	`true`	Включить early stopping.
`train.early_stop.metric`	`string`	`"val_loss"`	Метрика для слежения. Метрики с `acc`, `return`, `r2` — max; остальные — min.
`train.early_stop.patience`	`int ≥1`	`10`	Эпох без улучшения до остановки.
`train.early_stop.min_delta`	`float ≥0`	`0.0001`	Минимальное улучшение, которое считается прогрессом.

Подраздел: `train.checkpoint`

Путь	Тип	По умолчанию	Описание
`train.checkpoint.keep_best`	`bool`	`true`	Всегда сохранять `best.pt`.
`train.checkpoint.every_epochs`	`int ≥0`	`0`	Сохранять чекпоинт каждые N эпох. `0` — только лучший.
`train.checkpoint.metric`	`string`	`"val_loss"`	Метрика для отбора лучшего чекпоинта.

Функции потерь #

Значение	PyTorch	Когда использовать
`cross_entropy`	`CrossEntropyLoss`	Многоклассовая классификация. Требует `output_dim ≥ 2`.
`mse`	`MSELoss`	Регрессия (числовой выход).
`mae`	`L1Loss`	Регрессия, устойчивая к выбросам.
`bce`	`BCELoss`	Бинарная классификация с sigmoid на выходе.
`bce_logits`	`BCEWithLogitsLoss`	Бинарная классификация, включает sigmoid внутри.
`huber`	`HuberLoss`	Регрессия: мягкое сочетание MSE и MAE.
`nll`	`NLLLoss`	После `log_softmax`. Требует `output_dim ≥ 2`.

Раздел: `simulation` #

Используется только при task = "rl".

Путь	Тип	По умолчанию	Описание
`simulation.enabled`	`bool`	`false`	При `task=rl` принудительно выставляется в `true`.
`simulation.path`	`string`	`""`	Путь к `.py`-файлу среды.
`simulation.inline_code`	`code`	`""`	Код среды прямо в конфиге. Приоритетнее `path`.
`simulation.entry`	`string`	`"make_env"`	Имя фабрики или класса среды.
`simulation.algo`	`enum`	`"ppo"`	Алгоритм: `ppo`, `reinforce`, `dqn`.
`simulation.episodes`	`int ≥1`	`300`	Число эпизодов.
`simulation.max_steps`	`int ≥1`	`200`	Максимум шагов в эпизоде.
`simulation.gamma`	`float [0, 1]`	`0.99`	Discount factor.
`simulation.gae_lambda`	`float [0, 1]`	`0.95`	GAE-λ (только PPO).
`simulation.clip_eps`	`float [0, 1]`	`0.2`	PPO clip ε.
`simulation.entropy_coef`	`float ≥0`	`0.01`	Коэффициент энтропийного бонуса.
`simulation.value_coef`	`float ≥0`	`0.5`	Вес loss value-функции.
`simulation.rollout_episodes`	`int ≥1`	`8`	Эпизодов перед каждым обновлением политики.
`simulation.update_epochs`	`int ≥1`	`4`	Проходов по собранному батчу (PPO).
`simulation.timeout_seconds`	`float ≥0`	`30.0`	Таймаут одного шага/reset. `>0` — изолировать в подпроцессе. `0` — in-process (быстрее, без изоляции).

Раздел: `discord` #

Подраздел: `discord.presence`

Путь	Тип	По умолчанию	Описание
`discord.presence.enabled`	`bool`	`false`	Включить Rich Presence.
`discord.presence.client_id`	`string`	`""`	Application ID из discord.com/developers. Без него presence отключается.
`discord.presence.large_image`	`string`	`"kuznya"`	Ключ арта, загруженного в портал разработчика.
`discord.presence.small_image`	`string`	`""`	Ключ малой иконки.
`discord.presence.show_metrics`	`bool`	`true`	Показывать текущую метрику в строке статуса.
`discord.presence.buttons`	`buttons[]`	`[]`	До 2 кнопок: `[{"label": "...", "url": "https://..."}]`. Метки ≤ 31 байт.

Подраздел: `discord.webhook`

Путь	Тип	По умолчанию	Описание
`discord.webhook.enabled`	`bool`	`false`	Включить вебхук.
`discord.webhook.url_env`	`string`	`"KUZNYA_WEBHOOK_URL"`	Имя переменной окружения с URL вебхука. Никогда не пишите URL напрямую в конфиг, который попадёт в git.
`discord.webhook.url`	`secret`	`""`	URL напрямую. Редактируется в UI. Не хранится в экспорте.
`discord.webhook.live_panel`	`bool`	`true`	Одно сообщение редактируется на месте (1 POST + N PATCH).
`discord.webhook.notify`	`list`	`["run_start","run_end","best","crash"]`	События для отправки.
`discord.webhook.attach_curves`	`bool`	`true`	Прикладывать PNG с графиком потерь к финальной карточке.

Раздел: `output` #

Путь	Тип	По умолчанию	Описание
`output.dir`	`string`	`"runs"`	Корневая папка для артефактов ранов.
`output.save_curves`	`bool`	`true`	Сохранять кривые в MetricStore.

Межполевые правила валидации #

Эти правила нельзя выразить в плоской схеме — они проверяются в config.validate():

Условие	Поведение
`train.loss` in (`cross_entropy`, `nll`) и `model.output_dim < 2`	Ошибка Используй `mse` для регрессии.
`simulation.enabled = true` без `path` и `inline_code`	Ошибка Укажи код среды.
`simulation.path` и `simulation.inline_code` оба заданы	Предупреждение Приоритет у `inline_code`.
`simulation.enabled = true` и `task = supervised`	Предупреждение `task` автоматически переключается в `rl`.
`discord.presence.enabled = true` без `client_id`	Предупреждение Presence отключается.
`discord.webhook.enabled = true` без URL	Предупреждение Webhook отключается.
`train.scheduler.warmup_epochs ≥ train.epochs`	Предупреждение `warmup_epochs` сбрасывается в 0.
`data.batch_size > data.n_samples`	Предупреждение `batch_size` уменьшается до `n_samples // 4`.
`data.val_split ≤ 0` и `train.early_stop.enabled = true`	Предупреждение `early_stop.metric` переключается на `train_loss`.
`model.input_dim` не совпадает с реальной размерностью данных	Предупреждение Исправляется автоматически.

Примеры конфигов #

1. Бинарная классификация (CSV)

json

{
  "project": "fraud-detection",
  "task": "supervised",
  "model": {
    "input_dim": 30,
    "output_dim": 2,
    "layers": [
      {"type": "linear", "units": 128}, {"type": "relu"},
      {"type": "dropout", "p": 0.3},
      {"type": "linear", "units": 64},  {"type": "relu"}
    ]
  },
  "data": {
    "source": "data/fraud.csv",
    "val_split": 0.15,
    "batch_size": 128,
    "normalize": true
  },
  "train": {
    "epochs": 50,
    "loss": "cross_entropy",
    "optimizer": {"name": "adamw", "lr": 0.001, "weight_decay": 0.01},
    "scheduler": {"name": "plateau"}
  }
}

2. Регрессия с LSTM

json

{
  "project": "time-series",
  "task": "supervised",
  "model": {
    "input_dim": 10,
    "output_dim": 1,
    "layers": [
      {"type": "lstm", "hidden_size": 64, "num_layers": 2},
      {"type": "dropout", "p": 0.2}
    ]
  },
  "data": {
    "source": "data/ts.npz",
    "batch_size": 32
  },
  "train": {
    "epochs": 100,
    "loss": "mse",
    "optimizer": {"name": "adam", "lr": 0.001},
    "scheduler": {"name": "cosine", "warmup_epochs": 5}
  }
}

3. RL: PPO на встроенном gridworld

json

{
  "project": "gridworld-ppo",
  "task": "rl",
  "model": {
    "layers": [
      {"type": "linear", "units": 64}, {"type": "tanh"},
      {"type": "linear", "units": 64}, {"type": "tanh"}
    ]
  },
  "simulation": {
    "enabled": true,
    "path": "sims/gridworld.py",
    "algo": "ppo",
    "episodes": 300,
    "max_steps": 200,
    "gamma": 0.99,
    "gae_lambda": 0.95,
    "clip_eps": 0.2,
    "timeout_seconds": 30.0
  },
  "train": {
    "optimizer": {"name": "adam", "lr": 0.0003},
    "grad_clip": 0.5
  }
}

4. Supervised + Discord webhook

json

{
  "project": "mnist-demo",
  "task": "supervised",
  "model": {
    "input_dim": 784,
    "output_dim": 10,
    "layers": [
      {"type": "linear", "units": 256}, {"type": "relu"},
      {"type": "linear", "units": 128}, {"type": "relu"}
    ]
  },
  "data": {
    "source": "python:mydata:load_mnist",
    "batch_size": 256
  },
  "train": {
    "epochs": 20,
    "loss": "cross_entropy",
    "optimizer": {"name": "adamw", "lr": 0.001}
  },
  "discord": {
    "webhook": {
      "enabled": true,
      "url_env": "KUZNYA_WEBHOOK_URL",
      "live_panel": true,
      "attach_curves": true
    }
  }
}

5. RL с inline кодом среды

json

{
  "project": "my-game",
  "task": "rl",
  "simulation": {
    "enabled": true,
    "inline_code": "class Env:\n    n_actions = 2\n    def reset(self):\n        self.x = 0\n        return [float(self.x)]\n    def step(self, a):\n        self.x += 1 if a else -1\n        done = abs(self.x) >= 5\n        return [float(self.x)], -0.1 if not done else 1.0, done, {}\ndef make_env(): return Env()",
    "algo": "ppo",
    "episodes": 200,
    "timeout_seconds": 0
  },
  "train": {
    "optimizer": {"name": "adam", "lr": 0.003}
  }
}

Справочник конфига

JSONC: комментарии и висящие запятые #

Корень #

Раздел: model #

Типы слоёв

Раздел: data #

Форматы data.source

Раздел: train #

Подраздел: train.optimizer

Подраздел: train.scheduler

Подраздел: train.early_stop

Подраздел: train.checkpoint

Функции потерь #

Раздел: simulation #

Раздел: discord #

Подраздел: discord.presence

Подраздел: discord.webhook

Раздел: output #

Межполевые правила валидации #

Примеры конфигов #

1. Бинарная классификация (CSV)

2. Регрессия с LSTM

3. RL: PPO на встроенном gridworld

4. Supervised + Discord webhook

5. RL с inline кодом среды

Раздел: `model` #

Раздел: `data` #

Форматы `data.source`

Раздел: `train` #

Подраздел: `train.optimizer`

Подраздел: `train.scheduler`

Подраздел: `train.early_stop`

Подраздел: `train.checkpoint`

Раздел: `simulation` #

Раздел: `discord` #

Подраздел: `discord.presence`

Подраздел: `discord.webhook`

Раздел: `output` #