Untraceable09/AI_Project

Thyroid VFM Lab Starter

Starter repository for the AI lab project described in AI LAB PROJECT SYNOPSIS_aatman.pdf.

The project is organized around two tracks from the synopsis:

1. Detection: thyroid nodule localization from ultrasound frames with YOLO.
2. Classification: benign vs malignant nodule diagnosis with a vision transformer adapted through LoRA.

It also includes a distillation path so a heavier teacher model can supervise a lighter student model for deployment.

What is included

• A project scaffold for Python 3.10+.
• YAML-based experiment configs.
• VOC parsing utilities for TN5000-style annotations.
• A detection data exporter for YOLO training.
• Baseline entry points for classification, detection, and distillation.

Suggested repository layout

data/
  raw/
    JPEGImages/
    Annotations/
    ImageSets/
      Main/
configs/
scripts/
src/
outputs/

Quick start

python -m venv .venv
.venv\Scripts\activate
pip install -e .
python scripts/train_classification.py --config configs/classification_vit_lora.yaml
python scripts/train_detection.py --config configs/detection_yolov8.yaml
python scripts/train_distillation.py --config configs/distillation_mobilenet.yaml

Dataset assumptions

• Official TN5000-style images live under data/raw/JPEGImages.
• Official VOC XML annotations live under data/raw/Annotations.
• Official split files live under data/raw/ImageSets/Main as train.txt, val.txt, and test.txt.
• Each split file contains one image stem or relative image path per line.
• The loader also accepts simplified aliases such as images, annotations, and splits.
• For classification, the current baseline uses the first annotated object as the image label.
• TN5000 labels may appear as 0 and 1 in XML; the loader normalizes them to benign and malignant.

If TN5000 is packaged differently on your machine, update the config paths before training.

Model notes

• The classification baseline uses a Hugging Face ViT checkpoint with LoRA adapters on attention projections.
• The detection baseline converts VOC annotations to YOLO format before training.
• The distillation baseline expects a fine-tuned teacher checkpoint and trains a timm student model with hard-label and KL distillation loss.

Next steps

1. Place TN5000 in data/raw.
2. Verify actual class names in the XML annotations.
3. Decide whether the lab should prioritize detection or classification for the first reportable result.
4. Add experiment tracking and calibration/OOD evaluation once the first baseline is running.