Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,93 @@
+---
+license: mit
+---
+
+# avito-floorplan-checkpoints
+
+Чекпоинты instance-segmentation моделей из сравнительного исследования
+сегментации комнат на поэтажных планах (ResPlan_v2 + CubiCasa5K для
+обучения, реальные UGC-фото с Avito для теста). Код: см. основной проект.
+
+Классы (везде одинаковые, id 1-7): `living, bedroom, bathroom, kitchen,
+balcony, wall, opening`.
+
+Train/valid split: 80/20, seed=42, одинаковый для всех моделей.
+
+## RF-DETR-Seg (Medium)
+
+`rfdetr_seg/checkpoint_best_ema.pth`
+
+- Модель: `RFDETRSegMedium` (библиотека `rfdetr`)
+- batch_size=2, grad_accum_steps=2 (эффективный batch 4), lr=1e-4
+- Обучение остановлено по плану на эпохе 5 (компромисс время/бюджет на
+  общем сервере) — веса из эпохи 4 (последняя посчитанная валидация)
+- Валидация (эпоха 4): box mAP@50=0.900, mAP@50:95=0.826, segm mAP@50=0.834,
+  segm mAP@50:95=0.560
+- **UGC test**: segm AP@50=0.277, AP@50:95=0.175
+
+## YOLO11m-seg
+
+Пока не залит — текущий прогон (100 эпох, batch=8, imgsz=640,
+early-stopping patience=30) ещё идёт на сервере, зальём по завершении.
+Старый чекпоинт (всего 2 эпохи) сознательно не грузили — устарел.
+
+## Mask R-CNN (ResNet-50 FPN, MMDetection)
+
+`maskrcnn/best_coco_segm_mAP_epoch_1.pth`
+
+- Конфиг: `mask-rcnn_r50_fpn_1x_coco.py`, дообучение с COCO-претрейна
+- batch_size=2 (train), lr=0.0025 (в 8 раз меньше стандартного — под
+  маленький batch/transfer learning)
+- Обучение шло через несколько запусков по 2 часа (общий сервер, разделяемые
+  GPU) с `--load-from` от предыдущего чекпоинта — эпохи считаются заново
+  на каждом запуске, это НЕ единый непрерывный прогон на 24 эпохи из конфига
+- Текущий чекпоинт — лучший по `coco/segm_mAP` на момент заливки:
+  bbox mAP@50:95=0.683, bbox mAP@50=0.863, segm mAP@50:95=0.675,
+  segm mAP@50=0.858 (значения на валидации на обучающих данных, НЕ на UGC)
+- UGC test ещё не прогонялся на этой версии (есть более ранний результат на
+  чекпоинте после 2 эпох: segm AP@50=0.181, AP@50:95=0.096 — с тех пор модель
+  дообучилась ощутимо дальше, ожидаем лучше)
+
+## SegFormer (b2)
+
+`segformer/best.pt`
+
+- Backbone: `nvidia/segformer-b2-finetuned-ade-512-512` (HuggingFace, дообучен
+  под наши 8 классов, включая background)
+- batch_size=8, lr=6e-5, target epochs=60, early-stopping patience=10
+- Разметка семантическая (не instance) — на UGC test оценивается через
+  connected-components (маска -> инстансы), что методологически невыгодно
+  для этой модели по сравнению с "родными" instance-детекторами
+- val_mIoU ~0.86 на момент заливки (обучение продолжалось дальше сервере)
+- UGC test ещё не прогонялся
+
+## UNet-simple (внешняя модель, не часть основного сравнения)
+
+`unet_baseline/best_model.pt`
+
+- Обучена ВНЕ этого исследования (см. `ResPlan-main/train_resplan_v2.py`
+  в отдельном репозитории) — используется здесь только как референсный
+  бейзлайн "простая семантическая сегментация без всего остального"
+- Архитектура: ванильный UNet (encoder-decoder, DoubleConv-блоки), base
+  filters=64, 8 выходных классов
+- 24 эпохи, val_iou=0.805 (на своих синтетических данных)
+- batch size/lr — не отслеживались нами, обучение внешнее
+- **UGC test**: segm AP@50=0.050, AP@50:95=0.022 — заметно хуже
+  instance-детекторов (2346 сильно фрагментированных предсказаний из-за
+  connected-components на зашумлённой семантической карте, без
+  instance-aware head'а)
+
+## Сводная таблица (UGC test, реальные фото)
+
+| Модель | segm AP@50 | segm AP@50:95 |
+|---|---|---|
+| RF-DETR-Seg (Medium) | 0.277 | 0.175 |
+| YOLO-seg (2 эпохи, устарело) | 0.249 | 0.163 |
+| Mask R-CNN (2 эпохи, устарело) | 0.181 | 0.096 |
+| UNet-simple (24 эпохи, внешняя) | 0.050 | 0.022 |
+| SAM zero-shot (Grounded-SAM) | 0.0002 | 0.0002 |
+
+Провал между валидацией на синтетике (~0.6-0.9 mAP) и UGC test (~0.1-0.3 AP)
+у всех моделей — ожидаемый domain gap между чистыми планами и реальными
+фото объявлений. Таблица будет обновлена по мере дообучения YOLO/Mask R-CNN
+и первого прогона SegFormer на UGC.