training-patterns

What this skill does

# ML Training Patterns

**Purpose:** Provide production-ready training templates, configuration files, and automation scripts for common ML training scenarios including classification, generation, fine-tuning, and PEFT/LoRA approaches.

**Activation Triggers:**
- Building text classification models (sentiment, intent, NER, etc.)
- Training text generation models (summarization, Q&A, chatbots)
- Fine-tuning pre-trained models for specific tasks
- Implementing PEFT (Parameter-Efficient Fine-Tuning) with LoRA
- Setting up training pipelines with HuggingFace Transformers
- Configuring training hyperparameters and optimization
- Preparing datasets for model training

**Key Resources:**
- `scripts/setup-classification.sh` - Classification training setup automation
- `scripts/setup-generation.sh` - Generation training setup automation
- `scripts/setup-fine-tuning.sh` - Full fine-tuning setup automation
- `scripts/setup-peft.sh` - PEFT/LoRA training setup automation
- `templates/classification-config.yaml` - Classification training configuration
- `templates/generation-config.yaml` - Generation training configuration
- `templates/peft-config.json` - PEFT/LoRA configuration
- `examples/sentiment-classifier.md` - Complete sentiment classification example
- `examples/text-generator.md` - Complete text generation example

## Training Scenarios Overview

### 1. Text Classification

**Use cases:** Sentiment analysis, intent classification, topic categorization, spam detection, named entity recognition (NER)

**Key characteristics:**
- Input: Text → Output: Class label(s)
- Typically uses encoder models (BERT, RoBERTa, DistilBERT)
- Fast inference, suitable for production
- Requires labeled training data

**Setup command:**
```bash
./scripts/setup-classification.sh <project-name> <model-name> <num-classes>
```

**Example:**
```bash
./scripts/setup-classification.sh sentiment-model distilbert-base-uncased 3
```

### 2. Text Generation

**Use cases:** Summarization, question answering, chatbots, text completion, translation, code generation

**Key characteristics:**
- Input: Text (prompt) → Output: Generated text
- Uses decoder or encoder-decoder models (GPT-2, T5, BART)
- More computationally intensive
- Can be trained with or without labeled data

**Setup command:**
```bash
./scripts/setup-generation.sh <project-name> <model-name> <generation-type>
```

**Example:**
```bash
./scripts/setup-generation.sh qa-bot t5-small question-answering
```

### 3. Full Fine-Tuning

**Use cases:** When you have sufficient data and compute to retrain all model parameters

**Key characteristics:**
- Updates all model weights
- Requires significant compute (GPU with 16GB+ VRAM)
- Best for substantial domain adaptation
- Training time: hours to days

**Setup command:**
```bash
./scripts/setup-fine-tuning.sh <project-name> <model-name> <task-type>
```

**Example:**
```bash
./scripts/setup-fine-tuning.sh medical-classifier bert-base-uncased classification
```

### 4. PEFT (Parameter-Efficient Fine-Tuning)

**Use cases:** Limited compute resources, quick experimentation, domain adaptation with small datasets

**Key characteristics:**
- Only trains a small subset of parameters (LoRA adapters)
- 10-100x less memory than full fine-tuning
- Fast training (minutes to hours)
- Can fine-tune large models (7B+) on consumer GPUs
- Uses techniques like LoRA, QLoRA, Prefix Tuning, Adapter Layers

**Setup command:**
```bash
./scripts/setup-peft.sh <project-name> <model-name> <peft-method>
```

**Example:**
```bash
./scripts/setup-peft.sh efficient-classifier roberta-base lora
```

## Classification Training Pattern

### Configuration Template

**File:** `templates/classification-config.yaml`

**Key parameters:**
```yaml
model:
  name: distilbert-base-uncased
  num_labels: 3
  task_type: classification

dataset:
  train_file: data/train.csv
  validation_file: data/val.csv
  test_file: data/test.csv
  text_column: text
  label_column: label

training:
  output_dir: ./outputs
  num_epochs: 3
  batch_size: 16
  learning_rate: 2e-5
  warmup_steps: 500
  weight_decay: 0.01
  evaluation_strategy: epoch
  save_strategy: epoch
  logging_steps: 100
  fp16: true  # Mixed precision training
  gradient_accumulation_steps: 1

optimizer:
  name: adamw
  betas: [0.9, 0.999]
  epsilon: 1e-8
```

### Training Pipeline

**1. Dataset Preparation:**
```python
from datasets import load_dataset

# Load from CSV
dataset = load_dataset('csv', data_files={
    'train': 'data/train.csv',
    'validation': 'data/val.csv',
    'test': 'data/test.csv'
})

# Preprocess
def preprocess(examples):
    return tokenizer(
        examples['text'],
        truncation=True,
        padding='max_length',
        max_length=512
    )

dataset = dataset.map(preprocess, batched=True)
```

**2. Model Initialization:**
```python
from transformers import AutoModelForSequenceClassification

model = AutoModelForSequenceClassification.from_pretrained(
    model_name,
    num_labels=num_classes,
    id2label={0: 'negative', 1: 'neutral', 2: 'positive'},
    label2id={'negative': 0, 'neutral': 1, 'positive': 2}
)
```

**3. Training:**
```python
from transformers import TrainingArguments, Trainer

training_args = TrainingArguments(
    output_dir='./outputs',
    num_train_epochs=3,
    per_device_train_batch_size=16,
    per_device_eval_batch_size=32,
    learning_rate=2e-5,
    warmup_steps=500,
    weight_decay=0.01,
    evaluation_strategy='epoch',
    save_strategy='epoch',
    load_best_model_at_end=True,
    metric_for_best_model='accuracy',
    fp16=True,  # Enable mixed precision
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=dataset['train'],
    eval_dataset=dataset['validation'],
    compute_metrics=compute_metrics,
)

trainer.train()
```

**4. Evaluation:**
```python
from sklearn.metrics import accuracy_score, precision_recall_fscore_support

def compute_metrics(eval_pred):
    predictions, labels = eval_pred
    predictions = predictions.argmax(axis=-1)

    accuracy = accuracy_score(labels, predictions)
    precision, recall, f1, _ = precision_recall_fscore_support(
        labels, predictions, average='weighted'
    )

    return {
        'accuracy': accuracy,
        'precision': precision,
        'recall': recall,
        'f1': f1
    }

# Evaluate on test set
results = trainer.evaluate(dataset['test'])
print(results)
```

## Generation Training Pattern

### Configuration Template

**File:** `templates/generation-config.yaml`

**Key parameters:**
```yaml
model:
  name: t5-small
  task_type: generation
  generation_type: question-answering  # or summarization, translation, etc.

dataset:
  train_file: data/train.json
  validation_file: data/val.json
  input_column: question
  target_column: answer
  max_input_length: 512
  max_target_length: 128

training:
  output_dir: ./outputs
  num_epochs: 5
  batch_size: 8
  learning_rate: 3e-4
  warmup_steps: 1000
  weight_decay: 0.01
  evaluation_strategy: steps
  eval_steps: 500
  save_steps: 500
  logging_steps: 100
  fp16: true
  gradient_accumulation_steps: 2
  predict_with_generate: true

generation:
  max_length: 128
  min_length: 10
  num_beams: 4
  length_penalty: 2.0
  early_stopping: true
  no_repeat_ngram_size: 3
```

### Training Pipeline

**1. Dataset Preparation:**
```python
from datasets import load_dataset

# Load from JSON (question-answer pairs)
dataset = load_dataset('json', data_files={
    'train': 'data/train.json',
    'validation': 'data/val.json'
})

# Preprocess for seq2seq
def preprocess(examples):
    inputs = tokenizer(
        examples['question'],
        max_length=512,
        truncation=True,
        padding='max_length'
    )

    # Tokenize targets
    with tokenizer.as_target_tokenizer():
        targets = tokenizer(
            examples['answer'],
            max_length=128,
            truncation=True,
            padding='max_length'
        )

    inputs['labels'] = targets['input_ids']
    return inputs

dataset =