Upload vit-b16-readme.md with huggingface_hub

vit-b16-readme.md

@@ -0,0 +1,168 @@
+---
+base_model: torchvision/vit_b_16 (IMAGENET1K_V1)
+license: apache-2.0
+library_name: pytorch
+pipeline_tag: image-classification
+tags:
+- image-classification
+- flowers
+- oxford-102
+- torchvision
+- vit
+- transfer-learning
+metrics:
+- accuracy
+- f1
+model-index:
+- name: ViT-B/16 Flower Classifier
+  results:
+  - task:
+      type: image-classification
+    dataset:
+      name: Oxford-102 Flowers
+      type: oxford-102-flowers
+      split: validation
+    metrics:
+    - type: accuracy
+      value: 1.0
+    - type: f1
+      value: 1.0
+---
+
+# ViT-B/16 Flower Classifier
+
+Fine-tuned [`torchvision.models.vit_b_16`](https://docs.pytorch.org/vision/main/models/vision_transformer.html) (ImageNet-1K pretrained) for 102-class flower classification on the Oxford-102 Flowers dataset, with the full backbone unfrozen during fine-tuning. Achieves **1.0 accuracy / 1.0 F1** on the validation split.
+
+**Recommended when** accuracy is the only priority and the extra size/latency budget is acceptable — e.g. offline batch labeling, research baselines, or any deployment where a ~344MB model and ~87ms mean inference isn't a constraint. For latency- or memory-constrained serving, see [EfficientNetV2-S Flower Classifier](efficientnetv2-s-readme.md) instead.
+
+## Usage
+
+```python
+import torch
+from huggingface_hub import hf_hub_download
+from torchvision import models
+
+weights_path = hf_hub_download(repo_id="bengid/flower-classifier", filename="ft_ViT-B16.pth")
+
+model = models.vit_b_16(weights=None)
+model.heads[-1] = torch.nn.Linear(model.heads[-1].in_features, 102)
+model.load_state_dict(torch.load(weights_path, map_location="cpu", weights_only=True))
+model.eval()
+
+# preprocessing: resize(256) -> center-crop(224) -> normalize with dataset mean/std
+# see src/utils.py:get_transforms() in the training repo for the exact pipeline
+```
+
+## Training Data
+
+[Oxford-102 Flowers](https://www.robots.ox.ac.uk/~vgg/data/flowers/102/) — 8,189 images across 102 flower species, downloaded via `torchvision.datasets.Flowers102`. Class-weighted `CrossEntropyLoss` was used to correct for the dataset's uneven per-class image counts.
+
+## Training Procedure
+
+Single-stage fine-tune with a **two-phase backbone unfreeze** callback (`BackboneFinetuning`): the ViT backbone starts frozen (only the classification head trains), then unfreezes at a fixed epoch with its own, lower learning rate and a separate parameter group — unlike this project's original (v1) EfficientNet-B0 model, which only ever unfroze its *last 3 backbone blocks*.
+
+### Hyperparameters
+
+| Parameter | Value |
+|---|---|
+| Optimizer | AdamW |
+| LR scheduler | Cosine annealing (T_max=50, eta_min=1e-06) |
+| Head LR (before unfreeze) | 1e-3 |
+| Head LR (after unfreeze) | 1e-3 |
+| Backbone LR (after unfreeze) | 1e-5 |
+| Unfreeze epoch | 5 |
+| Max epochs | 50 |
+| Batch size | 64 |
+| Effective batch size | 256 |
+| Gradient accumulation | 4 |
+| Precision | 16-mixed |
+| Weight decay | 0.01 |
+| Early stopping patience | 5 |
+
+## Evaluation
+
+| Metric | Value |
+|---|---|
+| **Accuracy** | **1.0** |
+| **F1** | **1.0** |
+| Parameters | 85,877,094 |
+| Model size | 343.5 MB |
+| Checkpoint size | 1030.7 MB |
+| Mean latency | 86.5 ms |
+| p95 latency | 104.0 ms |
+
+Latency measured on {} at batch size 1.
+
+## Strengths & Weaknesses
+
+**Strengths:**
+- Best accuracy/F1 of every architecture evaluated for this project (see comparison below) — attention-based global context handles flowers that differ mainly in overall shape/arrangement rather than local texture.
+- Full-backbone fine-tuning lets every ViT layer adapt to the flower domain, avoiding the ceiling that partial-unfreeze approaches hit.
+
+**Weaknesses:**
+- Largest and slowest model in the lineup by a wide margin — ~4x the parameters and ~3x the mean latency of EfficientNetV2-S for a negligible (~0.05pp) accuracy gain.
+- ViTs are comparatively data-hungry and were historically harder to fine-tune from limited data before full-backbone unfreezing + a long enough schedule (see "Why the earlier models underperformed" below) — this model only reaches its ceiling because both were used.
+- Not a good fit for edge/mobile or high-throughput serving given its size and latency.
+
+## Limitations
+
+- **Closed-set, single-label**: trained on exactly 102 Oxford flower species; will confidently misclassify any other flower species, non-flower image, or multi-flower image into one of the 102 known classes — there is no out-of-distribution rejection.
+- **Fixed input pipeline**: expects a 224×224 center-cropped, normalized input (resize-then-crop). Unusual aspect ratios or off-center subjects can crop the flower out of frame.
+- **No adversarial robustness or calibration guarantees** — confidence scores are not calibrated probabilities.
+- Reported metrics are on the Oxford-102 validation split; real-world images (different lighting, backgrounds, camera quality) may perform worse.
+
+## Intended Use
+
+**Intended uses:**
+- Flower species identification within the 102 Oxford-102 classes (gardening/botany apps, educational tools, dataset labeling).
+- Backend model for this project's v2 `/classify` API endpoint when accuracy is prioritized over latency.
+
+**Out-of-scope uses:**
+- General-purpose plant, object, or scene classification outside the 102 trained species.
+- Medical, toxicity, or safety-related plant identification.
+- Any use where a wrong classification has safety or financial consequences without human review.
+
+## Model Comparison
+
+This project trained four models in total, in this order:
+
+| Model | Val Acc | Val F1 | Params | Size (MB) | Best For |
+|---|---|---|---|---|---|
+| [SimpleCNN (scratch)](https://huggingface.co/bengid/flower-classifier/blob/main/flower_model_weights.pth) | ~0.63 | {} | {} | {} | historical baseline only |
+| [EfficientNet-B0 (v1, partial unfreeze)](https://huggingface.co/bengid/flower-classifier/blob/main/ft_EfficientNet-B0.pth) | >0.93 | {} | {} | {} | historical baseline only |
+| [EfficientNetV2-S](https://huggingface.co/bengid/flower-classifier/blob/main/ft_EfficientNetV2-S.pth) | 0.9997 | 0.9995 | 20,308,150 | 81.8 | efficient production serving |
+| **ViT-B/16 (this model)** | **1.0** | **1.0** | 85,877,094 | 343.5 | maximum accuracy |
+
+### Why the earlier models underperformed
+
+- **SimpleCNN (scratch)** was trained from randomly initialized weights with no ImageNet pretraining, on a 6-block custom CNN — too little capacity and too little prior visual knowledge to learn 102 fine-grained flower classes from ~8k images alone.
+- **EfficientNet-B0 (v1)** started from ImageNet-pretrained weights but only ever unfroze its *last 3 backbone blocks* during fine-tuning (see this project's root `README.md`, "Fine-Tuning EfficientNet-B0" section, for the original two-stage recipe) — the earlier backbone layers, tuned for general ImageNet features, never adapted to flower-specific low/mid-level features, capping accuracy well below the fully-unfrozen v2 models.
+- Both **EfficientNetV2-S** and **ViT-B/16** (this model) unfreeze the *entire* backbone during fine-tuning, which is the main driver of the jump from ~93% to ~99.97-100% accuracy.
+
+## License
+
+Apache 2.0, consistent with this project's license.
+
+## Citation
+
+**Base model (Vision Transformer):**
+```bibtex
+@article{dosovitskiy2020vit,
+  title={An Image is Worth 16x16 Words: Transformers for Image Recognition at Scale},
+  author={Dosovitskiy, Alexey and Beyer, Lucas and Kolesnikov, Alexander and Weissenborn, Dirk and Zhai, Xiaohua and Unterthiner, Thomas and Dehghani, Mostafa and Minderer, Matthias and Heigold, Georg and Gelly, Sylvain and Uszkoreit, Jakob and Houlsby, Neil},
+  journal={arXiv preprint arXiv:2010.11929},
+  year={2020}
+}
+```
+
+**Training dataset:**
+```bibtex
+@inproceedings{nilsback2008automated,
+  title={Automated flower classification over a large number of classes},
+  author={Nilsback, Maria-Elena and Zisserman, Andrew},
+  booktitle={2008 Sixth Indian Conference on Computer Vision, Graphics \& Image Processing},
+  pages={722--729},
+  year={2008},
+  organization={IEEE}
+}
+```