SKILL.md · 24000
-prompt_column_name— column with JSON-encoded prompts (default:"prompt"`)
--bbox_column_name— dedicated bbox column (alternative to JSON prompt column)--point_column_name— dedicated point column (alternative to JSON prompt column)--mask_column_name— column with ground-truth masks (default:"mask")--hub_model_id—"username/model-name"for Hub persistence--num_train_epochs— 20-30 typical for SAM fine-tuning--per_device_train_batch_size— 2-4 (SAM models use significant memory)--freeze_vision_encoder/--freeze_prompt_encoder— freeze encoder weights (default: both frozen, only mask decoder trains)--train_val_split— fraction to split for validation (default 0.1)
Checking job status
MCP tool (if available):
hf_jobs("ps") # List all jobs
hf_jobs("logs", {"job_id": "your-job-id"}) # View logs
hf_jobs("inspect", {"job_id": "your-job-id"}) # Job details
Python API fallback:
from huggingface_hub import HfApi
api = HfApi()
api.list_jobs() # List all jobs
api.get_job_logs(job_id="your-job-id") # View logs
api.get_job(job_id="your-job-id") # Job details
Common failure modes
OOM (CUDA out of memory)
Reduce per_device_train_batch_size (try 4, then 2), reduce IMAGE_SIZE, or upgrade hardware.
Dataset format errors
Run scripts/dataset_inspector.py first. The training script auto-detects xyxy vs xywh, converts string categories to integer IDs, and adds image_id if missing. Ensure objects.bbox contains 4-value coordinate lists in absolute pixels and objects.category contains either integer IDs or string labels.
Hub push failures (401)
Verify: (1) job secrets include token (see directive #2), (2) script sets training_args.hub_token BEFORE creating the Trainer, (3) push_to_hub=True is set, (4) correct hub_model_id, (5) token has write permissions.
Job timeout
Increase timeout (see directive #5 table), reduce epochs/dataset, or use checkpoint strategy with hub_strategy="every_save".
KeyError: 'test' (missing test split)
The object detection training script handles this gracefully — it falls back to the validation split. Ensure you're using the latest scripts/object_detection_training.py.
Single-class dataset: "iteration over a 0-d tensor"
torchmetrics.MeanAveragePrecision returns scalar (0-d) tensors for per-class metrics when there's only one class. The template scripts/object_detection_training.py handles this by calling .unsqueeze(0) on these tensors. Ensure you're using the latest template.
Poor detection performance (mAP < 0.15)
Increase epochs (30-50), ensure 500+ images, check per-class mAP for imbalanced classes, try different learning rates (1e-5 to 1e-4), increase image size.
For comprehensive troubleshooting: see references/reliability_principles.md
Reference files
- scripts/object_detection_training.py — Production-ready object detection training script
- scripts/image_classification_training.py — Production-ready image classification training script (supports timm models)
- scripts/sam_segmentation_training.py — Production-ready SAM/SAM2 segmentation training script (bbox & point prompts)
- scripts/dataset_inspector.py — Validate dataset format for OD, classification, and SAM segmentation
- scripts/estimate_cost.py — Estimate training costs for any vision model (includes SAM/SAM2)
- references/object_detection_training_notebook.md — Object detection training workflow, augmentation strategies, and training patterns
- references/image_classification_training_notebook.md — Image classification training workflow with ViT, preprocessing, and evaluation
- references/finetune_sam2_trainer.md — SAM2 fine-tuning walkthrough with MicroMat dataset, DiceCE loss, and Trainer integration
- references/timm_trainer.md — Using timm models with HF Trainer (TimmWrapper, transforms, full example)
- references/hub_saving.md — Detailed Hub persistence guide and verification checklist
- references/reliability_principles.md — Failure prevention principles from production experience
External links
- Transformers Object Detection Guide
- Transformers Image Classification Guide
- DETR Model Documentation
- ViT Model Documentation
- HF Jobs Guide — Main Jobs documentation
- HF Jobs Configuration — Hardware, secrets, timeouts, namespaces
- HF Jobs CLI Reference — Command line interface
- Object Detection Models
- Image Classification Models
- SAM2 Model Documentation
- SAM Model Documentation
- Object Detection Datasets
- Image Classification Datasets