Chapter 22 · Huggingface Vision Trainer
Subchapter 22.2
references/hub_saving.mdMarkdown17 KBView on GitHub
CRITICAL: Training environments are ephemeral. ALL results are lost when a job completes unless pushed to the Hub.
When running on Hugging Face Jobs:
Without Hub push, training is completely wasted.
In your TrainingArguments:
from transformers import TrainingArguments
training_args = TrainingArguments(
output_dir="my-object-detector",
push_to_hub=True, # Enable Hub push
hub_model_id="username/model-name", # Target repository
)When submitting the job:
hf_jobs("uv", {
"script": training_script_content, # Pass the Python script content directly as a string
"secrets": {"HF_TOKEN": "$HF_TOKEN"} # Provide authentication
})The $HF_TOKEN syntax references your actual Hugging Face token value.
# train_detector.py
# /// script
# dependencies = ["transformers", "torch", "torchvision", "datasets"]
# ///
from transformers import (
AutoImageProcessor,
AutoModelForObjectDetection,
TrainingArguments,
Trainer
)
from datasets import load_dataset
import os
import torch
# Load dataset
dataset = load_dataset("cppe-5", split="train")
# Load model and processor
model_name = "facebook/detr-resnet-50"
image_processor = AutoImageProcessor.from_pretrained(model_name)
model = AutoModelForObjectDetection.from_pretrained(
model_name,
num_labels=5, # Number of classes
ignore_mismatched_sizes=True
)
# Configure with Hub push
training_args = TrainingArguments(
output_dir="my-detector",
num_train_epochs=10,
per_device_train_batch_size=8,
# ✅ CRITICAL: Hub push configuration
push_to_hub=True,
hub_model_id="myusername/cppe5-detector",
# Optional: Push strategy
hub_strategy="checkpoint", # Push checkpoints during training
)
# ✅ CRITICAL: Authenticate with Hub BEFORE creating Trainer
from huggingface_hub import login
hf_token = os.environ.get("HF_TOKEN") or os.environ.get("hfjob")
if hf_token:
login(token=hf_token)
training_args.hub_token = hf_token
elif training_args.push_to_hub:
raise ValueError("HF_TOKEN not found! Add secrets={'HF_TOKEN': '$HF_TOKEN'} to job config.")
# Define collate function
def collate_fn(batch):
pixel_values = [item["pixel_values"] for item in batch]
labels = [item["labels"] for item in batch]
encoding = image_processor.pad(pixel_values, return_tensors="pt")
return {
"pixel_values": encoding["pixel_values"],
"labels": labels
}
trainer = Trainer(
model=model,
args=training_args,
train_dataset=dataset,
data_collator=collate_fn,
)
trainer.train()
# ✅ Push final model and processor
trainer.push_to_hub()
image_processor.push_to_hub("myusername/cppe5-detector")
print("✅ Model saved to: https://huggingface.co/myusername/cppe5-detector")Submit with authentication:
hf_jobs("uv", {
"script": training_script_content, # Pass script content as a string, NOT a filename
"flavor": "a10g-large",
"timeout": "4h",
"secrets": {"HF_TOKEN": "$HF_TOKEN"} # ✅ Required!
})When push_to_hub=True:
save_strategy="steps" enabledObject detection models require the image processor to be saved separately:
# After training completes
trainer.push_to_hub()
# ✅ Also push the image processor
image_processor.push_to_hub(
repo_id="username/model-name",
commit_message="Upload image processor"
)Why this matters:
Save intermediate checkpoints during training:
TrainingArguments(
output_dir="my-detector",
push_to_hub=True,
hub_model_id="username/my-detector",
# Checkpoint configuration
save_strategy="steps",
save_steps=500, # Save every 500 steps
save_total_limit=3, # Keep only last 3 checkpoints
hub_strategy="checkpoint", # Push checkpoints to Hub
)Benefits:
Checkpoints are pushed to: username/my-detector (same repo)
Add metadata for better discoverability:
# At the end of training script
model.push_to_hub(
"username/my-detector",
commit_message="Upload trained object detection model",
tags=["object-detection", "vision", "cppe-5"],
model_card_kwargs={
"license": "apache-2.0",
"dataset": "cppe-5",
"metrics": ["map", "recall", "precision"],
"pipeline_tag": "object-detection",
}
)Critical for object detection: Save class labels with the model:
# Define your label mappings
id2label = {0: "Coverall", 1: "Face_Shield", 2: "Gloves", 3: "Goggles", 4: "Mask"}
label2id = {v: k for k, v in id2label.items()}
# Update model config before training
model.config.id2label = id2label
model.config.label2id = label2id
# Now train and push
trainer.train()
trainer.push_to_hub()Without label mappings:
For a complete guide on token types, $HF_TOKEN automatic replacement, secrets vs env differences, and security best practices, see the hugging-face-jobs skill → Token Usage Guide.
Recommended: Always pass tokens via secrets (encrypted server-side):
"secrets": {"HF_TOKEN": "$HF_TOKEN"} # ✅ Automatic replacement with your logged-in tokenBefore submitting any training job, verify:
push_to_hub=True in TrainingArgumentshub_model_id is specified (format: username/model-name)If repository doesn’t exist, it’s created automatically when first pushing.
Create repository before training:
from huggingface_hub import HfApi
api = HfApi()
api.create_repo(
repo_id="username/detector-name",
repo_type="model",
private=False, # or True for private repo
)Valid names:
username/detr-cppe5username/yolos-object-detectororganization/custom-detectorInvalid names:
detector-name (missing username)username/detector name (spaces not allowed)username/DETECTOR (uppercase discouraged)Recommended naming:
detr-, yolos-, deta--cppe5, -coco, -vocdetr-resnet50-cppe5 > model1Cause: HF_TOKEN not provided, invalid, or not authenticated before Trainer init
Solutions:
secrets={"HF_TOKEN": "$HF_TOKEN"} in job configlogin(token=hf_token) AND sets training_args.hub_token = hf_token BEFORE creating the Trainerhf auth whoamihf auth loginRoot cause: The Trainer calls create_repo(token=self.args.hub_token) during __init__() when push_to_hub=True. Relying on implicit env-var token resolution is unreliable in Jobs. Calling login() saves the token globally, and setting training_args.hub_token ensures the Trainer passes it explicitly to all Hub API calls.
Cause: No write access to repository
Solutions:
Cause: Repository doesn’t exist and auto-creation failed
Solutions:
Cause: Network issues or Hub unavailable
Solutions:
Possible causes:
Possible causes:
hub_model_id matches loginIf training completes but push fails, push manually:
from transformers import AutoModelForObjectDetection, AutoImageProcessor
# Load from local checkpoint
model = AutoModelForObjectDetection.from_pretrained("./output_dir")
image_processor = AutoImageProcessor.from_pretrained("./output_dir")
# Push to Hub
model.push_to_hub("username/model-name", token="hf_abc123...")
image_processor.push_to_hub("username/model-name", token="hf_abc123...")Note: Only possible if job hasn’t completed (files still exist).
push_to_hub=Truesave_total_limit to avoid excessive checkpointsdetr-cppe5 not detector1)object-detectiondetr, yolos, detacoco, voc, cppe-5Check logs for push progress:
hf_jobs("logs", {"job_id": "your-job-id"})Look for:
Pushing model to username/detector-name...
Upload file pytorch_model.bin: 100%
✅ Model pushed successfully
Pushing image processor...
✅ Image processor pushed successfully# production_detector.py
# /// script
# dependencies = [
# "transformers>=4.30.0",
# "torch>=2.0.0",
# "torchvision>=0.15.0",
# "datasets>=2.12.0",
# "evaluate>=0.4.0"
# ]
# ///
from transformers import (
AutoImageProcessor,
AutoModelForObjectDetection,
TrainingArguments,
Trainer
)
from datasets import load_dataset
import os
import torch
# Configuration
MODEL_NAME
Submit:
hf_jobs("uv", {
"script": training_script_content, # Pass script content as a string, NOT a filename
"flavor": "a10g-large",
"timeout": "8h",
"secrets": {"HF_TOKEN": "$HF_TOKEN"}
})After training, use your model:
from transformers import AutoImageProcessor, AutoModelForObjectDetection
from PIL import Image
import torch
# Load model from Hub
processor = AutoImageProcessor.from_pretrained("username/detr-cppe5-detector")
model = AutoModelForObjectDetection.from_pretrained("username/detr-cppe5-detector")
# Load and process image
image = Image.open("test_image.jpg")
inputs = processor(images=image, return_tensors="pt")
# Run inference
with torch.no_grad():
outputs = model(**inputs)
# Post-process results
target_sizes = torch.tensor([image.size[::-1]])
results = processor.post_process_object_detection(
outputs,
threshold=0.5,
target_sizes=target_sizes
)[0]
# Print detections
for score, label, box in zip(results["scores"], results["labels"], results["boxes"]):
box = [round(i, 2) for i in box.tolist()]
print(
f"Detected {model.config.id2label[label.item()]} with confidence "
f"{round(score.item(), 3)} at location {box}"
)Without push_to_hub=True and secrets={"HF_TOKEN": "$HF_TOKEN"}, all training results are permanently lost.
For object detection, also remember to:
Always verify all three are configured before submitting any training job.