Skill 2.3.5: Debug model convergence issues
Task 2.3: ML Model and Foundation Model (FM) Development — Analyze and evaluate the performance of ML and AI systems
Objective: separate a broken run (bug/config) from a limited run (capacity/data) from normal behavior — then fix the right one. Convergence debugging = reading the loss curve + reproducibility evidence.
Loss Curve Triage — Symptom → Root Cause → First Fix
| Loss curve symptom | Most likely cause | First action |
|---|---|---|
| Oscillates, never settles | Learning rate too high | Cut LR 3–10×; add warmup + decay |
| Diverges / NaN / Inf | LR too high, exploding gradients, FP16 overflow, NaN in data | Gradient clipping, lower LR, loss scaling, sanitize inputs |
| Barely moves, high plateau | LR too low, poor init, insufficient capacity, feature/label bug | Raise LR, re-init, add capacity, run tiny-batch overfit test |
| Train ↓, validation ↑ | Overfitting | Dropout / L2 / weight decay, early stopping, more or augmented data |
| Train and validation both high and flat | Underfitting | More capacity/features, longer training, higher LR |
| Noisy/jittery, slow trend | Batch size too small | Increase batch (and scale LR) |
| Repeating cyclical pattern | Data not shuffled | Shuffle before batching |
| Smooth, then a spike that recovers | LR schedule step / outlier batch | Decay LR, inspect the batch |
| Both curves flat at chance level | Label bug, train/serve skew, leakage | Audit labels and the feature pipeline |
Learning rate is the #1 cause of oscillation and divergence — examine it before anything else. Output-class count, training instance count, and data storage format are distractors; none of them drive gradient step size.
Hyperparameter Direction Matrix
| Hyperparameter | Too high → | Too low → |
|---|---|---|
| Learning rate | Oscillation, divergence, NaN | Slow convergence, high plateau, stuck |
| Batch size | Fewer updates/epoch, generalization gap | Noisy gradients, unstable loss |
| Regularization (dropout / L2 / weight decay) | Underfitting | Overfitting |
| Epochs | Overfitting | Underfitting |
| Momentum / Adam β | Overshoot | Slow escape from plateaus |
| Warmup steps (transformers) | Wasted epochs, slow start | Early instability, divergence |
Linear scaling rule: when batch size ×k, scale LR ×k (or use LARS/LAMB). Data-parallel training silently changes the effective batch size — unadjusted LR is the classic distributed-training convergence bug.
Fastest Diagnostic: Overfit a Tiny Batch
- Train on 1–10 samples until loss → ~0. If the model cannot overfit them, the bug is in code, labels, loss function, or LR — not data volume or architecture.
- If it can overfit, the problem is capacity, regularization, data quantity, or data quality.
- Always fix and log the random seed; non-reproducible runs make every later comparison meaningless.
Data-Side Convergence Killers
- NaNs / Inf / out-of-range values → immediate NaN loss.
- Unscaled or unnormalized features → vanishing/exploding gradients.
- Unshuffled data → cyclical loss, biased mini-batches.
- Mislabeled / flipped labels → loss floors above chance.
- Class imbalance → collapse to majority class (high accuracy, useless loss).
- Train/serve skew → offline converges, online degrades.
- Distribution shift → validation loss rises with no code change.
Architecture / Optimization Fixes
| Problem | Fix |
|---|---|
| Vanishing gradients (deep nets, RNNs) | ReLU/GELU, BatchNorm/LayerNorm, residual connections, LSTM/GRU gates |
| Exploding gradients | Gradient clipping, lower LR, better init (Xavier/He) |
| Dead ReLU / stalled units | Leaky ReLU, lower LR, re-init |
| Saturated activations (sigmoid/tanh) | Normalize inputs, change activation |
| FP16 mixed-precision NaN | Dynamic loss scaling, keep master weights in FP32 |
| "Slow" mistaken for non-convergence | Check GPU utilization / I/O — this is a throughput problem, not convergence |
Distributed Training Convergence Traps
- Effective batch size = per-device batch × device count — LR must be rescaled.
- Gradient staleness from asynchronous updates → unstable convergence.
- Stragglers delay all-reduce; use SageMaker distributed data parallel.
- Model parallelism creates different numerical paths — validate against a single-instance baseline first.
- Cross-instance reproducibility requires fixed seeds, deterministic ops, and identical package versions.
Observability & Tooling — What to Reach For
| Need | Service |
|---|---|
| Per-run params, metrics, artifacts, seed, code version | SageMaker AI with MLflow (or SageMaker Experiments) |
| Automatic convergence rules (loss not decreasing, overfit, vanishing gradient, stalled training, class imbalance, dead ReLU) | SageMaker Debugger built-in rules |
| Hardware bottlenecks (GPU/CPU utilization, I/O wait) | SageMaker Debugger Profiler |
| Loss/validation metrics over time, alarms on departure from baseline | Amazon CloudWatch |
| Trace a GenAI app step-by-step to find where output diverged | MLflow tracing |
Debugger rules detect the symptom; MLflow gives you the comparison. Neither fixes it — you still decide whether it is LR, data, or capacity.
FM / LLM Fine-Tuning Convergence Notes
- LLM loss curves are inherently noisy — judge the trend across steps, not per-step spikes.
- Typical LR: full fine-tune ~1e-5–1e-4; LoRA/PEFT higher (1e-4–1e-3). Too high → divergence; too low → no learning signal.
- Warmup + cosine decay is near-mandatory for transformer stability.
- Catastrophic forgetting: training loss drops while general capability degrades → lower LR, LoRA, or mix in general data.
- Loss computed over prompt tokens (masking bug) → loss looks low but the model never learns the response. Verify labels are masked to completion tokens only.
- Tokenization / padding bugs produce inexplicable plateaus — inspect tokenized samples directly.
- Bedrock model fine-tuning surfaces training and validation loss/accuracy curves; use early stopping instead of guessing an epoch count.
Anti-Patterns (Exam Traps)
- "Restart the job and hope" — no reproducibility, no evidence.
- Tuning architecture before the learning rate.
- Reporting only the best run and discarding variance.
- Judging convergence from training loss alone — training loss almost always improves; validation loss is the signal.
- Fixing overfitting with a bigger model — that is the underfitting remedy.
- Comparing runs across different seeds, package versions, or data snapshots and calling it a convergence difference.
Triage order: (1) reproduce with a fixed seed → (2) overfit a tiny batch → (3) audit the data → (4) adjust learning rate/schedule → (5) adjust capacity/regularization → (6) only then change architecture.