From 71ebce3b6d012ce3273586c7b23831b0be2a160b Mon Sep 17 00:00:00 2001 From: bogdanpavl Date: Wed, 24 Jun 2026 08:54:36 +0000 Subject: [PATCH] =?UTF-8?q?=D0=97=D0=B0=D0=B3=D1=80=D1=83=D0=B7=D0=B8?= =?UTF-8?q?=D1=82=D1=8C=20=D1=84=D0=B0=D0=B9=D0=BB=D1=8B=20=D0=B2=20=C2=AB?= =?UTF-8?q?reports=C2=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../1.1 Подготовительный этап (Конспект).md | 315 ++++++++++++++++++ 1 file changed, 315 insertions(+) create mode 100644 reports/1.1 Подготовительный этап (Конспект).md diff --git a/reports/1.1 Подготовительный этап (Конспект).md b/reports/1.1 Подготовительный этап (Конспект).md new file mode 100644 index 0000000..ec28331 --- /dev/null +++ b/reports/1.1 Подготовительный этап (Конспект).md @@ -0,0 +1,315 @@ +--- +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, стабильность и интерпретируемость вклада модальностей. \ No newline at end of file