Back to course syllabus
Automate with permission, recovery, and cost controlsIf needed: model and deployment · 4 / 10

LoRA or QLoRA fine-tuning? Run a small, reviewable pilot

Admit a stable behavior problem, split training data without leakage, probe real training memory, and compare adapters with a frozen baseline on unseen cases.

DECISION TOPICLocal model deployment
LESSON OUTPUT · LoRA/QLoRA pilot recordUPDATED · Oct 2, 2026
PATH READ0 / 10
HOW TO USE THIS LESSON

Read with one real task in mind, then complete the workbench. The lesson is done when another person can review what you made.

LoRA and QLoRA can reduce the amount of model state you train, but neither turns a weak dataset into a reliable behavior. A small fine-tuning run is useful only if a clear, recurring failure remains after a simpler baseline, examples may legally and safely be used for training, and an unseen test can show improvement without a serious regression.

The Prompt, RAG, or fine-tuning decision asks whether training is the right intervention. This page begins after that gate: how should a team run a bounded adapter-training experiment and decide whether to keep it? The 4-bit inference trial compares serving packages. QLoRA uses quantization during adapter training, so its training memory and final serving behavior need their own measurements.

Know what changes in each run

In ordinary LoRA, the base model is frozen and small trainable low-rank updates are attached to selected layers. The adapter is the trained artifact; its rank, scaling, dropout, target modules, base revision, and tokenizer/template must be recorded together. A QLoRA-style run keeps the base frozen in a 4-bit representation while training adapters through it. The original QLoRA recipe also describes particular memory techniques, including NF4 and double quantization; merely selecting an arbitrary 4-bit serving file does not make it an equivalent training setup.

Do not promise a fixed memory saving or quality gain. A full-precision LoRA run may need more memory for its frozen base, while a QLoRA run still needs activations, trainable weights and optimizer state, temporary buffers, and a usable compute path. A version or kernel change may alter both memory and speed. Save the precise library, CUDA, driver, model, quantization, adapter, optimizer, and sequence settings for each run.

CandidateWhat it proves if it passesWhat it cannot prove alone
Frozen base, no adapterThe current prompt and model’s quality on the same casesWhether an adapter could help
LoRA on the baseWhether a named adapter configuration improves held-out behaviorThat it fits a smaller GPU or that all ranks work equally
QLoRA-style trainingWhether the specific quantized training route can produce an acceptable adapter on the available hardwareThat a 4-bit inference package will have the same quality or service speed

Admit the task before preparing a dataset

Pick one stable behavior: a category boundary, an output convention, or a repeated instruction-following error when the required facts are already in the request. Write a baseline prompt, a deterministic validator where possible, a blocking-error list, and a threshold for an improvement worth operating. If the missing answer depends on next week’s policy, current inventory, or a user’s permissions, supply the authoritative fact at request time; training a past fact into an adapter will not keep it current.

Audit training rights and privacy before export. Identify who may use each source conversation or document for training, what must be removed or transformed, where datasets and checkpoints can live, how long they are retained, and who can approve a release. A technically successful loss curve is irrelevant if a private customer answer was copied into a training set without permission. Fix disputed labels with reviewers before making a larger set.

Split by the thing that could leak

Create a train, validation, and sealed final test manifest before tuning. Training examples update adapter weights. Validation cases may guide rank, learning rate, number of steps, early stopping, and prompt adjustments. The final test is opened only after that choice is frozen. Reusing final-test failures to make another choice turns it into validation data; prepare a new final test before making a fresh release claim.

Random row splits are often too optimistic when rows share a customer, case, document, template, or near-duplicate paraphrase. Assign a group key before splitting so related examples stay in one partition. For a workflow whose rules change with time, also reserve a later time window to test future-like inputs. Check exact and near duplicates across partitions, plus reused source passages and generated examples derived from the same original. Scikit-learn’s group-split utility keeps specified groups apart, but the team still has to choose a meaningful group key and inspect leakage.

Keep a slice ledger: ordinary, rare, ambiguous, multilingual, missing information, sensitive data, and human handoff where relevant. A small set may have too few examples in a critical slice to support a release conclusion. Record that uncertainty instead of turning one success into a percentage. Labels need a rule and a reviewer; train and test cannot use different meanings for the same category.

Probe training memory before a long run

The inference VRAM estimate deliberately excludes training. For this pilot, measure a real short training step with the longest allowed sequence and the intended microbatch, precision, gradient accumulation, activation checkpointing, optimizer, and adapter targets. Record the actual trainable parameter count, peak allocated and peak reserved CUDA memory, device-reported usage, offload, OOM, and step time. PyTorch’s reserved-memory peak reports memory managed by its caching allocator; other allocations may exist, so compare it with device telemetry as well.

If the full-precision LoRA probe fails and a QLoRA-style probe fits, that is a feasibility result, not evidence that QLoRA gives better task answers. Reduce sequence length or microbatch only within the task’s allowed input and training plan; silently shortening examples changes the experiment. A probe that barely fits without validation or checkpoint saving leaves no margin. Test the full training path, including an evaluation and checkpoint, before reserving a long GPU run.

Example 1: a stable support-ticket boundary

A support desk receives tickets with all needed facts in the request. Its base model repeatedly confuses a device-failure category with a service-plan category. The team first clarifies the category definitions, tries a few examples, and validates the JSON schema. The remaining errors are stable on reviewed cases, so a LoRA pilot qualifies.

Tickets from the same organization often share wording. The team groups by organization or case family before splitting; it does not scatter paraphrases from one ticket between train and final test. Reviewers define which mixed-intent tickets must go to a person. After tuning against train and validation, they compare the frozen base and the chosen adapter once on sealed organizations. A gain in common tickets does not pass if urgent cases are misrouted more often. If the final slice is too small to assess that risk, the verdict is more evidence needed, not “ready.”

Example 2: bilingual summaries on a limited GPU

An equipment team writes short English and Chinese defect summaries from already approved, sanitized inspection fields. The model sometimes omits a condition that changes the repair category. The task is stable enough to test an adapter, but full-precision LoRA does not fit the available GPU at the required sequence length in the measured training probe. A QLoRA-style configuration becomes a candidate after its own probe includes forward and backward steps, validation, and checkpoint save.

The team keeps bilingual source families in separate partitions and includes rare negation cases in the sealed test. It records the frozen base model, 4-bit training configuration, LoRA target modules, prompt template, and run seed. If the adapter improves ordinary summaries but still drops the condition, it fails the predefined blocker. If it passes, the team still tests the exported adapter with the intended serving engine and production prompt; training-fit evidence does not certify deployment latency or output behavior.

Finish a decision, not just a training run

Use the workbench to retain a task gate, data lineage and split manifest, short memory probe, training configuration, and matched result table. Compare exact case outcomes and severity before an aggregate score. Include training time, inference cost, human correction, and operating ownership. A single lucky seed or a falling training loss is not acceptance; repeat a borderline result or obtain more unseen cases before release.

Decision cellRecord before declaring a winner
Baseline and targetFrozen prompt/model, cases, severity rules, required improvement and no-regression slices
DataRights, redaction, label rules, group key, train/validation/final-test counts and duplicate check
TrainingBase and adapter revisions, LoRA targets/rank/scaling, 4-bit recipe if used, sequence, microbatch, accumulation, optimizer, seed, steps
MemoryLongest-step peak allocated/reserved/device usage, offload, OOM, time, validation and checkpoint result
Final verdictPer-slice held-out failures, blocked cases, baseline comparison, deployment check, owner and retest trigger

Common questions

Does QLoRA make an arbitrary model fit one GPU? No. It may reduce the frozen base’s storage in a supported training stack, while activations and the rest of training still consume memory. Measure your full path.

Can I pick the best checkpoint using the final test? No. That makes the test part of selection. Use validation for checkpoint and hyperparameter choices, then open the final partition once for a release decision.

Is a lower training loss enough? No. It measures fit to training examples. The decision rests on unseen task cases, severe failures, and deployment behavior.

Boundary

This pilot covers small, permissioned supervised adapter experiments on a defined behavior. It is not a recipe for injecting changing facts, bypassing data rights, or claiming general model improvement. Library support, training memory, reproducibility, model licensing, and adapter loading differ by release and hardware. If the final test is consumed during iteration, the dataset or labels change, or serving uses another base revision or template, re-establish a clean comparison before making a release claim.

SOURCES CHECKED

Which first-party sources informed this guide?

Sources anchor definitions, risk boundaries, or operational facts. The decision framework and workbench are original to AI Vista.

  1. Hugging Face PEFT LoRA conceptual guideChecked 2026-10-02
  2. Hugging Face PEFT quantization guideChecked 2026-10-02
  3. Hugging Face Transformers bitsandbytes quantization guideChecked 2026-10-02
  4. Hugging Face TRL supervised fine-tuning trainerChecked 2026-10-02
  5. PyTorch CUDA maximum reserved memoryChecked 2026-10-02
  6. Scikit-learn group shuffle splitChecked 2026-10-02

AI tools may assist with research, outlining, and language editing. Facts, cases, and final wording are reviewed by the editor. Report an error through the contact page.

TAKEAWAY TOOL

LoRA/QLoRA pilot record

Keep the data split sealed, measure the complete training path, and judge unseen cases against the base model.

adapter / finetuning / pilot
USE THIS WHENAfter a stable behavior failure passes the fine-tuning admission gate and before spending a long GPU run
YOU WILL GETA sealed-split LoRA or QLoRA decision with measured training memory and unseen-case evidence

This workbench saves a draft in this browser. Use sanitized case IDs, measurements, and evidence pointers; do not paste confidential contracts, customer questions, or keys.

HOW TO USE01—03
  1. 01
    Describe the taskDescribe the result with a sanitized summary.
  2. 02
    Fill the decision fieldsRecord input categories, risk, evidence pointers, and handoff.
  3. 03
    Ask a colleague to reviewThe tool is ready when someone else can restate the decision.
DONE WHENFields are complete, boundaries are clear, and the result is reviewable.
Edits save automatically

LESSON READ

Finish the workbench, then mark it read.

The read state updates the syllabus and your course progress.

  1. 01Fields filled
  2. 02Case tested
  3. 03Reviewable

GUIDE PRACTICE NOTES

Leave a judgment you can review later.

The fictional examples below show the format. Your own notes stay in this browser. Record what worked, which boundary failed, or one question worth testing.

↗
RELATED GUIDELoRA or QLoRA fine-tuning? Run a small, reviewable pilotSee examples and local notes →
0 examples and local notesINSIGHTS · QUESTIONS · IDEAS