Workflow·Data Science & ML

Hugging Face LLM Trainer

Name: Hugging Face LLM Trainer
Author: huggingface

Train or fine-tune language and vision models using TRL or Unsloth with Hugging Face Jobs infrastructure.

You say

Install this skill Read the source first Free Written by huggingface · unverified publisher

Context cost: 46.6k tokensestimated from the bundle, loaded when it triggers
Bundle: 19 files · 186.6 kB8 scripts among them — read before you run
Licence: Complete terms in LICENSE.txtfree to use
Last change: —no release on file
Servers it uses: Noneruns standalone

What it does

Train or fine-tune language and vision models using TRL (Transformer Reinforcement Learning) or Unsloth with Hugging Face Jobs infrastructure. Covers SFT, DPO, GRPO and reward modeling training methods, plus GGUF conversion for local deployment. Includes guidance on the TRL Jobs package, UV scripts with PEP 723 format, dataset preparation and validation, hardware selection, cost estimation, Trackio monitoring, Hub authentication, model selection/leaderboards and model persistence.

Installed, it changes the agent in these ways.

What this skill changes about the agent is not written down here yet. The listing was collected from its source, and the description is in its own SKILL.md.

Workflow

Runs a procedure end to end.

llmfine-tuningtraininghuggingface

Filed under

Data Science & ML

The skill itself

This is the whole product. A skill is instructions the model reads, so there is nothing behind the listing you cannot see first — the front matter loads with every session, and the body below it loads when the skill triggers.

SKILL.md28.8 kB · 739 lines

--- name: huggingface-llm-trainer description: Train or fine-tune language and vision models using TRL (Transformer Reinforcement Learning) or Unsloth with Hugging Face Jobs infrastructure. Covers SFT, DPO, GRPO and reward modeling training methods, plus GGUF conversion for local deployment. Includes guidance on the TRL Jobs package, UV scripts with PEP 723 format, dataset preparation and validation, hardware selection, cost estimation, Trackio monitoring, Hub authentication, model selection/leaderboards and model persistence. Use for tasks involving cloud GPU training, GGUF conversion, or when users mention training on Hugging Face Jobs without local GPU setup. license: Complete terms in LICENSE.txt ---

7# TRL Training on Hugging Face Jobs

9## Overview

11Train language models using TRL (Transformer Reinforcement Learning) on fully managed Hugging Face infrastructure. No local GPU setup required—models train on cloud GPUs and results are automatically saved to the Hugging Face Hub.

13**TRL provides multiple training methods:**

14- **SFT** (Supervised Fine-Tuning) - Standard instruction tuning

15- **DPO** (Direct Preference Optimization) - Alignment from preference data

16- **GRPO** (Group Relative Policy Optimization) - Online RL training

17- **Reward Modeling** - Train reward models for RLHF

19**For detailed TRL method documentation:**

20```python

21hf_doc_search("your query", product="trl")

22hf_doc_fetch("https://huggingface.co/docs/trl/sft_trainer") # SFT

23hf_doc_fetch("https://huggingface.co/docs/trl/dpo_trainer") # DPO

24# etc.

25```

27**See also:** references/training_methods.md for method overviews and selection guidance

29## When to Use This Skill

31Use this skill when users want to:

32- Fine-tune language models on cloud GPUs without local infrastructure

33- Train with TRL methods (SFT, DPO, GRPO, etc.)

34- Run training jobs on Hugging Face Jobs infrastructure

35- Convert trained models to GGUF for local deployment (Ollama, LM Studio, llama.cpp)

36- Ensure trained models are permanently saved to the Hub

37- Use modern workflows with optimized defaults

39### When to Use Unsloth

41Use **Unsloth** (references/unsloth.md) instead of standard TRL when:

42- **Limited GPU memory** - Unsloth uses ~60% less VRAM

43- **Speed matters** - Unsloth is ~2x faster

44- Training **large models (>13B)** - memory efficiency is critical

45- Training **Vision-Language Models (VLMs)** - Unsloth has FastVisionModel support

47See references/unsloth.md for complete Unsloth documentation and scripts/unsloth_sft_example.py for a production-ready training script.

49## Key Directives

51When assisting with training jobs:

531. **ALWAYS use hf_jobs() MCP tool** - Submit jobs using hf_jobs("uv", {...}), NOT bash trl-jobs commands. The script parameter accepts Python code directly. Do NOT save to local files unless the user explicitly requests it. Pass the script content as a string to hf_jobs(). If user asks to "train a model", "fine-tune", or similar requests, you MUST create the training script AND submit the job immediately using hf_jobs().

552. **Always include Trackio** - Every training script should include Trackio for real-time monitoring. Use example scripts in scripts/ as templates.

573. **Provide job details after submission** - After submitting, provide job ID, monitoring URL, estimated time, and note that the user can request status checks later.

594. **Use example scripts as templates** - Reference scripts/train_sft_example.py, scripts/train_dpo_example.py, etc. as starting points.

61## Local Script Execution

63Repository scripts use PEP 723 inline dependencies. Run them with uv run:

64```bash

65uv run scripts/estimate_cost.py --help

66uv run scripts/dataset_inspector.py --help

67```

69## Prerequisites Checklist

71Before starting any training job, verify:

73### ✅ **Account & Authentication**

74- Hugging Face Account with [Pro](https://hf.co/pro), [Team](https://hf.co/enterprise), or [Enterprise](https://hf.co/enterprise) plan (Jobs require paid plan)

75- Authenticated login: Check with hf_whoami()

76- **HF_TOKEN for Hub Push** ⚠️ CRITICAL - Training environment is ephemeral, must push to Hub or ALL training results are lost

77- Token must have write permissions

78- **MUST pass secrets={"HF_TOKEN": "$HF_TOKEN"} in job config** to make token available (the $HF_TOKEN syntax

79 references your actual token value)

81### ✅ **Dataset Requirements**

82- Dataset must exist on Hub or be loadable via datasets.load_dataset()

83- Format must match training method (SFT: "messages"/text/prompt-completion; DPO: chosen/rejected; GRPO: prompt-only)

84- **ALWAYS validate unknown datasets** before GPU training to prevent format failures (see Dataset Validation section below)

85- Size appropriate for hardware (Demo: 50-100 examples on t4-small; Production: 1K-10K+ on a10g-large/a100-large)

87### ⚠️ **Critical Settings**

88- **Timeout must exceed expected training time** - Default 30min is TOO SHORT for most training. Minimum recommended: 1-2 hours. Job fails and loses all progress if timeout is exceeded.

89- **Hub push must be enabled** - Config: push_to_hub=True, hub_model_id="username/model-name"; Job: secrets={"HF_TOKEN": "$HF_TOKEN"}

91## Asynchronous Job Guidelines

93**⚠️ IMPORTANT: Training jobs run asynchronously and can take hours**

95### Action Required

97**When user requests training:**

981. **Create the training script** with Trackio included (use scripts/train_sft_example.py as template)

992. **Submit immediately** using hf_jobs() MCP tool with script content inline - don't save to file unless user requests

1003. **Report submission** with job ID, monitoring URL, and estimated time

1014. **Wait for user** to request status checks - don't poll automatically

102

103### Ground Rules

104- **Jobs run in background** - Submission returns immediately; training continues independently

105- **Initial logs delayed** - Can take 30-60 seconds for logs to appear

106- **User checks status** - Wait for user to request status updates

107- **Avoid polling** - Check logs only on user request; provide monitoring links instead

108

109### After Submission

110

111**Provide to user:**

112- ✅ Job ID and monitoring URL

113- ✅ Expected completion time

114- ✅ Trackio dashboard URL

115- ✅ Note that user can request status checks later

116

117**Example Response:**

118```

119✅ Job submitted successfully!

120

121Job ID: abc123xyz

122Monitor: https://huggingface.co/jobs/username/abc123xyz

123

124Expected time: ~2 hours

125Estimated cost: ~$10

126

127The job is running in the background. Ask me to check status/logs when ready!

128```

129

130## Quick Start: Three Approaches

131

132**💡 Tip for Demos:** For quick demos on smaller GPUs (t4-small), omit eval_dataset and eval_strategy to save ~40% memory. You'll still see training loss and learning progress.

133

134### Sequence Length Configuration

135

136**TRL config classes use max_length (not max_seq_length)** to control tokenized sequence length:

137

138```python

139# ✅ CORRECT - If you need to set sequence length

140SFTConfig(max_length=512) # Truncate sequences to 512 tokens

141DPOConfig(max_length=2048) # Longer context (2048 tokens)

142

143# ❌ WRONG - This parameter doesn't exist

144SFTConfig(max_seq_length=512) # TypeError!

145```

146

147**Default behavior:** max_length=1024 (truncates from right). This works well for most training.

148

149**When to override:**

150- **Longer context**: Set higher (e.g., max_length=2048)

151- **Memory constraints**: Set lower (e.g., max_length=512)

152- **Vision models**: Set max_length=None (prevents cutting image tokens)

153

154**Usually you don't need to set this parameter at all** - the examples below use the sensible default.

155

156### Approach 1: UV Scripts (Recommended—Default Choice)

157

158UV scripts use PEP 723 inline dependencies for clean, self-contained training. **This is the primary approach for Claude Code.**

159

160```python

161hf_jobs("uv", {

162 "script": """

163# /// script

164# dependencies = ["trl>=0.12.0", "peft>=0.7.0", "trackio"]

165# ///

166

167from datasets import load_dataset

168from peft import LoraConfig

169from trl import SFTTrainer, SFTConfig

170import trackio

171

172dataset = load_dataset("trl-lib/Capybara", split="train")

173

174# Create train/eval split for monitoring

175dataset_split = dataset.train_test_split(test_size=0.1, seed=42)

176

177trainer = SFTTrainer(

178 model="Qwen/Qwen2.5-0.5B",

179 train_dataset=dataset_split["train"],

180 eval_dataset=dataset_split["test"],

181 peft_config=LoraConfig(r=16, lora_alpha=32),

182 args=SFTConfig(

183 output_dir="my-model",

184 push_to_hub=True,

185 hub_model_id="username/my-model",

186 num_train_epochs=3,

187 eval_strategy="steps",

188 eval_steps=50,

189 report_to="trackio",

190 project="meaningful_prject_name", # project name for the training name (trackio)

191 run_name="meaningful_run_name", # descriptive name for the specific training run (trackio)

192 )

193)

194

195trainer.train()

196trainer.push_to_hub()

197""",

198 "flavor": "a10g-large",

199 "timeout": "2h",

200 "secrets": {"HF_TOKEN": "$HF_TOKEN"}

201})

202```

203

204**Benefits:** Direct MCP tool usage, clean code, dependencies declared inline (PEP 723), no file saving required, full control

205**When to use:** Default choice for all training tasks in Claude Code, custom training logic, any scenario requiring hf_jobs()

206

207#### Working with Scripts

208

209⚠️ **Important:** The script parameter accepts either inline code (as shown above) OR a URL. **Local file paths do NOT work.**

210

211**Why local paths don't work:**

212Jobs run in isolated Docker containers without access to your local filesystem. Scripts must be:

213- Inline code (recommended for custom training)

214- Publicly accessible URLs

215- Private repo URLs (with HF_TOKEN)

216

217**Common mistakes:**

218```python

219# ❌ These will all fail

220hf_jobs("uv", {"script": "train.py"})

221hf_jobs("uv", {"script": "./scripts/train.py"})

222hf_jobs("uv", {"script": "/path/to/train.py"})

223```

224

225**Correct approaches:**

226```python

227# ✅ Inline code (recommended)

228hf_jobs("uv", {"script": "# /// script\n# dependencies = [...]\n# ///\n\n<your code>"})

229

230# ✅ From Hugging Face Hub

231hf_jobs("uv", {"script": "https://huggingface.co/user/repo/resolve/main/train.py"})

232

233# ✅ From GitHub

234hf_jobs("uv", {"script": "https://raw.githubusercontent.com/user/repo/main/train.py"})

235

236# ✅ From Gist

237hf_jobs("uv", {"script": "https://gist.githubusercontent.com/user/id/raw/train.py"})

238```

239

240**To use local scripts:** Upload to HF Hub first:

241```bash

242hf repos create my-training-scripts --type model

243hf upload my-training-scripts ./train.py train.py

244# Use: https://huggingface.co/USERNAME/my-training-scripts/resolve/main/train.py

245```

246

247### Approach 2: TRL Maintained Scripts (Official Examples)

248

249TRL provides battle-tested scripts for all methods. Can be run from URLs:

250

251```python

252hf_jobs("uv", {

253 "script": "https://github.com/huggingface/trl/blob/main/trl/scripts/sft.py",

254 "script_args": [

255 "--model_name_or_path", "Qwen/Qwen2.5-0.5B",

256 "--dataset_name", "trl-lib/Capybara",

257 "--output_dir", "my-model",

258 "--push_to_hub",

259 "--hub_model_id", "username/my-model"

260 ],

261 "flavor": "a10g-large",

262 "timeout": "2h",

263 "secrets": {"HF_TOKEN": "$HF_TOKEN"}

264})

265```

266

267**Benefits:** No code to write, maintained by TRL team, production-tested

268**When to use:** Standard TRL training, quick experiments, don't need custom code

269**Available:** Scripts are available from https://github.com/huggingface/trl/tree/main/examples/scripts

270

271### Finding More UV Scripts on Hub

272

273The uv-scripts organization provides ready-to-use UV scripts stored as datasets on Hugging Face Hub:

274

275```python

276# Discover available UV script collections

277dataset_search({"author": "uv-scripts", "sort": "downloads", "limit": 20})

278

279# Explore a specific collection

280hub_repo_details(["uv-scripts/classification"], repo_type="dataset", include_readme=True)

281```

282

283**Popular collections:** ocr, classification, synthetic-data, vllm, dataset-creation

284

285### Approach 3: HF Jobs CLI (Direct Terminal Commands)

286

287When the hf_jobs() MCP tool is unavailable, use the hf jobs CLI directly.

288

289**⚠️ CRITICAL: CLI Syntax Rules**

290

291```bash

292# ✅ CORRECT syntax - flags BEFORE script URL

293hf jobs uv run --flavor a10g-large --timeout 2h --secrets HF_TOKEN "https://example.com/train.py"

294

295# ❌ WRONG - "run uv" instead of "uv run"

296hf jobs run uv "https://example.com/train.py" --flavor a10g-large

297

298# ❌ WRONG - flags AFTER script URL (will be ignored!)

299hf jobs uv run "https://example.com/train.py" --flavor a10g-large

300

301# ❌ WRONG - "--secret" instead of "--secrets" (plural)

302hf jobs uv run --secret HF_TOKEN "https://example.com/train.py"

303```

304

305**Key syntax rules:**

3061. Command order is hf jobs uv run (NOT hf jobs run uv)

3072. All flags (--flavor, --timeout, --secrets) must come BEFORE the script URL

3083. Use --secrets (plural), not --secret

3094. Script URL must be the last positional argument

310

311**Complete CLI example:**

312```bash

313hf jobs uv run \

314 --flavor a10g-large \

315 --timeout 2h \

316 --secrets HF_TOKEN \

317 "https://huggingface.co/user/repo/resolve/main/train.py"

318```

319

320**Check job status via CLI:**

321```bash

322hf jobs ps # List all jobs

323hf jobs logs <job-id> # View logs

324hf jobs inspect <job-id> # Job details

325hf jobs cancel <job-id> # Cancel a job

326```

327

328### Approach 4: TRL Jobs Package (Simplified Training)

329

330The trl-jobs package provides optimized defaults and one-liner training.

331

332```bash

333uvx trl-jobs sft \

334 --model_name Qwen/Qwen2.5-0.5B \

335 --dataset_name trl-lib/Capybara

336

337```

338

339**Benefits:** Pre-configured settings, automatic Trackio integration, automatic Hub push, one-line commands

340**When to use:** User working in terminal directly (not Claude Code context), quick local experimentation

341**Repository:** https://github.com/huggingface/trl-jobs

342

343⚠️ **In Claude Code context, prefer using hf_jobs() MCP tool (Approach 1) when available.**

344

345## Hardware Selection

346

348|------------|---------------------|------------------|----------|

354

355**GPU Flavors:** cpu-basic/upgrade/performance/xl, t4-small/medium, l4x1/x4, a10g-small/large/largex2/largex4, a100-large, h100/h100x8

356

357**Guidelines:**

358- Use **LoRA/PEFT** for models >7B to reduce memory

359- Multi-GPU automatically handled by TRL/Accelerate

360- Start with smaller hardware for testing

361

362**See:** references/hardware_guide.md for detailed specifications

363

364## Critical: Saving Results to Hub

365

366**⚠️ EPHEMERAL ENVIRONMENT—MUST PUSH TO HUB**

367

368The Jobs environment is temporary. All files are deleted when the job ends. If the model isn't pushed to Hub, **ALL TRAINING IS LOST**.

369

370### Required Configuration

371

372**In training script/config:**

373```python

374SFTConfig(

375 push_to_hub=True,

376 hub_model_id="username/model-name", # MUST specify

377 hub_strategy="every_save", # Optional: push checkpoints

378)

379```

380

381**In job submission:**

382```python

383{

384 "secrets": {"HF_TOKEN": "$HF_TOKEN"} # Enables authentication

385}

386```

387

388### Verification Checklist

389

390Before submitting:

391- [ ] push_to_hub=True set in config

392- [ ] hub_model_id includes username/repo-name

393- [ ] secrets parameter includes HF_TOKEN

394- [ ] User has write access to target repo

395

396**See:** references/hub_saving.md for detailed troubleshooting

397

398## Timeout Management

399

400**⚠️ DEFAULT: 30 MINUTES—TOO SHORT FOR TRAINING**

401

402### Setting Timeouts

403

404```python

405{

406 "timeout": "2h" # 2 hours (formats: "90m", "2h", "1.5h", or seconds as integer)

407}

408```

409

410### Timeout Guidelines

411

412| Scenario | Recommended | Notes |

413|----------|-------------|-------|

414| Quick demo (50-100 examples) | 10-30 min | Verify setup |

415| Development training | 1-2 hours | Small datasets |

416| Production (3-7B model) | 4-6 hours | Full datasets |

417| Large model with LoRA | 3-6 hours | Depends on dataset |

418

419**Always add 20-30% buffer** for model/dataset loading, checkpoint saving, Hub push operations, and network delays.

420

421**On timeout:** Job killed immediately, all unsaved progress lost, must restart from beginning

422

423## Choose a Base Model (Model Selection)

424

425**Identify models to train based on task type or benchmark results.**

426

427Use scripts/hf_benchmarks.py to identify top-performing models for specific tasks. This helps the user select a model as the base for training, whilst keeping size and hardware constraints in mind.

428

429```bash

430# Get help on the benchmarks command:

431uv run scripts/hf_benchmarks.py --help

432```

433

434### Example -- choosing an OCR base model

435```bash

436# Search for benchmarks containing whose name contains the text ocr

437uv run scripts/hf_benchmarks.py search --query ocr

438

439# Get the ranked leaderboard for the allenai/olmOCR-bench benchmark

440uv run scripts/hf_benchmarks.py leaderboard allenai/olmOCR-bench

441```

442

443## Cost Estimation

444

445**Offer to estimate cost when planning jobs with known parameters.** Use scripts/estimate_cost.py:

446

447```bash

448uv run scripts/estimate_cost.py \

449 --model meta-llama/Llama-2-7b-hf \

450 --dataset trl-lib/Capybara \

451 --hardware a10g-large \

452 --dataset-size 16000 \

453 --epochs 3

454```

455

456Output includes estimated time, cost, recommended timeout (with buffer), and optimization suggestions.

457

458**When to offer:** User planning a job, asks about cost/time, choosing hardware, job will run >1 hour or cost >$5

459

460## Example Training Scripts

461

462**Production-ready templates with all best practices:**

463

464Load these scripts for correctly:

465

466- **scripts/train_sft_example.py** - Complete SFT training with Trackio, LoRA, checkpoints

467- **scripts/train_dpo_example.py** - DPO training for preference learning

468- **scripts/train_grpo_example.py** - GRPO training for online RL

469

470These scripts demonstrate proper Hub saving, Trackio integration, checkpoint management, and optimized parameters. Pass their content inline to hf_jobs() or use as templates for custom scripts.

471

472## Monitoring and Tracking

473

474**Trackio** provides real-time metrics visualization. See references/trackio_guide.md for complete setup guide.

475

476**Key points:**

477- Add trackio to dependencies

478- Configure trainer with report_to="trackio" and run_name="meaningful_name"

479

480### Trackio Configuration Defaults

481

482**Use sensible defaults unless user specifies otherwise.** When generating training scripts with Trackio:

483

484**Default Configuration:**

485- **Space ID**: {username}/trackio (use "trackio" as default space name)

486- **Run naming**: Unless otherwise specified, name the run in a way the user will recognize (e.g., descriptive of the task, model, or purpose)

487- **Config**: Keep minimal - only include hyperparameters and model/dataset info

488- **Project Name**: Use a Project Name to associate runs with a particular Project

489

490**User overrides:** If user requests specific trackio configuration (custom space, run naming, grouping, or additional config), apply their preferences instead of defaults.

491

492

493This is useful for managing multiple jobs with the same configuration or keeping training scripts portable.

494

495See references/trackio_guide.md for complete documentation including grouping runs for experiments.

496

497### Check Job Status

498

499```python

500# List all jobs

501hf_jobs("ps")

502

503# Inspect specific job

504hf_jobs("inspect", {"job_id": "your-job-id"})

505

506# View logs

507hf_jobs("logs", {"job_id": "your-job-id"})

508```

509

510**Remember:** Wait for user to request status checks. Avoid polling repeatedly.

511

512## Dataset Validation

513

514**Validate dataset format BEFORE launching GPU training to prevent the #1 cause of training failures: format mismatches.**

515

516### Why Validate

517

518- 50%+ of training failures are due to dataset format issues

519- DPO especially strict: requires exact column names (prompt, chosen, rejected)

520- Failed GPU jobs waste $1-10 and 30-60 minutes

521- Validation on CPU costs ~$0.01 and takes <1 minute

522

523### When to Validate

524

525**ALWAYS validate for:**

526- Unknown or custom datasets

527- DPO training (CRITICAL - 90% of datasets need mapping)

528- Any dataset not explicitly TRL-compatible

529

530**Skip validation for known TRL datasets:**

531- trl-lib/ultrachat_200k, trl-lib/Capybara, HuggingFaceH4/ultrachat_200k, etc.

532

533### Usage

534

535```python

536hf_jobs("uv", {

537 "script": "https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py",

538 "script_args": ["--dataset", "username/dataset-name", "--split", "train"]

539})

540```

541

542The script is fast, and will usually complete synchronously.

543

544### Reading Results

545

546The output shows compatibility for each training method:

547

548- **✓ READY** - Dataset is compatible, use directly

549- **✗ NEEDS MAPPING** - Compatible but needs preprocessing (mapping code provided)

550- **✗ INCOMPATIBLE** - Cannot be used for this method

551

552When mapping is needed, the output includes a **"MAPPING CODE"** section with copy-paste ready Python code.

553

554### Example Workflow

555

556```python

557# 1. Inspect dataset (costs ~$0.01, <1 min on CPU)

558hf_jobs("uv", {

559 "script": "https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py",

560 "script_args": ["--dataset", "argilla/distilabel-math-preference-dpo", "--split", "train"]

561})

562

563# 2. Check output markers:

564# ✓ READY → proceed with training

565# ✗ NEEDS MAPPING → apply mapping code below

566# ✗ INCOMPATIBLE → choose different method/dataset

567

568# 3. If mapping needed, apply before training:

569def format_for_dpo(example):

570 return {

571 'prompt': example['instruction'],

572 'chosen': example['chosen_response'],

573 'rejected': example['rejected_response'],

574 }

575dataset = dataset.map(format_for_dpo, remove_columns=dataset.column_names)

576

577# 4. Launch training job with confidence

578```

579

580### Common Scenario: DPO Format Mismatch

581

582Most DPO datasets use non-standard column names. Example:

583

584```

585Dataset has: instruction, chosen_response, rejected_response

586DPO expects: prompt, chosen, rejected

587```

588

589The validator detects this and provides exact mapping code to fix it.

590

591## Converting Models to GGUF

592

593After training, convert models to **GGUF format** for use with llama.cpp, Ollama, LM Studio, and other local inference tools.

594

595**What is GGUF:**

596- Optimized for CPU/GPU inference with llama.cpp

597- Supports quantization (4-bit, 5-bit, 8-bit) to reduce model size

598- Compatible with Ollama, LM Studio, Jan, GPT4All, llama.cpp

599- Typically 2-8GB for 7B models (vs 14GB unquantized)

600

601**When to convert:**

602- Running models locally with Ollama or LM Studio

603- Reducing model size with quantization

604- Deploying to edge devices

605- Sharing models for local-first use

606

607**See:** references/gguf_conversion.md for complete conversion guide, including production-ready conversion script, quantization options, hardware requirements, usage examples, and troubleshooting.

608

609**Quick conversion:**

610```python

611hf_jobs("uv", {

612 "script": "<see references/gguf_conversion.md for complete script>",

613 "flavor": "a10g-large",

614 "timeout": "45m",

615 "secrets": {"HF_TOKEN": "$HF_TOKEN"},

616 "env": {

617 "ADAPTER_MODEL": "username/my-finetuned-model",

618 "BASE_MODEL": "Qwen/Qwen2.5-0.5B",

619 "OUTPUT_REPO": "username/my-model-gguf"

620 }

621})

622```

623

624## Common Training Patterns

625

626See references/training_patterns.md for detailed examples including:

627- Quick demo (5-10 minutes)

628- Production with checkpoints

629- Multi-GPU training

630- DPO training (preference learning)

631- GRPO training (online RL)

632

633## Common Failure Modes

634

635### Out of Memory (OOM)

636

637**Fix (try in order):**

6381. Reduce batch size: per_device_train_batch_size=1, increase gradient_accumulation_steps=8. Effective batch size is per_device_train_batch_size x gradient_accumulation_steps. For best performance keep effective batch size close to 128.

6392. Enable: gradient_checkpointing=True

6403. Upgrade hardware: t4-small → l4x1, a10g-small → a10g-large etc.

641

642### Dataset Misformatted

643

644**Fix:**

6451. Validate first with dataset inspector:

646 ```bash

647 uv run https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py \

648 --dataset name --split train

649 ```

6502. Check output for compatibility markers (✓ READY, ✗ NEEDS MAPPING, ✗ INCOMPATIBLE)

6513. Apply mapping code from inspector output if needed

652

653### Job Timeout

654

655**Fix:**

6561. Check logs for actual runtime: hf_jobs("logs", {"job_id": "..."})

6572. Increase timeout with buffer: "timeout": "3h" (add 30% to estimated time)

6583. Or reduce training: lower num_train_epochs, use smaller dataset, enable max_steps

6594. Save checkpoints: save_strategy="steps", save_steps=500, hub_strategy="every_save"

660

661**Note:** Default 30min is insufficient for real training. Minimum 1-2 hours.

662

663### Hub Push Failures

664

665**Fix:**

6661. Add to job: secrets={"HF_TOKEN": "$HF_TOKEN"}

6672. Add to config: push_to_hub=True, hub_model_id="username/model-name"

6683. Verify auth: mcp__huggingface__hf_whoami()

6694. Check token has write permissions and repo exists (or set hub_private_repo=True)

670

671### Missing Dependencies

672

673**Fix:**

674Add to PEP 723 header:

675```python

676# /// script

677# dependencies = ["trl>=0.12.0", "peft>=0.7.0", "trackio", "missing-package"]

678# ///

679```

680

681## Troubleshooting

682

683**Common issues:**

684- Job times out → Increase timeout, reduce epochs/dataset, use smaller model/LoRA

685- Model not saved to Hub → Check push_to_hub=True, hub_model_id, secrets=HF_TOKEN

686- Out of Memory (OOM) → Reduce batch size, increase gradient accumulation, enable LoRA, use larger GPU

687- Dataset format error → Validate with dataset inspector (see Dataset Validation section)

688- Import/module errors → Add PEP 723 header with dependencies, verify format

689- Authentication errors → Check mcp__huggingface__hf_whoami(), token permissions, secrets parameter

690

691**See:** references/troubleshooting.md for complete troubleshooting guide

692

693## Resources

694

695### References (In This Skill)

696- references/training_methods.md - Overview of SFT, DPO, GRPO, KTO, PPO, Reward Modeling

697- references/training_patterns.md - Common training patterns and examples

698- references/unsloth.md - Unsloth for fast VLM training (~2x speed, 60% less VRAM)

699- references/gguf_conversion.md - Complete GGUF conversion guide

700- references/trackio_guide.md - Trackio monitoring setup

701- references/hardware_guide.md - Hardware specs and selection

702- references/hub_saving.md - Hub authentication troubleshooting

703- references/troubleshooting.md - Common issues and solutions

704- references/local_training_macos.md - Local training on macOS

705

706### Scripts (In This Skill)

707- scripts/train_sft_example.py - Production SFT template

708- scripts/train_dpo_example.py - Production DPO template

709- scripts/train_grpo_example.py - Production GRPO template

710- scripts/unsloth_sft_example.py - Unsloth text LLM training template (faster, less VRAM)

711- scripts/estimate_cost.py - Estimate time and cost (offer when appropriate)

712- scripts/convert_to_gguf.py - Complete GGUF conversion script

713- scripts/hf_benchmarks.py - Search for benchmark results and leaderboards by task, alias or free text.

714

715### External Scripts

716- [Dataset Inspector](https://huggingface.co/datasets/mcp-tools/skills/raw/main/dataset_inspector.py) - Validate dataset format before training (use via uv run or hf_jobs)

717

718### External Links

719- [TRL Documentation](https://huggingface.co/docs/trl)

720- [TRL Jobs Training Guide](https://huggingface.co/docs/trl/en/jobs_training)

721- [TRL Jobs Package](https://github.com/huggingface/trl-jobs)

722- [HF Jobs Documentation](https://huggingface.co/docs/huggingface_hub/guides/jobs)

723- [TRL Example Scripts](https://github.com/huggingface/trl/tree/main/examples/scripts)

724- [UV Scripts Guide](https://docs.astral.sh/uv/guides/scripts/)

725- [UV Scripts Organization](https://huggingface.co/uv-scripts)

726

727## Key Takeaways

728

7291. **Submit scripts inline** - The script parameter accepts Python code directly; no file saving required unless user requests

7302. **Jobs are asynchronous** - Don't wait/poll; let user check when ready

7313. **Always set timeout** - Default 30 min is insufficient; minimum 1-2 hours recommended

7324. **Always enable Hub push** - Environment is ephemeral; without push, all results lost

7335. **Include Trackio** - Use example scripts as templates for real-time monitoring

7346. **Offer cost estimation** - When parameters are known, use scripts/estimate_cost.py

7357. **Use UV scripts (Approach 1)** - Default to hf_jobs("uv", {...}) with inline scripts; TRL maintained scripts for standard training; avoid bash trl-jobs commands in Claude Code

7368. **Use hf_doc_fetch/hf_doc_search** for latest TRL documentation

7379. **Validate dataset format** before training with dataset inspector (see Dataset Validation section)

73810. **Choose appropriate hardware** for model size; use LoRA for models >7B

739

In the file

SKILL.md3,596 words

Files19

LicenceComplete terms in LICENSE.txt

Why you can read it

Nothing in a skill executes. The client loads the text and the model follows it, so a skill can be audited the way a runbook is — by reading it.

What it costs in context

Skills are not billed by the call. They are paid for in context: every token the instructions occupy is a token your code, your diff and your conversation cannot use. Here is what this one takes and when it takes it.

≈180

always loaded

The name and description, so the model knows the skill exists and when to reach for it.

46,470

on trigger

The instruction body and 18 supporting files, read only when the skill fires.

23.3%

of a 200k window

Ten skills this size would take about 233% of the window before you open a file.

050k100k150k200k context window

46.6k tokens, estimated from the bundle at four bytes to the token, held for the rest of the session once it triggers. Heavy. Teams tend to install this one per project rather than globally, and load it only when the job comes up.

Servers bill, skills cost

A server charges by the month. A skill charges once per session, in context, and then keeps charging it for as long as the session lives.

Before and after

The same question, put to the same model twice: once as it comes, and once with these instructions loaded.

No worked example has been published for this skill yet.

Adoption

Installsnone yet

Ratingno reviews yet

The procedure it runs

The procedure has not been published here. It is in the skill’s own SKILL.md, which its author has not sent to the marketplace yet.

Prose, not code

These steps are written for a model to follow, not executed by a runtime. It can still be told to skip one, and it will say so when it does.

Servers it uses

None. This skill calls no MCP servers at all.

Everything it needs is in the instructions, so it works in a project with nothing connected — the model reads the file and changes how it works with what it can already reach.

It writes no files and reaches no network. All it changes is how the model reasons and writes.

What it asks for

Writes filesno

Network accessno

Read from the allowed-tools line of this skill’s own SKILL.md. A skill grants no permissions of its own — it can only ask for tools your client already has.

What it will not do

Every skill is narrow, and the useful ones say where they stop. These are the jobs this one is the wrong tool for.

What this skill is not for has not been published here. Nothing is implied by that: it is a section the author has not filled in.

If this is not it

12 other skills in Data Science & ML

What is in the bundle

19 files, 186.6 kB on disk. Mostly text — the instructions the model reads — with 8 scripts in it that your client would run only if the instructions tell it to.

SKILL.md28.8 kB
references/gguf_conversion.md9.9 kB
references/hardware_guide.md6.8 kB
references/hub_saving.md8.5 kB
references/local_training_macos.md8.3 kB
references/reliability_principles.md10.9 kB
references/trackio_guide.md6.4 kB
references/training_methods.md5.0 kB
references/training_patterns.md6.1 kB
references/troubleshooting.md8.9 kB
references/unsloth.md8.0 kB
scripts/convert_to_gguf.py12.6 kB
scripts/dataset_inspector.py15.7 kB
scripts/estimate_cost.py4.9 kB
scripts/hf_benchmarks.py20.1 kB
scripts/train_dpo_example.py3.1 kB
scripts/train_grpo_example.py2.4 kB
scripts/train_sft_example.py3.3 kB
scripts/unsloth_sft_example.py16.9 kB

What is not in it

A skill installs nothing and depends on nothing: it is a folder your client reads. This one carries 8 scripts beside the text, so the bundle is 19 files you can review in full before installing. The Complete terms in LICENSE.txt licence covers the templates and examples as well as the instructions.

Install

Installing copies the bundle into your project. Nothing runs at install time — the files sit on disk until the model reads them.

# Hugging Face LLM Trainer · 46.6k tokens when loaded
npx mcprush@latest skill add huggingface/hugging-face-llm-trainer

Writes to .claude/skills/hugging-face-llm-trainer/ in the current project. Add --global to put it in your home directory instead, for every project.

Which clients pick it up on their own

A skill is a folder of text. A client with a skills folder reads it without being told; everywhere else the same text works, it is just handed to the model rather than found.

Claude Code.claude/skills/

Claude Desktop

ChatGPT

Cursor.cursor/skills/

VS Code.github/skills/

Codex CLI.agents/skills/

Gemini CLI.gemini/skills/

Grok.grok/skills/

Zed.agents/skills/

Windsurf.windsurf/skills/

Agent SDK.claude/skills/

HTTP / API

This release

Versionnot versioned

Publishedno release date on file

PriceFree

Referencehuggingface/hugging-face-llm-trainer

Versions

Its author publishes no version number, so there is nothing here to pin to: what you install is the folder as it stands today. Instructions change more often than APIs do — a skill can be rewritten entirely without anything it depends on moving.

No earlier releases have been published to the marketplace.

Pinning

Nothing to pin to: this skill carries no version number of its own. What you install is what the folder holds on the day you install it.

Reviews

—no reviews yet · no installs yet

Nobody has reviewed this skill yet. The rating is the mean of the reviews written here, so there is none until somebody writes the first.

Who can post

Only accounts that have had the skill installed for fourteen days, so a review is written after living with it rather than after reading it. Publishers may reply once.

Who wrote it

huggingface

Publishes on mcprush.

0 servers listed5 skills listednot claimed

Profile

Publisher

Servers0