svngoku/coding-agents-skills/unsloth-hf-jobs

Unsloth Training on HF Jobs

Fine-tune LLMs and VLMs using Unsloth on HF Jobs with UV scripts that handle dependencies automatically.

Prerequisites

• Hugging Face account with token
• HF CLI: curl -LsSf https://hf.co/cli/install.sh | bash
• Dataset on the Hub (see data formats below)

Available Scripts

Remote URL (for HF Jobs): https://huggingface.co/datasets/uv-scripts/unsloth-jobs/raw/main/

Data Formats

VLM Fine-tuning

Requires images and messages columns:

{
    "images": [<PIL.Image>],
    "messages": [
        {"role": "user", "content": [{"type": "image"}, {"type": "text", "text": "What's in this image?"}]},
        {"role": "assistant", "content": [{"type": "text", "text": "A golden retriever playing fetch."}]}
    ]
}

Example dataset: davanstrien/iconclass-vlm-sft

Continued Pretraining

Any dataset with a text column (use --text-column if named differently):

{"text": "Your domain-specific text here..."}

Usage Patterns

VLM Fine-tuning

hf jobs uv run \
  https://huggingface.co/datasets/uv-scripts/unsloth-jobs/raw/main/sft-qwen3-vl.py \
  --flavor a100-large --secrets HF_TOKEN --timeout 4h \
  -- --dataset <username>/<dataset> \
     --num-epochs 1 \
     --eval-split 0.2 \
     --output-repo <username>/<model-name>

Continued Pretraining

hf jobs uv run \
  https://huggingface.co/datasets/uv-scripts/unsloth-jobs/raw/main/continued-pretraining.py \
  --flavor a100-large --secrets HF_TOKEN \
  -- --dataset <username>/<dataset> \
     --text-column content \
     --max-steps 1000 \
     --output-repo <username>/<model-name>

With Trackio Monitoring

Add --trackio-space <username>/trackio to any command for live monitoring.

Common Options

Quick Tips

• Verify setup with --max-steps 10 before full runs
• Use --eval-split 0.1 to detect overfitting
• Check GPU pricing: hf jobs hardware (A100-large ~$2.50/hr, L40S ~$1.80/hr)
• First step may take minutes (CUDA kernel compilation)
• View script options: uv run <script-url> --help

Anti-Patterns to Avoid

• Skipping the smoke test — always verify setup with --max-steps 10 before a full run; config errors cost GPU hours
• Wrong data format for VLMs — VLM fine-tuning requires images + messages columns with image + text content parts; plain text datasets silently fail or train nonsense
• Forgetting `--secrets HF_TOKEN` — the job fails at model download/login; pass the secret explicitly
• Batch size 1 without gradient accumulation — on A100 with 4-bit LoRA you can afford larger batches; accumulation of 1 wastes throughput
• Uploading only the adapter when you need a merged model — set --merge-model if the target is deployment, not another fine-tuning pass
• Training without `--eval-split` — you cannot detect overfitting or pick a checkpoint without a held-out split
• Ignoring `--streaming` on huge datasets — disk may fill up; stream when the dataset doesn't fit locally

When to Use / Not Use

Use this skill when:

• Fine-tuning LLMs or VLMs with Unsloth on HF on-demand cloud GPUs
• Doing LoRA/QLoRA fine-tuning, continued pretraining, or domain adaptation via UV scripts
• You have no local GPU or want ephemeral, pay-per-hour training

Do NOT use this skill when:

• You have local GPUs and prefer on-premises training — use the unsloth skill directly
• The model works with prompting/RAG and doesn't need fine-tuning at all
• You need full control over a custom training stack (TRL, custom loops) — this skill is scoped to the provided UV scripts

Resources

• HF Jobs Quickstart
• Unsloth Documentation
• UV Scripts Guide