unsloth/studio/backend/utils/hardware/VRAM_ESTIMATION.md

VRAM Estimation for Training

Total VRAM = Weights + LoRA Adapters + Optimizer + Gradients + Activations + CUDA Overhead

Symbol	Meaning
H	hidden_size
L	num_hidden_layers
V	vocab_size
K	(H / num_attention_heads) * num_key_value_heads
M	intermediate_size (or moe_intermediate_size)
E	num_experts (1 for dense)
r	LoRA rank
B	per_device_train_batch_size
S	max_seq_length

---

1. Model Weights

QKVO = (H + K + K + H) * H
MLP  = H * M * 3 * E  +  (E * H if E > 1 else 0)

Quantizable     = (QKVO + MLP) * L
Non-quantizable = 2*H*L + V*H + (V*H if not tie_embeddings else 0)

Mode	Bytes
QLoRA 4-bit	Quantizable * 2 / 3.2 + Non-quantizable * 2
LoRA / Full fp16	(Quantizable + Non-quantizable) * 2

The 3.2 factor (16/5) accounts for BNB NF4 blockwise scales. Repos whose quantization config enables bnb_4bit_use_double_quant use a tighter, still conservative 3.6 factor for the quantized portion of the weights. When a 4-bit config has llm_int8_skip_modules entries that point to language model layers or submodules, those quantizable weights are charged at fp16 instead of NF4. Generic embedding and multimodal skip names are already covered by non-quantizable terms or excluded from text training weights.

2. LoRA Adapters

Module	A	B
q_proj	H×r	r×H
k_proj	H×r	r×K
v_proj	H×r	r×K
o_proj	H×r	r×H
gate_proj	H×r	r×M
up_proj	H×r	r×M
down_proj	M×r	r×H

MLP modules multiply by E for MoE.

LoRA_bytes = sum(A + B per selected module) * L * 2

all-linear is treated as all known text linear modules in the table above. The estimator deliberately does not infer multimodal or vision-tower LoRA modules from config shapes; those modules vary too much across VLM families for a generic config formula.

Some decoder configs expose layer-shape fields such as layer_types, head_dim, global_head_dim, num_global_key_value_heads, attention_k_eq_v, num_kv_shared_layers, use_double_wide_mlp, vocab_size_per_layer_input, and hidden_size_per_layer_input. When those fields are present, the estimator derives text weight and LoRA counts from the per-layer shapes instead of assuming every layer has the same seven projection modules.

3. Optimizer States (calibrated)

Optimizer	Bytes/param	Notes
adamw_8bit	4	BNB upcasts to fp32 during step
adamw_torch	6	Fused, no master copy
paged_adamw_32bit	8	Full fp32 states
sgd	4

Trainable params = all params (Full FT) or LoRA params only.

4. Gradients

Gradient_bytes = trainable_params * 2    (fp16, accumulated in-place)

5. Activations

Per-layer (from unsloth_zoo/vllm_utils.py):

Per_layer = (S*B*(H+K+K) + S*B*2 + S*B*(M+M)) * 2 * 1.25

When the resolved attention implementation is none of flash_attention_2, sdpa, or flex_attention (PyTorch SDPA dispatches to flash or memory-efficient kernels and FlexAttention is also a memory-efficient kernel, all of which are O(n) in memory), activation memory also includes a quadratic attention-score/workspace estimate:

Non_flash_attention = B * num_attention_heads * S^2 * 2 * 12.0 * effective_layers
Activations = max(Per_layer_with_gc, Non_flash_attention)

Unsloth resolves the attention implementation with Unsloth's resolve_attention_implementation helper and uses that result directly. The estimator does not duplicate model-family attention policy.

GC Mode	Full FT	LoRA/QLoRA
none	L layers	L layers
true (HF)	2.0	1.0
unsloth	1.5	1.0

6. Floors

Activations use the computed formula directly:

activation_bytes = computed_activation_bytes

Full fine-tuning keeps the gradient floor at 15% of model weight memory to account for autograd overhead, NCCL buffers, mixed-precision scaling, and PyTorch fragmentation:

gradient_bytes = max(computed_gradient_bytes, weights * 0.15)

For LoRA/QLoRA, the base model is frozen, so the weight-derived gradient floor is capped by trainable-state and live-activation scale:

raw_gradient_bytes = trainable_params * 2
gradient_floor = min(weights * 0.15, max(computed_activation_bytes, optimizer_bytes))
gradient_bytes = max(raw_gradient_bytes, gradient_floor)

This prevents frozen quantized model size from dominating gradient/state overhead when the measured runtime footprint is governed by LoRA optimizer states and live activations.

7. CUDA Overhead

1.4 GB fixed — CUDA driver + PyTorch runtime, calibrated on RTX 5070 Ti.

8. Multi-GPU Overhead

When sharding across multiple GPUs, each additional GPU (beyond the first) contributes only 85% of its free VRAM to the usable pool. The 15% discount accounts for NCCL all-reduce buffers, PCIe/NVLink transfer overhead, synchronization barriers, and memory fragmentation from non-uniform shard sizes. Calibrated empirically on 2-8 GPU setups with NVLink and PCIe topologies.

usable_gb = free[gpu_0] + sum(free[gpu_i] * 0.85 for i in 1..N)

---

Parameter Flow

Frontend -> routes/{training,inference}.py
         -> prepare_gpu_selection(gpu_ids, model_name, ...)
            |
            +-- gpu_ids is explicit (e.g. [5,6,7])
            |     -> resolve_requested_gpu_ids: validate against parent-visible set
            |     -> return all requested GPUs (model sharded across all of them)
            |
            +-- gpu_ids is None or []
                  -> auto_select_gpu_ids: estimate VRAM, pick minimum GPUs needed
                  -> estimate_required_model_memory_gb -> estimate_training_vram
                  -> greedy selection: rank GPUs by free VRAM, add until model fits

         -> get_device_map(resolved_gpu_ids)
            -> "balanced" if >1 GPU, "sequential" otherwise

         -> worker subprocess: apply_gpu_ids(resolved_gpu_ids)
            -> sets CUDA_VISIBLE_DEVICES before torch/CUDA init

Threaded params: batch_size, max_seq_length, lora_r, target_modules, gradient_checkpointing, optim.

Source: studio/backend/utils/hardware/vram_estimation.py