315 lines
20 KiB
Markdown
315 lines
20 KiB
Markdown
---
|
||
tags:
|
||
- task
|
||
- CVGL
|
||
- ЛИСАД/ВЛМ
|
||
---
|
||
[[Base-Terms]], [[ЭТАПЫ]], [[01_required]],
|
||
[[Основной пакет]], [[02_fusion_core_общий]], [[02_fusion_core_персональный]],
|
||
|
||
**Изучение постановки и контекста проекта:**
|
||
- README.md;
|
||
- docs/00_project/06_MERIDIAN_CONTEXT.md (включая §5 — требование корректного поведения при отсутствии модальности);
|
||
- docs/01_tasks/00_MASTER_ASSIGNMENT.md;
|
||
- 01_INPUT_OUTPUT_CONTRACT.md;
|
||
- 02_TEAM_WORKFLOW.md;
|
||
- 03_EXPERIMENT_PROTOCOL_GTA_UAV.md
|
||
|
||
# MERIDIAN CONTEXT
|
||
|
||
## 1. MERIDIAN — асимметричная Teacher–Student система
|
||
|
||
MERIDIAN — асимметричная Teacher–Student система кросс-видовой геолокализации БПЛА (UAV ↔ satellite) с привилегированными модальностями (LUPI/KD) и лёгким edge-инференсом.
|
||
|
||
**Цель:** сравнение методов объединения и выбор по обозначенным критериям
|
||
## 2. Teacher
|
||
|
||
Имеет 8 входных потоков.
|
||
|
||
|#|Поток|View|Источник|Природа сигнала|
|
||
|---|---|---|---|---|
|
||
|1|RGB satellite|sat|датасет|основной визуальный якорь|
|
||
|2|Text caption satellite|sat|VLM (Qwen3-VL)|глобальная семантика сцены|
|
||
|3|CHM satellite|sat|CHMv2|высота растительности/структура|
|
||
|4|Segmentation satellite|sat|SegFormer, 17 классов|land-cover semantics|
|
||
|5|RGB UAV|uav|датасет|основной визуальный якорь|
|
||
|6|Text caption UAV|uav|VLM (Qwen3-VL)|глобальная семантика сцены|
|
||
|7|Relative depth UAV|uav|Depth Anything|геометрия/структура сцены|
|
||
|8|Segmentation UAV|uav|SegFormer, 17 классов|spatial semantics|
|
||
## 3. Цель
|
||
|
||
Прямой перебор fusion-архитектур на полном Teacher (DINOv3-L, ~300M+ params) слишком дорог: один полный прогон занимает часы и съедает всю VRAM. Поэтому архитектурный поиск выполняется на **быстром прокси**:
|
||
|
||
Прокси сохраняет главное: frozen visual anchor + лёгкие обучаемые модули, те же модальности, тот же retrieval-протокол. Вывод «какой класс fusion-операторов выигрывает и за счёт чего» переносится; конкретные гиперпараметры — нет, и это нормально.
|
||
|
||
## 4. Назначение результата
|
||
|
||
1. Победившее семейство (primary) + fallback фиксируются в decision record.
|
||
2. Primary-механизм переносится на Teacher DINOv3 (адаптация: CNN stage maps → ViT token maps) и входит в спецификацию fusion MERIDIAN.
|
||
3. Fused-эмбеддинг Teacher становится KD-таргетом для RGB-only Student.
|
||
4. Ваши diagnostics (вклад модальностей, gate statistics) станут инструментами анализа Teacher.
|
||
|
||
## 5. Устойчивость к modality-dropout
|
||
|
||
В production Teacher модальности могут отсутствовать или быть деградированными (нет caption у ~55% satellite tiles уже сейчас; depth/CHM могут быть зашумлены). Кроме того, на следующем этапе MERIDIAN планируется обучение с **modality dropout** (стохастическое отключение модальностей) — ==оно НЕ входит в ваше задание==, но накладывает требование на архитектуру:
|
||
|
||
| Класс | Поведение при отсутствии модальности | Вердикт |
|
||
| -------------------------------------------------- | -------------------------------------------- | ------------------------------ |
|
||
| Cross-attention над пулом модальных токенов | softmax перенормируется на оставшиеся токены | **безопасен by construction** |
|
||
| FiLM / gating с zero-init (identity-at-init) | выпавшая модальность даёт identity | **безопасен при корректной init** |
|
||
| Gated additive residual | residual = 0 → чистый RGB-путь | **безопасен при корректной init** |
|
||
| Чисто multiplicative gating (выход = RGB × f(aux)) | near-zero aux уничтожает RGB-сигнал | опасен, требует additive-ветки |
|
||
| Differential conditioning (f(Xi − Xj)) | теряет смысл при отсутствии одного из Xi | опасен |
|
||
| SSM/Mamba cross-state fusion | состояние дестабилизируется | research-arm, не primary |
|
||
==Практическое следствие для всех трёх треков: тест «отключи модальность через validity mask и проверь, что descriptor конечен и близок к RGB-only» входит в обязательные unit-тесты, а поведение при missing modality — в decision table финального сравнения.==
|
||
|
||
## 6. В проекте отсутствует
|
||
|
||
- Никакого modality dropout в training loop (это следующий этап MERIDIAN, отдельная задача).
|
||
- Никакой дистилляции в Student (KD-мост строится после выбора fusion).
|
||
- Никакой замены StripNet или обучения собственных моделей depth/seg/CHM/captions.
|
||
- Никакого использования GPS, координат, имён локаций и paired-view признаков.
|
||
|
||
# MASTER ASSIGMENT
|
||
|
||
## 1. Исполнители
|
||
|
||
| Сотрудник | Архитектурный трек | Общая ответственность |
|
||
| -------------------------- | --------------------------------------- | ---------------------------------------------------- |
|
||
| **Павленко Богдан Викторович** | **Condition-Aware RGB-Anchored Fusion** | **общий fusion API и architecture consistency** |
|
||
| Близно Максим Витальевич | Token/Bottleneck Full-Modal Aggregation | benchmark, metrics, run registry и статистика |
|
||
| Мороз Егор Сергеевич | Role-Aware Hierarchical Fusion | dataset contract, preprocessing и quality validation |
|
||
## 2. Что требуется решить
|
||
|
||
Нужно разработать алгоритм объединения модальностей для cross-view geo-localization. Для каждой view-ветки доступен свой набор:
|
||
- img
|
||
- text
|
||
- geom
|
||
- segm
|
||
|
||
Один shared `StripNet-small` кодирует RGB.
|
||
### 2.1. Зачем это нужно
|
||
|
||
Для архитектурного отбора fusion-механизма для Teacher системы MERIDIAN на быстром прокси (StripNet + GTA-UAV вместо DINOv3 + production-данных).
|
||
Отсюда два следствия:
|
||
|
||
1. Нас интересует **класс механизма и причина его успеха**, а не выжатые гиперпараметрами проценты.
|
||
2. Вторичный критерий отбора — **корректное поведение при отсутствии модальности** (validity mask = 0): выход конечен, RGB-путь не искажён
|
||
|
||
### 2.2. Заметки о данных
|
||
|
||
|Факт|Значение|Следствие|
|
||
|---|---|---|
|
||
|Satellite RGB|14,640 PNG 256×256, **RGBA**|alpha-канал проверить и отбросить осознанно|
|
||
|UAV RGB|33,763 PNG 512×384, высоты 100–600 м|resize к 256×256 фиксируется единообразно|
|
||
|Captions UAV|33,411 из 33,763 (~99%)|почти полное покрытие|
|
||
|Captions satellite|**6,546 из 14,640 (~44.7%)**|text_valid mask обязателен; пустой caption ≠ нулевой текст|
|
||
|Auxiliary maps|48,403 изображений: segm/depth/edge/chm (+SafeTensors)|edges в primary input не входят|
|
||
|Segmentation|17 unified classes|канон классов — `vendor_reference/depth_edges_annotate_worlduav/scripts/seg_classes.py`|
|
||
|Seg-filter|37,498 из 48,403 прошли фильтр (≥90% background+water исключены)|фильтр применяется одинаково ко всем вариантам|
|
||
|Расположение данных|Linux-сервер: `/home/servml/Документы/datasets/GTA-UAV-LR{,-captions,-aug}/`|фактические пути фиксируются в gin и ENVIRONMENT_AUDIT|
|
||
|
||
## 3. Входные и выходные данные
|
||
[[#IO CONTRACT]]
|
||
### 3.1. Satellite branch
|
||
|
||
```
|
||
RGB satellite [B, 3, 256, 256]
|
||
Caption satellite list[str] / tokenized text
|
||
CHM [B, 1, 256, 256]
|
||
Segmentation [B, 1, 256, 256] IDs или [B, 17, 256, 256]
|
||
Validity masks geometry + segmentation
|
||
```
|
||
### 3.2. Satellite branch
|
||
|
||
```
|
||
RGB UAV [B, 3, 256, 256]
|
||
Caption UAV list[str] / tokenized text
|
||
Relative depth [B, 1, 256, 256]
|
||
Segmentation [B, 1, 256, 256] IDs или [B, 17, 256, 256]
|
||
Validity masks geometry + segmentation
|
||
```
|
||
|
||
### 3.3. Выходные данные
|
||
|
||
```
|
||
descriptor [B, 1024], L2 normalized
|
||
rgb_descriptor [B, 1024]
|
||
modality_contributions
|
||
diagnostics
|
||
```
|
||
|
||
Далее вычисляется similarity matrix UAV-to-satellite. Fusion-модуль не получает features противоположной view.
|
||
|
||
## 4. Цель экспериментов
|
||
|
||
Проверить, может ли full-modal representation улучшить cross-area retrieval относительно StripNet RGB-only и какой класс fusion делает это наиболее надёжно.
|
||
|
||
Primary metric: cross-area UAV-to-satellite R@1.
|
||
Secondary:
|
||
- R@5, R@10, MRR, AP;
|
||
- satellite-to-UAV retrieval;
|
||
- mean и std по seed 42/123/456;
|
||
- peak VRAM, latency, trainable params;
|
||
- вклад text, segmentation и geometry;
|
||
- отсутствие modality collapse.
|
||
|
||
## 5. Архитектурный кандидат
|
||
|
||
RGB остаётся anchor. Auxiliary encoders строят residual corrections, а controller определяет их вклад в зависимости от content и качества входов.
|
||
# IO CONTRACT
|
||
|
||
Одна обучающая запись содержит UAV-снимок запрос (query) и один положительный satellite кандидат (1 к 1). На eval может быть 1 к * (несколько допустимых sat matches)
|
||
|
||
## 1. Sat view
|
||
|
||
|Поле|Форма|Dtype|Нормализация|Назначение|
|
||
|---|---|---|---|---|
|
||
|`rgb`|`[B, 3, 256, 256]`|`float32`|ImageNet mean/std|вход StripNet|
|
||
|`text`|`list[str]` или tokens|string/int|согласно text encoder|описание сцены без location leakage|
|
||
|`geometry`|`[B, 1, 256, 256]`|`float32`|robust per-frame CHM normalization|высотная структура|
|
||
|`segmentation`|`[B, 1, 256, 256]` class IDs или `[B, 17, 256, 256]` probabilities|`uint8`/`float32`|IDs `0..16` или probabilities|land-cover semantics|
|
||
|`geometry_valid`|`[B, 1, 256, 256]`|`bool`|нет|валидные CHM pixels|
|
||
|`segmentation_valid`|`[B, 1, 256, 256]`|`bool`|нет|валидные segmentation pixels|
|
||
|`sample_id`|`[B]`|string|нет|только логирование, не feature|
|
||
|
||
## 2. UAV view
|
||
|
||
|Поле|Форма|Dtype|Нормализация|Назначение|
|
||
|---|---|---|---|---|
|
||
|`rgb`|`[B, 3, 256, 256]`|`float32`|ImageNet mean/std|вход StripNet|
|
||
|`text`|`list[str]` или tokens|string/int|согласно text encoder|описание сцены без location leakage|
|
||
|`geometry`|`[B, 1, 256, 256]`|`float32`|relative depth normalization|структура и масштабные признаки|
|
||
|`segmentation`|`[B, 1, 256, 256]` class IDs или `[B, 17, 256, 256]` probabilities|`uint8`/`float32`|IDs `0..16` или probabilities|spatial semantics|
|
||
|`geometry_valid`|`[B, 1, 256, 256]`|`bool`|нет|валидные depth pixels|
|
||
|`segmentation_valid`|`[B, 1, 256, 256]`|`bool`|нет|валидные segmentation pixels|
|
||
|`sample_id`|`[B]`|string|нет|только логирование, не feature|
|
||
|
||
## 3. StripNet
|
||
|
||
|Stage|Tensor|Spatial stride|Разрешённое использование|
|
||
|--:|---|--:|---|
|
||
|1|`[B, 64, 64, 64]`|4|преимущественно RGB low-level; auxiliary fusion только после отдельного обоснования|
|
||
|2|`[B, 128, 32, 32]`|8|dense segmentation/geometry кандидаты|
|
||
|3|`[B, 320, 16, 16]`|16|основной mid-level fusion|
|
||
|4|`[B, 512, 8, 8]`|32|high-level fusion и readout|
|
||
|GAP|`[B, 512]`|global|RGB anchor descriptor|
|
||
|Projection|`[B, 1024]`|global|retrieval descriptor до L2 normalization|
|
||
## 4. Fusion output
|
||
|
||
Каждый `encode_view` возвращает:
|
||
|
||
|Поле|Форма|Требование|
|
||
|---|---|---|
|
||
|`descriptor`|`[B, 1024]`|finite, L2 norm `1 +/- 1e-4`|
|
||
|`rgb_descriptor`|`[B, 1024]`|RGB anchor для диагностики|
|
||
|`modality_contributions`|`[B, 3]` или dict|text, segmentation, geometry|
|
||
|`diagnostics`|dict tensors/scalars|gates, attention mass, norms, entropy|
|
||
|
||
Диагностика не должна менять descriptor в eval mode.
|
||
## 5. Парный forward
|
||
|
||
satellite batch -> encode_view(view="satellite") -> z_sat [B, 1024]
|
||
UAV batch -> encode_view(view="uav") -> z_uav [B, 1024]
|
||
similarity = z_uav @ z_sat.T / temperature
|
||
## 6. Text contrat
|
||
|
||
- Поддержать L1, L2, L3 или выбранную объединённую схему.
|
||
- Пустой satellite caption обрабатывается через explicit validity mask.
|
||
- Пустая строка не должна кодироваться как полноценный semantic signal.
|
||
- Caption не должен содержать координаты, названия районов, file names и прямые match identifiers.
|
||
- Text encoder и token budget фиксируются для честного сравнения fusion variants.
|
||
## 8. Geometry contract
|
||
|
||
- CHM и depth имеют общий ключ `geometry`, но разные preprocessing и projector parameters.
|
||
- Нельзя считать численные значения depth и CHM сопоставимыми до view-specific normalization.
|
||
- PNG допускается только для визуальной проверки. Для обучения использовать dense tensors/SafeTensors.
|
||
- Любая производная карта, например depth gradient, считается внутри documented preprocessing block.
|
||
## 9. Segmentation contract
|
||
|
||
- Канонический набор: 17 unified classes.
|
||
- Primary representation определяется командой на interface-freeze: class IDs + embedding или probabilities/logits.
|
||
- Hard RGB palette images не используются как model input.
|
||
- Редкие и отсутствующие классы не должны приводить к NaN при mask pooling.
|
||
## 10. Запрещённые признаки
|
||
|
||
- GPS и координаты.
|
||
- Название карты, района или локации.
|
||
- Индекс paired image как embedding.
|
||
- Features второй view-ветки внутри текущего encoder.
|
||
- Evaluation labels внутри preprocessing.
|
||
|
||
# Регламент совместной работы
|
||
|
||
У команды три архитектурных трека, но одна кодовая и экспериментальная система.
|
||
|
||
| Область | Driver | Обязательные reviewers |
|
||
| ---------------------------------- | ------------ | ---------------------- |
|
||
| **Fusion API и registry** | **Павленко** | Близно, Мороз |
|
||
| Dataset и modality validation | Мороз | **Павленко**, Близно |
|
||
| Training/eval benchmark | Близно | **Павленко**, Мороз |
|
||
| **Condition-aware module** | **Павленко** | Мороз |
|
||
| Token/bottleneck module | Близно | **Павленко** |
|
||
| Role-aware module | Мороз | Близно |
|
||
| Общая experiment matrix | Близно | все |
|
||
| **Финальная архитектурная оценка** | **все** | **все** |
|
||
## Этапы
|
||
|
||
### Gate 0. Environment audit
|
||
|
||
- Проверить локальные пути двух внешних проектов.
|
||
- Зафиксировать путь GTA-UAV RGB, captions, pair JSON и annotations.
|
||
- Проверить checkpoint StripNet.
|
||
- Выполнить чтение обязательного пакета.
|
||
- Создать `reports/joint/ENVIRONMENT_AUDIT.md`.
|
||
### Gate 1. Interface freeze
|
||
|
||
До реализации архитектур команда совместно утверждает:
|
||
|
||
1. Формат segmentation: IDs/embedding или probabilities.
|
||
2. Формат CHM/depth и normalization.
|
||
3. Text encoder, уровни captions и output dimension.
|
||
4. `FusionModelBase` API.
|
||
5. Common diagnostics keys.
|
||
6. Baseline config и output directory convention.
|
||
|
||
Результат: `reports/joint/INTERFACE_DECISION.md`. Изменения после freeze требуют записи причины и влияния на все три варианта.
|
||
### Gate 2. RGB-only baseline
|
||
|
||
- Один общий StripNet-only run.
|
||
- Один общий dataloader.
|
||
- Один общий evaluation script.
|
||
- Smoke run на малом subset.
|
||
- Полный baseline минимум на seed 42, затем финальный baseline на 42/123/456.
|
||
Без подтверждённого baseline реализация fusion не переходит к полным запускам.
|
||
### Gate 3. Independent implementation behind common API
|
||
|
||
Каждый сотрудник реализует свой модуль в отдельной feature branch. Разрешены разные внутренние операторы, но входы, выходы, loss и logging одинаковы.
|
||
### Gate 4. Pair review
|
||
|
||
Reviewer проверяет:
|
||
|
||
- shape contract;
|
||
- отсутствие cross-view leakage;
|
||
- корректность masks;
|
||
- identity/residual path;
|
||
- вычислительную сложность;
|
||
- диагностируемость вклада модальностей;
|
||
- тесты и gin config.
|
||
### Gate 5. Smoke comparison
|
||
|
||
Все три модуля запускаются:
|
||
|
||
- на одном subset;
|
||
- с одним seed;
|
||
- на одинаковом числе batches;
|
||
- с одинаковым optimizer/loss;
|
||
- с logging peak VRAM и latency.
|
||
|
||
Цель: найти ошибки интеграции, а не выбрать победителя.
|
||
### Gate 6. Full experiment matrix
|
||
|
||
После smoke comparison выполняются primary runs и выбранные ablations по общему protocol.
|
||
### Gate 7. Joint decision
|
||
|
||
Команда совместно заполняет decision table. Архитектура не выбирается по одному лучшему run. Учитываются mean, variance, compute, стабильность и интерпретируемость вклада модальностей. |