Ml Training

---
name: ml-training
description: "ML model training on cloud GPU capability pack. Covers platform selection, LoRA and QLoRA fine-tuning, cost estimation, and human-AI collaboration via browser MCP. Use for any ML model fine-tuning, cloud GPU training, or model adaptation task."
version: 0.1.0
type: reference-based
keywords: ["fine-tune", "微调", "LoRA", "QLoRA", "train model", "训练模型", "Colab", "Kaggle", "RunPod", "cloud GPU", "云GPU", "云训练", "training data", "训练数据", "GPU hours", "model training", "模型训练", "personality clone", "个性克隆"]
---

# ML Training Capability Pack

> Cross-agent portable judgment for ML model training on cloud GPU. Covers platform selection, LoRA/QLoRA fine-tuning for LLM and voice models, data preparation, cost estimation, and human-AI collaboration workflows.
**CONSUMES**: Training data (JSONL/ShareGPT/audio+transcript pairs), base model name, hardware constraints, budget.
**PRODUCES**: Platform recommendation, tool selection, training configuration, cost estimate.
> **INTERFACE**: ai-voice-production pack defers voice training platform selection to this pack's `platform-selection.md`. This pack defers voice-specific tool selection (GPT-SoVITS, VoxCPM2 configs, audio quality thresholds) to ai-voice-production pack. When both packs load for voice training: this pack takes precedence for platform/cost decisions; ai-voice-production takes precedence for tool selection and audio quality.

---

## Step 0: Prerequisites

- **Python 3.10+** — required by Unsloth, LlamaFactory, Axolotl
- **pip or uv** — install in virtual environment (never global)
- **Cloud account** — at least one of: Google (Colab/Kaggle), RunPod, Vast.ai
- **Chrome + Claude MCP extension** — for browser-automated Colab workflows (optional)
- **jq + awk** — required by `scripts/dataset-check.sh` / `cost-estimate.sh` / `vram-fit.sh`

Verify: `python3 --version`

---

## Step 1: Context Detection

| User Signal | Load Reference |
|---|---|
| fine-tune, 微调, LoRA, QLoRA, train model, 训练模型 | `references/lora-finetune.md` |
| Colab, Kaggle, RunPod, Vast.ai, cloud GPU, 云GPU, 云训练 | `references/platform-selection.md` |
| training data, 训练数据, chat logs, 聊天记录, data prep | `references/data-preparation.md` |
| cost, 成本, pricing, 多少钱, budget, GPU hours | `references/cost-estimation.md` |
| browser automation, MCP, Colab操作, 人机协作 | `references/mcp-collaboration.md` |
| personality clone, 个性克隆, sound like, 像某人 | `references/lora-finetune.md` + `references/data-preparation.md` |

**Multi-signal**: Load all matched references. Cross-reference links are provided within files.

---

## Step 2: Decision Entry Point

**Q1 — What type of model?**
- LLM (text: Qwen/Llama/Mistral) → load `lora-finetune.md`
- Voice (TTS/cloning: VoxCPM2/GPT-SoVITS) → defer to ai-voice-production pack for tool selection; load `platform-selection.md` for GPU choice
- Image/other → out of scope, state clearly

**Q2 — What hardware do you have locally?**
- Apple Silicon 8-16GB → cloud training mandatory for 7B+ LoRA 16-bit; local only for QLoRA 2-bit or inference
- NVIDIA GPU ≥16GB → local QLoRA possible; cloud for LoRA 16-bit or larger models
- No GPU → cloud mandatory

**Q3 — What's your budget?**
- $0 → Colab Free / Kaggle (with gotcha awareness — read `platform-selection.md`)
- $10-50/mo → Colab Pro (student free w/ .edu) / RunPod
- >$50/mo → RunPod Secure / Lambda (if uptime critical)

**Q4 — What tool?**
- Minimal setup + Colab/Kaggle → Unsloth (~70% VRAM reduction via `use_gradient_checkpointing="unsloth"`, 2-5× speedup)
- Widest models + GUI → LlamaFactory v0.9.4 (LlamaBoard no-code UI + CLI)
- RL / post-training pipeline → Axolotl v0.17.0 (single YAML, GRPO/DPO/KTO/ORPO)
- Voice → GPT-SoVITS or VoxCPM2 (defer to ai-voice-production pack)

---

## Step 3: Apply Rules

Read matched reference(s) and apply rules directly. Rules are concrete decision parameters — not step-by-step tutorials. Run the deterministic checks (Step 4) instead of eyeballing VRAM/cost/schema.

---

## Step 4: Validation Scripts (don't punt determinism to prose)

| Script | Checks |
|---|---|
| `scripts/vram-fit.sh <params_B> <method> <gpu_gb>` | Does the config fit the card? (qlora4/lora8/lora16, unsloth-qlora4) |
| `scripts/cost-estimate.sh <num_examples> [epochs] [batch] [sec/step] [rate]` | GPU-hour cost from the formula + 2026 rate anchors |
| `scripts/dataset-check.sh <file.jsonl>` | JSONL validity + schema detect (ShareGPT/ChatML/Alpaca/preference) + size verdict + dedup |

---

## Quick Rule Index (router — depth lives in references/)

> Each entry is a POINTER, not the answer. The concrete numbers (ranks, VRAM, prices,
> learning rates, quotas) are in the linked reference so this index stays a true router.

### Platform Selection → `references/platform-selection.md`
- Budget decision tree ($0 / $10-50 / $50+) → §Budget Decision Tree
- Free-tier hard limits (Colab/Kaggle quotas, session caps) → §Free Tier Hard Limits
- The 5 platform gotchas (anti-abuse, idle timeout, ephemeral storage, untrusted hosts, egress) → §Hidden Limitations
- VRAM → card mapping → §VRAM → Platform mapping

### LoRA Fine-Tuning → `references/lora-finetune.md`
- When to fine-tune (dataset-size → task threshold) → §When to Fine-Tune
- VRAM requirements + Unsloth gradient-checkpointing flag → §VRAM Requirements
- LoRA vs QLoRA quality/VRAM tradeoff + 2026 default config → §LoRA vs QLoRA
- Rank (r) + alpha rule → §Rank Selection
- Learning rate (SFT vs DPO/GRPO) → §Learning Rate
- Overfitting tripwires + training budget → §Overfitting Tripwires
- Preference tuning (DPO/GRPO config) → §Preference Tuning
- Version-pinned tool comparison → §Tool Comparison

### Data Preparation → `references/data-preparation.md`
- Quality > quantity rule → §Dataset Quality Rule
- LLM data pipeline + schemas (ShareGPT/ChatML/Alpaca) → §LLM Data Pipeline
- Preference-pair data (DPO/GRPO triples) → §Preference-Pair Data
- Voice data pipeline (defer audio thresholds) → §Voice Data Pipeline
- AI bootstrap to reach the example floor → §AI Bootstrap

### MCP Collaboration → `references/mcp-collaboration.md`
- PAUSE protocol (auth triggers, forbidden tools, resume) → §PAUSE Protocol
- Chrome MCP tool map → §Chrome MCP Tool Map
- Security rules → §Security Rules

### Cost Estimation → `references/cost-estimation.md`
- Cost formula → §Cost Formula
- 2026 price anchors → §Cloud GPU Price Anchors
- "Can I do it free?" tree → §"Can I Do It Free?" Decision Tree

---

## Anti-Skip Table

| Shortcut Attempt | Required Action |
|---|---|
| "I'll just use Colab Free" | MUST read `platform-selection.md` gotchas — anti-abuse termination kills SSH/remote desktop, Drive I/O errors after 10K files, idle quota burn |
| "200 examples should be enough for everything" | MUST check task-type threshold in `lora-finetune.md` — practical floor 100, sweet spot 500-10000; personality needs AI bootstrap to reach ~500. Run `scripts/dataset-check.sh` for the size verdict |
| "I'll fine-tune first, test later" | MUST check fine-tune threshold in `lora-finetune.md` — if <100 examples, use few-shot prompting/RAG first (below practical floor) |
| "My Mac can handle it" | MUST check VRAM in `lora-finetune.md` — 7-8B LoRA 16-bit needs ~16GB, 8GB Mac = cloud mandatory above QLoRA 4-bit. Run `scripts/vram-fit.sh` to confirm |
| "I'll reuse the SFT learning rate for DPO" | MUST check `lora-finetune.md` §Learning Rate — DPO/GRPO LR is 5e-6, ~40× lower than SFT 2e-4; reusing 2e-4 diverges |
| "I'll skip data cleaning" | MUST read `data-preparation.md` quality rule — 500 clean examples outperform 5,000 noisy; 117 clean > 248 dirty segments at same step count (Colin dogfood) |