QLoRA Fine-Tuning With Memory Receipts

QLoRA fine-tuning makes a single-GPU run possible by changing what occupies memory, not by suspending the laws of GPU allocation. This guide builds a measured ledger for weights, adapters, optimizer state, activations, temporary buffers, and quality before choosing rank or sequence length.

The proposed ledger replaces the sentence ‘it fits’ with a reproducible claim. The method produces a peak-memory trace, one-variable sweep, held-out quality matrix, adapter receipt, and an explicit answer to whether the smaller footprint still solves the task.

The vocabulary connects NF4 quantization, LoRA adapters, paged optimizers, and parameter-efficient fine-tuning once each because they occupy different rows in the memory and quality argument. That vocabulary supports the article's QLoRA fine-tuning decision without creating a second intent.

1. Base weights
2. Adapters
3. Activations
4. Peak buffers

QLoRA fine-tuning needs a memory ledger

A successful allocation says little about the next long batch, optimizer step, evaluation pass, or checkpoint write. The QLoRA paper introduces a quantized-base adaptation recipe and analyzes the memory-saving components behind it. The phrase ‘fits on one GPU’ is incomplete until the measured window includes backward, optimizer, evaluation, and checkpoint phases. A proposed review of “QLoRA fine-tuning needs a memory ledger” has four inspectable moves.

• Reset peak statistics before the measured window
• Record allocated and reserved bytes
• Mark forward, backward, optimizer, and save phases
• Capture batch and sequence shapes with each peak

The proposed evidence for qlora fine-tuning needs a memory ledger is phase-labeled peaks from a warm and a worst-shape step. The qlora fine-tuning needs a memory ledger receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this QLoRA fine-tuning decision is quoting idle memory or model-load memory as training cost. If quoting idle memory or model-load memory as training cost occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is the configuration fits only if the worst supported step leaves a declared reserve. Promotion under “the configuration fits only if the worst supported step leaves a declared reserve” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

Account for the quantized base honestly

Low-bit storage reduces the frozen model footprint while computation still uses higher-precision values and metadata. The bitsandbytes documentation documents low-bit loading and optimizer configuration used in practical quantized training stacks. Quantized storage, compute values, scales, and temporary dequantization work occupy different ledger rows and should not be collapsed. A proposed review of “Account for the quantized base honestly” has four inspectable moves.

• Record quantization type and compute dtype
• Count scales and quantization metadata
• Verify which modules remain unquantized
• Measure dequantization workspace at runtime

The proposed evidence for account for the quantized base honestly is reconciling the theoretical parameter total with observed allocations. The account for the quantized base honestly receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this QLoRA fine-tuning decision is dividing parameter count by two and treating the result as complete. If dividing parameter count by two and treating the result as complete occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is measured persistent bytes must be explainable within a small ledger tolerance. Promotion under “measured persistent bytes must be explainable within a small ledger tolerance” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

Choose rank from a quality-memory frontier

Adapter rank is a capacity decision whose useful range depends on the task and targeted modules. The PEFT LoRA guide explains adapter rank, target modules, and the relationship between frozen base weights and trainable updates. Rank becomes a defensible choice when added capacity is plotted against held-out task gain rather than spare device memory. A proposed review of “Choose rank from a quality-memory frontier” has four inspectable moves.

• Start with a low, middle, and high rank
• Hold data order and steps constant
• Score every supported cohort
• Plot quality gain per added gigabyte

The proposed evidence for choose rank from a quality-memory frontier is the smallest rank before held-out improvement flattens. The choose rank from a quality-memory frontier receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this QLoRA fine-tuning decision is selecting a large rank because spare memory exists. If selecting a large rank because spare memory exists occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is increase capacity only while a named cohort gains beyond measurement noise. Promotion under “increase capacity only while a named cohort gains beyond measurement noise” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

Signal	Decision	Evidence
Rank 8 · 1k	Baseline	10.8 GB · 78.1
Rank 16 · 2k	Ship	15.6 GB · 84.7
Rank 64 · 2k	Reject	19.9 GB · 85.0

Make the reserve check runnable

A one-line budget gate should fail before a notebook launches a run that will die during the first difficult sequence. A preflight reserve check prevents the first long sequence from discovering an arithmetic error through an out-of-memory crash. A proposed review of “Make the reserve check runnable” has four inspectable moves.

• Express all values in bytes
• Include a safety reserve
• Test both typical and worst shapes
• Report the overage rather than a boolean alone

The proposed evidence for make the reserve check runnable is executing the fixture in the same environment as materialization. The make the reserve check runnable receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this QLoRA fine-tuning decision is using total device capacity without driver and workspace headroom. If using total device capacity without driver and workspace headroom occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is planned persistent and peak bytes plus reserve must remain below capacity. Promotion under “planned persistent and peak bytes plus reserve must remain below capacity” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

Runnable artifact. Save this bounded specimen as qlora-fine-tuning-memory.test.mjs and run node --test qlora-fine-tuning-memory.test.mjs. Expected result: PASS: reserve protects peak memory.

import assert from "node:assert/strict";
import test from "node:test";
const fits = ({ persistent, peak, reserve, capacity }) => persistent + peak + reserve <= capacity;
test("keeps a device reserve", () => {
  assert.equal(fits({ persistent: 11, peak: 5, reserve: 2, capacity: 20 }), true);
  assert.equal(fits({ persistent: 13, peak: 6, reserve: 2, capacity: 20 }), false);
  console.log("PASS: reserve protects peak memory");
});

Treat activations as a shape problem

Sequence length, microbatch size, padding, and checkpoint policy often dominate the configurable portion of the peak. Activation cost follows actual token shapes and padding, which can dominate the few bytes being debated in adapter configuration. A proposed review of “Treat activations as a shape problem” has four inspectable moves.

• Bucket examples by real length
• Measure padded and packed batches
• Sweep microbatch independently
• Log checkpoint boundaries

The proposed evidence for treat activations as a shape problem is bytes per token at several representative shapes. The treat activations as a shape problem receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this QLoRA fine-tuning decision is tuning rank while a pathological padding ratio causes the failure. If tuning rank while a pathological padding ratio causes the failure occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is choose batching and sequence limits before spending the remaining budget on adapters. Promotion under “choose batching and sequence limits before spending the remaining budget on adapters” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

Observe paging rather than assuming it

Moving optimizer pressure away from a peak helps only if transfers and stalls remain inside the training-time budget. Paging earns its complexity only when the freed peak enables useful quality without creating an unacceptable step-time tail. A proposed review of “Observe paging rather than assuming it” has four inspectable moves.

• Track step-time percentiles
• Count allocation retries and synchronization stalls
• Compare with a nonpaged small baseline
• Inspect host-memory pressure

The proposed evidence for observe paging rather than assuming it is peak memory saved beside p95 step-time cost. The observe paging rather than assuming it receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this QLoRA fine-tuning decision is calling a run efficient because it avoids an out-of-memory exception. If calling a run efficient because it avoids an out-of-memory exception occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is paging is acceptable only when the saved capacity buys useful task quality. Promotion under “paging is acceptable only when the saved capacity buys useful task quality” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

1. MeasureMeasure

   Reset and capture allocated, reserved, and peak memory.

2. SweepSweep

   Vary rank or sequence length one factor at a time.

3. EvaluateEvaluate

   Score held-out cohorts against the frozen base.

4. PackagePackage

   Save adapter, tokenizer, template, and ledger together.

Evaluate the adapter against its base

A compact update can still forget, overfit templates, or shift calibration on cohorts absent from the tuning set. A compact adapter still changes behavior, so base-versus-adapted disagreements deserve the same cohort scrutiny as a full run. A proposed review of “Evaluate the adapter against its base” has four inspectable moves.

• Freeze base and adapted generations
• Use identical decoding settings
• Score task, safety, language, and format cohorts
• Review the largest disagreements

The proposed evidence for evaluate the adapter against its base is paired behavior deltas with confidence intervals and examples. The evaluate the adapter against its base receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this QLoRA fine-tuning decision is reporting training loss as proof of task improvement. If reporting training loss as proof of task improvement occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is promotion requires target gains without breaching protected regression limits. Promotion under “promotion requires target gains without breaching protected regression limits” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

Package the complete adapter receipt

An adapter file without its base revision and prompt contract is not a reproducible artifact. The adapter package is incomplete without the exact base revision, tokenizer, prompt template, module targets, and clean-load check. A proposed review of “Package the complete adapter receipt” has four inspectable moves.

• Pin base model and library revisions
• Save tokenizer and chat template
• Record target modules and scaling
• Attach memory and quality ledgers

The proposed evidence for package the complete adapter receipt is loading the package in a clean process and matching fixture output. The package the complete adapter receipt receipt should bind the relevant input and configuration to the observed output, then retain a deliberately rejected control so the check can prove it distinguishes a bad result.

The falsification target for this QLoRA fine-tuning decision is assuming any similarly named base checkpoint is compatible. If assuming any similarly named base checkpoint is compatible occurs, a favorable aggregate can still conceal the exact cohort, queue state, position, geometry, or frame that invalidates the conclusion.

The article's proposed boundary is the clean-load hash and held-out sample outputs must match the approved receipt. Promotion under “the clean-load hash and held-out sample outputs must match the approved receipt” should wait until another reviewer can evaluate the boundary from named evidence without relying on the author's authority.

Keep the boundary visible

Build the ledger before filling the GPU. Quantized base storage, adapter parameters, activation shapes, optimizer behavior, temporary workspaces, and safety reserve must reconcile with an observed phase-labeled peak.

Then choose the smallest configuration that clears held-out task and cohort gates. Memory saved is useful only when it buys a reproducible run whose behavior is worth serving.

Continue through four related field notes: LLM quantization quality budgets, multi-LoRA serving, model distillation, distributed checkpointing. Each extends the QLoRA fine-tuning method without changing this article's single search intent.