297 lines
20 KiB
Markdown
297 lines
20 KiB
Markdown
# Шаг 1 — Что не соответствует стандарту в текущем состоянии
|
||
|
||
> **Только диагностика.** Никаких решений по рефакторингу — это пойдёт на следующих шагах. Здесь только: что есть сейчас, какое правило стандарта нарушено, и каков масштаб проблемы.
|
||
|
||
---
|
||
|
||
## Текущее состояние
|
||
|
||
| Что | Где | Сколько |
|
||
|---|---|---|
|
||
| Гин-конфиги (взаимовключаемые через `include`) | `conf/` | 12 файлов: `balanced.gin`, `baseline_no_text.gin`, `text_heavy.gin` (v2 UAV-GeoLoc), `gtauav_balanced.gin`, `gtauav_baseline.gin`, `gtauav_balanced_asym.gin`, `gtauav_baseline_asym.gin`, `gtauav_balanced_stripnet.gin`, `gtauav_balanced_stripnet_unfrozen.gin`, `gtauav_baseline_stripnet.gin`, `gtauav_baseline_stripnet_unfrozen.gin`, `gtauav_text_heavy.gin`, `gtauav_image_heavy.gin` (по скриншоту в локальной копии есть ещё 4 sofia-варианта) |
|
||
| Главный `@gin.configurable + @dataclass` | `src/training/train_gtauav.py::TrainConfigGTAUAV` | 1 класс, 50+ полей |
|
||
| Legacy `@gin.configurable` на классе тренировки | `src/training/train.py::TrainConfig` (v2) | 1 класс, 14 полей |
|
||
| `@gin.configurable` на не-конфиг классах | `src/losses/multi_infonce.py::InfoNCELoss`, `src/losses/weighted_infonce.py::WeightedInfoNCELoss`, `src/datasets/visloc_with_captions.py::GeoLocCaptionDataset` | 3 класса |
|
||
| Локальный `@dataclass` для модели (без gin) | `src/models/sofia_v1/config.py::SOFIAv1Config` | 1 класс |
|
||
| Module-level пути | `src/training/train_gtauav.py`, `src/datasets/gtauav_dataset.py`, `scripts/make_split.py`, `scripts/filter_segmentation.py` | 4 файла |
|
||
| `argparse` | `src/training/train_gtauav.py`, `src/training/train.py`, `scripts/make_split.py`, `scripts/filter_segmentation.py` | 4 файла |
|
||
|
||
---
|
||
|
||
## Несоответствия стандарту
|
||
|
||
### 1. `@gin.configurable + @dataclass` — критическое нарушение
|
||
|
||
**Правило** (`Стандарт_написания_кода_для_DL_CV.md` §3.1, `Reference Examples → Anti-patterns`):
|
||
|
||
> «**Запрещено** использовать `dataclass` совместно с gin»
|
||
|
||
**Что нарушает:**
|
||
|
||
`src/training/train_gtauav.py`:
|
||
```python
|
||
@gin.configurable(module="src.training.train_gtauav")
|
||
@dataclass # ← FORBIDDEN
|
||
class TrainConfigGTAUAV:
|
||
train_json: str = _TRAIN_JSON
|
||
test_json: str = _TEST_JSON
|
||
rgb_root: str = _RGB_ROOT
|
||
# ... 50+ полей всего:
|
||
# пути к данным, к моделям, training schedule, model arch (mona, gates,
|
||
# baseline, stripnet, asymmetric), loss params, sampler params,
|
||
# tracking flags (wandb/tb/gradcam/profiler)
|
||
```
|
||
|
||
**Почему это нарушение:** `@dataclass` авто-генерирует `__init__`, в который gin **тоже** инъектирует параметры. Получается двойная магия: dataclass читает type hints для генерации сигнатуры, gin читает гин-биндинги для подмены значений. На практике работает, но это именно та комбинация, которую стандарт запрещает.
|
||
|
||
**Масштаб:** **1 класс**, но он держит **всё** — путь, hardware, model, loss, sampler, tracking. Это блокирует разделение конфига на оси.
|
||
|
||
---
|
||
|
||
### 2. `@gin.configurable` на не-конфиг классах — критическое нарушение
|
||
|
||
**Правило** (стандарт §3.1):
|
||
|
||
> «Декоратор `@gin.configurable` **только на классах** [конфигурации, *не на бизнес-логике*]»
|
||
|
||
**Что нарушает:**
|
||
|
||
| Файл | Класс | Параметры (которые проникают в `.gin`) |
|
||
|---|---|---|
|
||
| `src/losses/multi_infonce.py` | `InfoNCELoss` | `temperature_init`, `temperature_final`, `label_smoothing`, `weight_q2g`, `weight_g2q`, `learnable_temperature`, `tau_min`, `tau_max`, `hard_mining_k` |
|
||
| `src/losses/weighted_infonce.py` | `WeightedInfoNCELoss` | `temperature_init`, `learnable_temperature`, `label_smoothing`, `k`, `tau_min`, `tau_max` |
|
||
| `src/datasets/visloc_with_captions.py` (v2) | `GeoLocCaptionDataset` | `query_file`, `data_root`, `image_transform`, `drop_caption_prob`, `seed` |
|
||
|
||
**Почему это нарушение:** конфиг и бизнес-логика — разные слои. Когда `nn.Module` или `Dataset` декорированы `@gin.configurable`, гин лезет в **их** `__init__` помимо лезения в `TrainConfigGTAUAV.__init__`. В `gtauav_balanced.gin` это видно прямо:
|
||
|
||
```gin
|
||
# Параметры дублируются — раз в TrainConfigGTAUAV, раз в InfoNCELoss:
|
||
TrainConfigGTAUAV.tau_init = 0.07
|
||
TrainConfigGTAUAV.label_smoothing = 0.1
|
||
TrainConfigGTAUAV.weight_q2g = 0.6
|
||
TrainConfigGTAUAV.weight_g2q = 0.4
|
||
|
||
# ---- InfoNCELoss (gin-configurable) ----
|
||
InfoNCELoss.temperature_init = 0.07 # ← дубль tau_init
|
||
InfoNCELoss.label_smoothing = 0.1 # ← дубль
|
||
InfoNCELoss.weight_q2g = 0.6 # ← дубль
|
||
InfoNCELoss.weight_g2q = 0.4 # ← дубль
|
||
InfoNCELoss.tau_min = 0.01
|
||
InfoNCELoss.tau_max = 0.1
|
||
InfoNCELoss.hard_mining_k = 0
|
||
```
|
||
|
||
**Это активный источник тихих багов:** если кто-то поменяет `TrainConfigGTAUAV.tau_init = 0.05`, а `InfoNCELoss.temperature_init` забудет — обучение пойдёт с `0.05` в логике trainer-а и `0.07` в самой loss-функции. Никаких ошибок не будет, метрики просто будут странными.
|
||
|
||
**Масштаб:** **3 класса**, но самый болезненный — `InfoNCELoss`, потому что у него **самая большая зона перекрытия** с `TrainConfigGTAUAV`.
|
||
|
||
---
|
||
|
||
### 3. `argparse` — критическое нарушение
|
||
|
||
**Правило** (стандарт §3.4):
|
||
|
||
> «**Запрещён argparse** — все параметры из .gin файлов»
|
||
|
||
**Что нарушает:**
|
||
|
||
| Файл | Кол-во CLI флагов | Самые проблемные |
|
||
|---|---|---|
|
||
| `src/training/train_gtauav.py::main` | ~15 | `--config`, `--baseline`, `--batch-size`, `--epochs`, `--filter-meta`, `--wandb`, `--gradcam`, `--profile`, `--gin-param`, `--resume`, `--output-dir` |
|
||
| `src/training/train.py::main` (v2) | 1 | `--config` |
|
||
| `scripts/make_split.py::main` | 3 | `--ratio`, `--seed`, `--output-dir` |
|
||
| `scripts/filter_segmentation.py::main` | 3 | `--segm-root`, `--threshold`, `--output` |
|
||
|
||
**Самый ядовитый паттерн** в `train_gtauav.py`:
|
||
|
||
```python
|
||
parser.add_argument("--gin-param", nargs="*", help="Override gin params from CLI")
|
||
# ...
|
||
gin.parse_config_files_and_bindings([cfg_file], extra_bindings)
|
||
```
|
||
|
||
CLI **перекрывает** gin-биндинги. Это создаёт **3 источника правды** на один и тот же параметр: дефолт в `__init__`, значение в `.gin`, значение в `--gin-param`. Какое из них применилось в конкретном запуске — невозможно установить иначе как чтением логов.
|
||
|
||
**Масштаб:** **тренировочный код** (`train_gtauav.py`) — критично; **скрипты** (`make_split.py`, `filter_segmentation.py`) — пограничный случай (см. ниже §7).
|
||
|
||
---
|
||
|
||
### 4. `include` для композиции `.gin` — пограничный случай
|
||
|
||
**Правило** (`REQUIREMENTS_GIN_STYLE.md` §8):
|
||
|
||
> «Использовать **минимальный** набор возможностей gin: `@gin.configurable`, `gin.parse_config_file()`. Нет: `gin.register()`, `gin.constant()`, `gin.query_parameter()`, **макросы, ссылки между конфигами**»
|
||
|
||
**Что есть сейчас:**
|
||
|
||
```gin
|
||
# conf/gtauav_balanced_asym.gin
|
||
include 'conf/gtauav_balanced.gin'
|
||
|
||
TrainConfigGTAUAV.shared_encoder = False
|
||
TrainConfigGTAUAV.mona_last_n_blocks = 24
|
||
TrainConfigGTAUAV.output_dir = "out/gtauav/balanced_asym"
|
||
```
|
||
|
||
`include` — это **встроенная фича gin** для композиции. Формально она:
|
||
- ✅ Не входит в явный список запрещённого (`gin.constant`, `gin.register`, `gin.query_parameter`, макросы)
|
||
- ❌ Попадает под формулировку «**ссылки между конфигами**» в `REQUIREMENTS_GIN_STYLE.md` §8
|
||
|
||
**По букве правил это нарушение.** По духу — `include` решает реальную проблему (DRY), но создаёт неявную зависимость: чтобы понять, с какими параметрами запускается `gtauav_balanced_stripnet_unfrozen.gin`, нужно прочитать **3 файла** (`unfrozen` → `stripnet` → `balanced`).
|
||
|
||
**Масштаб:** все 14 `gtauav_*.gin` (кроме `gtauav_balanced.gin`, который сам — корень дерева) и v2 (`baseline_no_text.gin`, `text_heavy.gin` тянут `balanced.gin`).
|
||
|
||
---
|
||
|
||
### 5. Один мега-конфиг на всё — не «жёсткое» нарушение, но против духа
|
||
|
||
**Правило** (стандарт §3.3, `Рекомендуемые_gin-config_категории.md`):
|
||
|
||
> «Каждый `.gin` → один конфиг-класс»
|
||
>
|
||
> «Принцип разделения: если два параметра меняются **вместе** — в одном конфиге. Если **независимо** — в разных»
|
||
|
||
**Что есть сейчас:**
|
||
|
||
`TrainConfigGTAUAV` миксует **несколько независимых осей изменчивости** в один класс:
|
||
- Пути к данным/моделям (меняются при смене машины) ↔ training schedule (меняются при смене эксперимента) ↔ model arch (`baseline_mode`, `shared_encoder`, `mona_*`, `stripnet_*`) ↔ loss (`tau_init`, `label_smoothing`, `weight_q2g`, ...) ↔ sampler (`sampler_type`, `dss_*`) ↔ tracking (`use_wandb`, `use_tb`, `use_gradcam`, `use_profiler`)
|
||
|
||
В одном `.gin` лежат биндинги для всех этих осей. Когда нужно «то же обучение, но без wandb» — приходится копировать целый `.gin` файл.
|
||
|
||
**Это не нарушение явного запрета, но прямое следствие нарушения #1:** пока есть один большой `@dataclass + @gin.configurable`, иначе расположить параметры просто негде.
|
||
|
||
**Масштаб:** проникает во все 12 `gtauav_*.gin` файлов одинаково.
|
||
|
||
---
|
||
|
||
### 6. Module-level хардкод путей — нарушение
|
||
|
||
**Правило** (стандарт §6 чеклист):
|
||
|
||
> «Нет захардкоженных model ID / промптов / размеров?»
|
||
|
||
**Что нарушает:**
|
||
|
||
```python
|
||
# src/training/train_gtauav.py (module level)
|
||
_RGB_ROOT = "/media/servml/SSD_2_2TB/datasets/cvgl_datasets/GTA-UAV-LR"
|
||
_CAPTION_ROOT = "/media/servml/SSD_2_2TB/datasets/cvgl_datasets/GTA-UAV-LR-captions"
|
||
_TRAIN_JSON = "meta/train_80.json"
|
||
_TEST_JSON = "meta/test_20.json"
|
||
_DINO_WEB = "nn_models/DINO_WEB/dinov3-vitl16-pretrain-lvd1689m.pth"
|
||
_DINO_SAT = "nn_models/DINO_SAT/model.safetensors"
|
||
_LRSCLIP = "nn_models/LRSCLIP/DGTRS-CLIP-ViT-L-14.pt"
|
||
|
||
# src/datasets/gtauav_dataset.py (module level) — ДУБЛЬ:
|
||
_RGB_ROOT = Path("/media/servml/SSD_2_2TB/datasets/cvgl_datasets/GTA-UAV-LR")
|
||
_CAPTION_ROOT = Path("/media/servml/SSD_2_2TB/datasets/cvgl_datasets/GTA-UAV-LR-captions")
|
||
|
||
# scripts/make_split.py (module level):
|
||
_RGB_ROOT = Path("/media/servml/SSD_2_2TB/datasets/cvgl_datasets/GTA-UAV-LR")
|
||
|
||
# scripts/filter_segmentation.py (module level):
|
||
SEGM_ROOT = Path("/media/servml/SSD_2_2TB/datasets/cvgl_datasets/GTA-UAV-LR-aug/segm")
|
||
```
|
||
|
||
**Главная проблема — не сам факт хардкода**, а то, что один и тот же путь `/media/servml/SSD_2_2TB/datasets/cvgl_datasets/GTA-UAV-LR` дублируется в **трёх** местах: train_gtauav.py + gtauav_dataset.py + make_split.py. Если переехать на другую машину — нужно править 3 файла; если забыть один — silent breakage.
|
||
|
||
**Масштаб:** 4 файла, ~10 module-level констант пути.
|
||
|
||
---
|
||
|
||
### 7. Скрипты `make_split.py` / `filter_segmentation.py` — спорный случай
|
||
|
||
**Что есть:**
|
||
- `argparse` (3 параметра в каждом)
|
||
- module-level пути (`_RGB_ROOT`, `SEGM_ROOT`)
|
||
- Запускаются однократно перед тренировкой
|
||
- Не интегрированы в `Trainer.run()`
|
||
|
||
**Применять ли стандарт «нет argparse» к ним?**
|
||
|
||
Стандарт направлен против `argparse` в **тренировочном коде**, где параметров 50+ и нужна воспроизводимость. У `make_split.py` 3 параметра, и это **разовая препроцессинг-утилита**. Здесь буква и дух стандарта расходятся.
|
||
|
||
**Это не «несоответствие, требующее немедленной правки»**, а **открытый вопрос для следующего шага**: применять ли gin-стиль к препроцессинг-скриптам или оставить argparse.
|
||
|
||
---
|
||
|
||
### 8. Sofia models — `@dataclass` без gin (формально не нарушение)
|
||
|
||
**Что есть:**
|
||
|
||
```python
|
||
# src/models/sofia_v1/config.py
|
||
@dataclass
|
||
class SOFIAv1Config:
|
||
variant: Literal["tiny_tiny", "tiny", "small", "small_v2"] = "small"
|
||
in_channels: int = 3
|
||
input_size: int = 256
|
||
dcn_variant: Literal["v2", "v4"] = "v2"
|
||
d_descriptor: int = 1024
|
||
use_film_altitude: bool = True
|
||
altitude_norm: float = 500.0
|
||
use_text_film_uav: bool = True
|
||
use_text_film_sat: bool = True
|
||
text_film_dim: int = 1024
|
||
text_film_hidden: int = 256
|
||
```
|
||
|
||
**Стандарт** запрещает **`@gin.configurable + @dataclass`**, но не запрещает `@dataclass` сам по себе. `SOFIAv1Config` без gin — формально стандарт **не нарушает**.
|
||
|
||
**Однако:** в `gtauav_balanced_sofia*.gin` (по скриншоту локально есть, в репо пока нет) параметры sofia, очевидно, прокидываются в `TrainConfigGTAUAV` как обычные поля. То есть sofia сейчас живёт в **двух** местах:
|
||
- `SOFIAv1Config` (dataclass, в коде модели)
|
||
- `TrainConfigGTAUAV.sofia_*` (если там такие есть) или только через позиционное создание `SOFIAv1Config()` в `Trainer`
|
||
|
||
Это не нарушение, но **архитектурный раскол**: dataclass-конфиги внутри модельных подсистем + gin-конфиги снаружи.
|
||
|
||
**Это тоже открытый вопрос для следующего шага**, не текущая проблема.
|
||
|
||
---
|
||
|
||
### 9. Прочее по чеклисту стандарта (мелочи)
|
||
|
||
| Пункт | Состояние | Файлы |
|
||
|---|---|---|
|
||
| `from __future__ import annotations` первой строкой | ✅ есть в ключевых файлах | проверено в `train_gtauav.py`, `gtauav_dataset.py`, `multi_infonce.py`, `weighted_infonce.py`, `train.py` |
|
||
| Строгие type hints | ✅ в основном | пара мест с `dict` без параметров (`_atomic_save(obj: dict)`) |
|
||
| Google-style docstrings | ✅ есть, качество хорошее | — |
|
||
| `@torch.inference_mode()` вместо `@torch.no_grad()` | ❌ используется `@torch.no_grad()` | `train_gtauav.py::_evaluate`, `_embed_drone_queries` |
|
||
| Atomic writes | ⚠️ есть, но без cleanup на ошибке | `train_gtauav.py::_atomic_save` (нет `try/except` — `.tmp` остаётся при сбое) |
|
||
| Английский в коде/комментариях | ✅ есть | — |
|
||
| Импорты stdlib → third-party → local | ✅ есть | — |
|
||
|
||
---
|
||
|
||
## Сводка — что нарушено и насколько срочно
|
||
|
||
| # | Нарушение | Срочность | Зона воздействия |
|
||
|---|---|---|---|
|
||
| 1 | `@gin.configurable + @dataclass` на `TrainConfigGTAUAV` | 🔴 критично | блокирует всё остальное |
|
||
| 2 | `@gin.configurable` на `InfoNCELoss`, `WeightedInfoNCELoss`, `GeoLocCaptionDataset` | 🔴 критично | активный источник тихих багов |
|
||
| 3 | `argparse` в тренировочном коде | 🔴 критично | три источника правды на параметр |
|
||
| 4 | `include` между `.gin` файлами | 🟡 пограничный | формально нарушает «нет ссылок между конфигами» |
|
||
| 5 | Один мега-конфиг (нет разделения на оси) | 🟡 следствие #1 | разрешится с #1 |
|
||
| 6 | Module-level пути в 4 файлах | 🟡 нарушение, но не критично | дубли — реальная проблема |
|
||
| 7 | `argparse` в скриптах препроцессинга | ⚪ открытый вопрос | спорный случай |
|
||
| 8 | `@dataclass` в `SOFIAv1Config` (без gin) | ⚪ открытый вопрос | формально не нарушение |
|
||
| 9 | `@torch.no_grad()` вместо `@torch.inference_mode()` | 🟢 мелочь | косметика |
|
||
| 10 | `_atomic_save` без cleanup .tmp | 🟢 мелочь | редкое последствие |
|
||
|
||
---
|
||
|
||
## Что предлагаю обсудить дальше (Шаг 2)
|
||
|
||
Прежде чем двигать код, нужно принять решения по 4 развилкам:
|
||
|
||
1. **`include` между `.gin`** — терпим как удобный DRY-механизм или приводим к плоской иерархии (каждый эксперимент = самодостаточный набор `.gin` без `include`)?
|
||
|
||
2. **Разделение `TrainConfigGTAUAV` на классы** — на сколько и по каким осям?
|
||
- Вариант **5 классов** (Pipeline / Hardware / Models / Training / Tracking) из «`Рекомендуемые_gin-config_категории.md`».
|
||
- Вариант **6 классов** (отдельный Loss + Sampler).
|
||
- Вариант **3 класса** (всё, что было — в Training, плюс Pipeline + Tracking).
|
||
|
||
3. **Sofia + dataclass** — оставлять `SOFIAv1Config` как dataclass-структуру внутри модели или переписать в обычный класс/влить в `ModelsConfig`?
|
||
|
||
4. **Скрипты** — переводить на gin или оставить argparse?
|
||
|
||
После решения этих 4 пунктов план рефакторинга становится однозначным. |