Update README_convnext_binding.md

README_convnext_binding.md

@@ -122,8 +122,155 @@ print(f"Не переплёт: {probs[0]:.1%} | Переплёт: {probs[1]:.1%}
 
 ---
 
-## Цитирование
+# Kleine-Marchen — Binding Srednik Detector (DINOv2 Ensemble)
+
+Ансамбль из 5 моделей на базе **DINOv2 ViT-Small** для классификации переплётов рукописей по наличию **средника** — центрального декоративного элемента крышки переплёта.
+
+Модель разработана в рамках исследования рукописного фонда Российской государственной библиотеки (РГБ).
+
+---
+
+## Назначение
+
+Модель решает задачу бинарной классификации изображений переплётов:
+
+- **Класс 1 — со средником**: на крышке переплёта присутствует средник
+- **Класс 0 — без средника**: средник отсутствует
+
+Модель предназначена для автоматической предварительной сортировки больших коллекций фотографий переплётов рукописей. Окончательная верификация результатов производится специалистом.
+
+---
+
+## Метрики
+
+Оценка проводилась методом 5-fold стратифицированной кросс-валидации.
+
+| Метрика | Значение |
+|---|---|
+| Accuracy (OOF Ensemble) | **94.50%** |
+| F1-macro (OOF Ensemble) | **0.9450** |
+| Precision | 0.9454 |
+| Recall | 0.9450 |
+
+**Confusion Matrix (OOF, все 5 фолдов):**
+
+|  | Предсказано: без средника | Предсказано: со средником |
+|---|---|---|
+| **Реально: без средника** | 471 | 20 |
+| **Реально: со средником** | 34 | 457 |
+
+---
+
+## Данные
+
+- **Источник**: фотографии переплётов рукописей из фондов РГБ
+- **Размер обучающей выборки**: 567 изображений на каждый класс (1134 итого)
+- **Формат**: цветные фотографии переплётов на тёмном фоне
+- **Разрешение при обучении**: 280×280 px
+
+Датасет собирался итеративно: после каждого цикла обучения производился анализ ошибок и доразметка сложных случаев (изношенные переплёты, пограничные экземпляры).
+
+---
+
+## Архитектура
+
+**Базовая модель**: `vit_small_patch14_dinov2.lvd142m` (DINOv2 ViT-Small, 22M параметров)
+
+**Голова классификатора**:
+```
+LayerNorm(384) → Linear(384→256) → GELU → Dropout(0.3) → Linear(256→2)
+```
+
+**Стратегия обучения**: двухфазный fine-tuning
+- Фаза 1 (6 эпох): обучение только головы, LR = 5e-4
+- Фаза 2 (20 эпох): голова + последние 4 блока ViT, дифференциальный LR (голова: 3e-5, бэкбон: 2e-6)
+
+**Ансамбль**: 5 моделей (по одной на каждый фолд) с усреднением вероятностей + TTA (5 аугментаций)
+
+---
+
+## Использование
+
+Готовые скрипты для обучения, оценки и инференса доступны в репозитории:
+
+**[https://github.com/Infarondus/Kleine-marchen](https://github.com/Infarondus/Kleine-marchen)**
+
+### Быстрый старт
+
+```python
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+import timm
+import numpy as np
+from PIL import Image
+import albumentations as A
+from albumentations.pytorch import ToTensorV2
+
+MODEL_NAME   = 'vit_small_patch14_dinov2.lvd142m'
+IMAGE_SIZE   = 280
+DINO_MEAN    = [0.485, 0.456, 0.406]
+DINO_STD     = [0.229, 0.224, 0.225]
+
+def build_model():
+    backbone = timm.create_model(
+        MODEL_NAME, pretrained=False, num_classes=0,
+        img_size=IMAGE_SIZE, dynamic_img_size=True,
+    )
+    head = nn.Sequential(
+        nn.LayerNorm(backbone.embed_dim),
+        nn.Linear(backbone.embed_dim, 256),
+        nn.GELU(),
+        nn.Dropout(0.3),
+        nn.Linear(256, 2),
+    )
+    class DinoClassifier(nn.Module):
+        def __init__(self, b, h):
+            super().__init__()
+            self.backbone, self.head = b, h
+        def forward(self, x):
+            return self.head(self.backbone(x))
+    return DinoClassifier(backbone, head)
 
+transform = A.Compose([
+    A.LongestMaxSize(max_size=IMAGE_SIZE),
+    A.PadIfNeeded(min_height=IMAGE_SIZE, min_width=IMAGE_SIZE,
+                  border_mode=0, value=[255, 255, 255]),
+    A.Normalize(mean=DINO_MEAN, std=DINO_STD),
+    ToTensorV2(),
+])
+
+# Загрузка модели
+device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+model  = build_model().to(device)
+ckpt   = torch.load('fold_1_km.pth', map_location=device, weights_only=False)
+model.load_state_dict(ckpt['model_state_dict'])
+model.eval()
+
+# Инференс
+img    = np.array(Image.open('binding.jpg').convert('RGB'))
+tensor = transform(image=img)['image'].unsqueeze(0).to(device)
+with torch.no_grad():
+    probs = F.softmax(model(tensor), dim=1)[0]
+
+print(f"Без средника: {probs[0]:.1%} | Со средником: {probs[1]:.1%}")
+```
+
+### Рекомендуемый порог
+
+При использовании ансамбля рекомендуется порог **0.55–0.75** для класса «со средником» в зависимости от допустимого уровня ложных срабатываний.
+
+---
+
+## Ограничения
+
+- Модель обучена на фотографиях переплётов РГБ и может хуже работать на изображениях из других коллекций (domain shift)
+- Сильно изношенные переплёты с плохо читаемым средником являются наиболее сложными случаями
+- Не предназначена для работы с изображениями страниц, не являющихся переплётами — для фильтрации используйте модель `binding-detector-convnext` на первом этапе
+
+---
+## Цитирование
+Если вы используете эту модель в исследовании, пожалуйста, укажите репозиторий:
 ```
 @misc{kleine-marchen-binding,
   author = {Infarondus},