SnakeAid ComputerVision AI Model Training

Tech Stack Overview

Project Overview: SnakeAid Platform

SnakeAid is an AI-powered platform for snakebite first aid and rescue support. It connects patients, snake rescuers, snake experts, and administrators to improve identification, guidance, and response speed.

Core capabilities include:

Step-by-step first aid guidance and safety warnings
AI-based snake species identification and bite severity assessment
SOS with GPS sharing and rescue team tracking
Expert verification and remote consultation
Incident reporting, analytics, and treatment facility lookup

Where This Repository Fits

This repository focuses on the computer vision training pipeline that powers SnakeAid's AI features. It covers dataset preparation, model training, experiment tracking, and deployment-ready model packaging. The outputs here (trained weights, metrics, and export artifacts) are consumed by the broader SnakeAid platform for snake identification and related AI assistance.

For full project scope and product modules, see the project-level documentation in the SnakeAidDocs repository.

🤗 Hugging Face Hub

SnakeAid datasets and trained YOLO checkpoints are published as verified Hugging Face Hub artifacts under the-khiem7.

📊 System Status Dashboard

Item	Value
Hugging Face account	`the-khiem7`
Dataset repositories	`5`
Model repositories	`6`
Verification status	`all_ok: true`
Last verified	`2026-04-08`
Local verification report	`huggingface/HUGGINGFACE_SOURCE_OF_TRUTH_REPORT.json`
Migration record	`huggingface/README.md`
Intentionally excluded checkpoint	`SnakeAI_5k_120e.pt`

🧩 Pipeline Overview

flowchart LR
    A[Raw Snake Images] --> B[YOLO Dataset Versions]
    B --> C["Hugging Face Hub"]
    C --> D[Colab / SageMaker Training]
    D --> E[YOLO PyTorch Checkpoints]
    E --> F[ONNX / CPU Inference]

📚 Datasets

SnakeAid YOLOv12 300 Masking

Hub: https://huggingface.co/datasets/the-khiem7/snakeaid-yolov12-300-masking
Type: Segmentation / masking dataset
Payload: 710 verified files, 353 images

SnakeAid YOLOv12 5000 BBox

Hub: https://huggingface.co/datasets/the-khiem7/snakeaid-yolov12-5000-bbox
Type: Bounding box detection dataset
Payload: 10,586 verified files, 5,291 images

SnakeAid YOLOv12 5000 Masking

Hub: https://huggingface.co/datasets/the-khiem7/snakeaid-yolov12-5000-masking
Type: Segmentation / masking dataset
Payload: 9,918 verified files, 4,957 images

SnakeAid YOLOv12 5291 BBox

Hub: https://huggingface.co/datasets/the-khiem7/snakeaid-yolov12-5291-bbox
Type: Bounding box detection dataset
Payload: 10,586 verified files, 5,291 images

SnakeAid YOLOv12 5291 BBox Complete

Hub: https://huggingface.co/datasets/the-khiem7/snakeaid-yolov12-5291-bbox-complete
Type: Complete bounding box detection dataset
Payload: 10,584 verified files, 5,291 images

🤖 Models

Install the runtime once before loading any checkpoint:

pip install ultralytics huggingface_hub

Use the same loading pattern for every model below by changing repo_id and filename:

from huggingface_hub import hf_hub_download
from ultralytics import YOLO

repo_id = "the-khiem7/snakeaid-detect-yolov12-h2-120e-10p-5291bbox-complete"
filename = "SnakeTraining_H2_YOLOv12_Khiem_Bbox5291Complete_120epoch_10patience_20251215_1346.pt"

checkpoint = hf_hub_download(repo_id, filename)
model = YOLO(checkpoint)
results = model("path/to/snake-image.jpg")

YOLOv12n 10e 300 Masking

Hub: https://huggingface.co/the-khiem7/snakeaid-detect-yolov12n-10e-300masking
Training: YOLOv12n, 10 epochs, 300 masking dataset
Checkpoint: SnakeAid_SnakeDetector_YOLOv12n_300Masking_10epoch_Khiem.pt

YOLOv12n 10e 5000 Masking

Hub: https://huggingface.co/the-khiem7/snakeaid-detect-yolov12n-10e-5000masking
Training: YOLOv12n, 10 epochs, 5000 masking dataset
Checkpoint: SnakeAid_SnakeDetector_YOLOv12n_5000Masking_10epoch_Khiem.pt

YOLOv12s 17e 5000 BBox

Hub: https://huggingface.co/the-khiem7/snakeaid-detect-yolov12s-17e-5000bbox
Training: YOLOv12s, 17 epochs, 5000 bbox dataset
Checkpoint: SnakeAid_SnakeDetector_YOLOv12s_5000Bbox_17epoch_Nhan.pt

YOLOv12 V4 5000 BBox

Hub: https://huggingface.co/the-khiem7/snakeaid-detect-yolov12-v4-5000bbox
Training: YOLOv12 experiment 4, 5000 bbox dataset
Checkpoint: SnakeTraining_V4_YOLOv12_Khiem_Bbox5000_20251213_1828.pt

YOLOv12 V6 40e 5291 BBox Complete

Hub: https://huggingface.co/the-khiem7/snakeaid-detect-yolov12-v6-40e-10p-5291bbox-complete
Training: YOLOv12 experiment 6, 40 epochs, 10 patience, 5291 bbox complete dataset
Checkpoint: SnakeTraining_V6_YOLOv12_Khiem_Bbox5291Complete_40epoch_10patience_20251215_0303.pt

YOLOv12 H2 120e 5291 BBox Complete

Hub: https://huggingface.co/the-khiem7/snakeaid-detect-yolov12-h2-120e-10p-5291bbox-complete
Training: YOLOv12 High Performance Training (nVIDIA H100) experiment 2, 120 epochs, 10 patience, 5291 bbox complete dataset
Checkpoint: SnakeTraining_H2_YOLOv12_Khiem_Bbox5291Complete_120epoch_10patience_20251215_1346.pt

Documentation

Docs are now powered by Docsify in docs/. View them locally with:

npx docsify-cli@latest serve docs

Or install once with npm install -g docsify-cli and run docsify serve docs. The site mirrors the training pipeline, experiment tracking, and artifacts in a navigable sidebar.

Repository Layout

.
|-- docs/                         # Docsify documentation site
|-- huggingface/                  # Hugging Face migration record and verification report
|-- notebooks/
|   |-- training/                 # YOLO training notebook history
|   `-- validation/               # Dataset and label verification notebooks
|-- tools/
|   `-- colab-shutdown-webhook/   # Local webhook helper for Colab completion
`-- README.md                     # Repo entrypoint

Notebooks

Training notebooks:

notebooks/training/SnakeTraining_V1_YOLOv12_Khiem.ipynb
notebooks/training/SnakeTraining_V2_YOLOv12_Khiem.ipynb
notebooks/training/SnakeTraining_V3_YOLOv12_Khiem_Bbox5000.ipynb
notebooks/training/SnakeTraining_V4_YOLOv12_Khiem_Bbox5000.ipynb
notebooks/training/SnakeTraining_V5_YOLOv12_Khiem_Bbox5000.ipynb
notebooks/training/SnakeTraining_V6_YOLOv12_Khiem_Bbox5000.ipynb
notebooks/training/SnakeTraining_V7_YOLOv12_Khiem_Bbox5291.ipynb
notebooks/training/SnakeTraining_V8_YOLOv12_Khiem_Bbox5291.ipynb

Validation notebooks:

notebooks/validation/SnakeAId_LabelVerify.ipynb
notebooks/validation/SnakeDataset_SegmentationVerify.ipynb

Local Tools

The Colab shutdown webhook helper lives in:

tools/colab-shutdown-webhook/

Run it on Windows with:

tools\colab-shutdown-webhook\run-webhook.bat

This repository focuses on the training side of the SnakeAid Computer Vision AI system, covering data preparation, model training, experiment tracking, and deployment-oriented model packaging.

The tech stack is organized following a practical AI / MLOps pipeline, from data labeling to production-ready models.

Data Labeling & Dataset Management

Roboflow

Annote Manage	Data Versioning
Anotating	Labeling

Roboflow is used for:

Image annotation (Bounding Box / Segmentation)
Dataset versioning
Exporting datasets in YOLO-compatible format

Roboflow helps standardize raw image data into structured datasets suitable for training YOLO models, while maintaining consistency across dataset versions.

Role in pipeline: Data preparation & labeling

Model Training Framework

Ultralytics YOLO

Ultralytics YOLO is the core computer vision framework used for:

Object detection and segmentation
Model architecture definition
Training, validation, and evaluation workflows

YOLO is chosen due to its balance between:

Real-time performance
Accuracy
Deployment flexibility (CPU / GPU / ONNX export)

Role in pipeline: Model architecture & training logic

Training Environments

Google Colab

Training	Evaluate
ColabPro	Runtimes

Google Colab serves as the primary training environment, providing:

Easy access to GPU resources
Rapid experimentation via notebooks
Fast iteration during model development

Colab is mainly used for:

Initial experiments
Hyperparameter tuning
Dataset validation

Role in pipeline: Main training platform

Amazon SageMaker (Experimental / Study)

Amazon SageMaker is used as a secondary training platform for:

Studying managed ML workflows
Comparing notebook-based training with cloud-managed training services
Understanding production-grade ML infrastructure concepts

SageMaker usage in this project is experimental and educational, not the primary training path.

Role in pipeline: Training workflow comparison & experimentation

MLOps & Experiment Management

ClearML

ClearML acts as the central MLOps backbone of the project.

It is used for:

Experiment tracking (metrics, parameters, system info)
Model versioning and registry
Artifact management (models, logs, results)
Ensuring reproducibility across training runs

ClearML replaces ad-hoc storage solutions (e.g. Google Drive) as the experiment tracking and training-time model registry. Hugging Face Hub now acts as the public source of truth for the selected migrated datasets and checkpoints listed in the Hugging Face Hub section above.

Role in pipeline: Experiment tracking, model registry, and reproducibility

Model Packaging & Inference Optimization (Optional)

Neural Magic (DeepSparse)

Neural Magic (DeepSparse) is explored as an optional inference optimization layer for:

CPU-based deployments
ONNX model acceleration
Cost-efficient inference on x86 CPU environments

Neural Magic is not required for training, but is studied to evaluate:

CPU inference performance
Cost vs latency trade-offs in production environments

Role in pipeline: CPU inference optimization (optional)

🔗 Tech Stack Summary (Pipeline View)

flowchart TD
    A[Roboflow] --> B[Ultralytics YOLO]
    B --> C[Colab / SageMaker]
    C --> D["ClearML (Tracking & Registry)"]
    D --> E["Hugging Face Hub (Verified Datasets & Checkpoints)"]
    E --> F[ONNX / PyTorch Models]
    F --> G["Neural Magic (CPU Inference)"]

Session 2 — Essential AI Norms

This session explains the essential AI and training concepts that appear directly in the training configuration, logs, and output artifacts of this repository.

The goal is not to teach AI theory, but to help readers:

understand what actually happened during training,
read YOLO training logs without confusion,
interpret common output files generated after training.

No prior deep AI knowledge is assumed.

1. Training Configuration — What the Model Was Asked to Do

Epochs

epochs=120

An epoch means one full pass over the entire training dataset.

Training for 120 epochs means the model is allowed to learn from the same data repeatedly, gradually improving its internal parameters. However, training does not necessarily reach epoch 120 if early stopping is triggered.

Batch Size

batch=32

The batch size defines how many images are processed together before the model updates its weights.

Larger batches provide more stable learning.
Smaller batches reduce GPU memory usage.

Image Size

imgsz=640

YOLO models do not train on raw image sizes. All images are resized to a fixed resolution to:

allow batch processing,
fit the CNN architecture,
optimize GPU computation.

2. Optimization — How the Model Learns

Optimizer: AdamW

optimizer="AdamW"

The optimizer controls how the model updates its parameters.

AdamW is chosen because it:

converges faster than classical SGD,
handles noisy gradients well,
is commonly used in modern object detection tasks.

Learning Rate Strategy

lr0=0.002
lrf=0.01
cos_lr=True
warmup_epochs=3

The learning rate defines how aggressively the model updates its weights.

cos_lr=True enables cosine decay, meaning:
- learning is stronger at the beginning,
- becomes more conservative near the end.
warmup_epochs=3 prevents unstable updates during the first epochs.

Early Stopping

patience=15

Early stopping automatically terminates training if the validation metric does not improve for 15 consecutive epochs.

This:

prevents overfitting,
saves GPU time,
avoids unnecessary training cycles.

3. Data Augmentation — Why the Model Sees Modified Images

The training configuration includes multiple augmentation techniques:

hsv_h, hsv_s, hsv_v
degrees, translate, scale, shear
mosaic, mixup, copy_paste

These augmentations help the model generalize to real-world conditions instead of memorizing the training data.

Mosaic Augmentation

mosaic=1.0
close_mosaic=10

Mosaic combines four images into one during training.

Benefits:

increases object density per image,
improves detection of small objects,
enhances robustness.

Mosaic is disabled during the final epochs (close_mosaic=10) to allow fine-tuning on natural images.

Related output visualization:

train_batch0	train_batch1
train_batch2

MixUp & Copy-Paste

mixup=0.10
copy_paste=0.10

These techniques blend objects or images together to:

reduce overfitting,
expose the model to complex backgrounds,
simulate rare scenarios.

They are applied conservatively to avoid confusing the model.

4. Model Architecture — Understanding the Scale of the Network

From the training log:

231 layers
20,069,970 parameters
68.3 GFLOPs

Parameters (~20M) represent the model's capacity to learn patterns.
GFLOPs measure the computational cost of a single inference.

These numbers directly influence:

inference speed,
deployment cost,
feasibility on CPU vs GPU environments.

5. Evaluation Metrics — What the Numbers Mean

From validation logs:

Box(P)   R   mAP50   mAP50-95

Precision (P)

Among all predicted bounding boxes, how many are correct?

Recall (R)

Among all real objects, how many did the model successfully detect?

mAP50 vs mAP50-95

mAP50 evaluates detection quality at a loose overlap threshold.
mAP50-95 averages performance over stricter thresholds.

A lower mAP50-95 does not imply poor performance — it reflects a harder evaluation standard.

Related curves:

6. Output Artifacts — Understanding Training Results

YOLO training generates multiple artifacts that help interpret model behavior.

Confusion Matrix

confusion_matrix

confusion_matrix_normalized

Shows which classes the model confuses with each other and highlights class imbalance or systematic errors.

Training Curves

Visualize:

loss convergence,
metric stability,
training vs validation trends.

Dataset Statistics

Reveal:

class distribution,
correlation between bounding box dimensions,
potential dataset imbalance.

Prediction Visualization

val_batch0_labels	val_batch0_pred
val_batch1_labels	val_batch1_pred
val_batch2_labels	val_batch2_pred

These images compare:

ground-truth annotations,
model predictions, allowing qualitative error analysis.

7. Why This Session Matters

This session focuses on reading and understanding training outputs, not on abstract AI theory.

By grounding explanations in:

actual training logs,
configuration parameters,
generated artifacts,

readers can build intuition about:

how models learn,
why metrics behave as they do,
how training decisions affect real outcomes.

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.github/workflows		.github/workflows
.vscode		.vscode
docs		docs
huggingface		huggingface
notebooks		notebooks
tools/colab-shutdown-webhook		tools/colab-shutdown-webhook
README.md		README.md

Uh oh!