The DeepSeek Fine Tuning Guide for LoRA, QLoRA and Full SFT

You have a domain — legal clauses, support tickets, internal Python conventions — and the stock model gets it 70 % right. The remaining 30 % is where production breaks. This DeepSeek fine tuning guide walks through the realistic options as of October 2026: LoRA and QLoRA on the R1 distills and Coder, full supervised fine-tuning on DeepSeek’s current open weights for teams with serious GPU budget, and the dataset and evaluation work that decides whether any of it pays off. By the end you will know which DeepSeek checkpoint to start from, how to prepare data, what hardware to rent, and the specific commands to ship a working adapter.

What you will build

By the end of this tutorial you will have a parameter-efficient adapter (LoRA or QLoRA) trained on a small DeepSeek checkpoint, evaluated against a held-out split, and ready to serve behind an OpenAI-compatible API. The same recipe scales up to multi-GPU full fine-tuning on the larger weights, with the budget and risk increasing accordingly.

One framing point before we start: DeepSeek’s flagship API models are not the right starting point for fine-tuning. The open weights behind them — DeepSeek-V4.1-Flash-1017 and DeepSeek-V4-Pro-0813, both MIT-licensed on Hugging Face — are server-scale Mixture-of-Experts models: DeepSeek’s 10 September 2026 announcement described the September V4.1-Flash build as a 552B-parameter MoE, and the V4-Pro-0813 model card says it is built on the V4-Pro (Preview) model structure. The full R1 model is likewise far too large for a single GPU, which is why DeepSeek published smaller distilled checkpoints based on Qwen2.5 and Llama 3. Most teams should fine-tune a distill or Coder variant and use the API (deepseek-flash or deepseek-v4-pro) for everything else.

Prerequisites

• Python 3.10+ and a CUDA-capable GPU. For QLoRA on a 7–8B distill with the plain transformers + peft recipe below, our rough rule of thumb is to plan for a 16–24 GB card (for example an RTX 4090 or A10G). Memory-optimised libraries need less: Unsloth’s requirements page lists 5 GB (7B) and 6 GB (8B) as its absolute minimum for QLoRA (checked 23 October 2026).
• A Hugging Face account with a write-access token (for downloading weights and pushing your adapter).
• 500–5,000 cleaned training examples in JSONL chat format, plus a held-out evaluation split.
• The libraries: transformers, peft, trl, bitsandbytes, datasets, accelerate. Optionally unsloth for memory and speed wins.
• If you plan to call the DeepSeek API for synthetic data generation or evaluation comparisons, see the DeepSeek API getting started walkthrough first.

Step 1 — Pick the right base checkpoint

This single decision sets the cost ceiling for the project. A wrong choice here cannot be salvaged by hyperparameter tuning later.

The GPU column is our rough planning guide for the recipe in this tutorial, not a measured minimum; actual memory use depends on sequence length, batch size and library. Picking a distilled base such as DeepSeek-R1-Distill-Qwen-7B that fits your GPU budget, then preparing 500–5,000 labelled examples in JSONL ChatML format with train and validation splits, is the textbook starting position. Of the current flagship weights, DeepSeek-V4.1-Flash-1017 is the more realistic self-hosting target; DeepSeek-V4-Pro-0813 needs significant cluster capacity even to serve, so most teams will use the DeepSeek API for it. If your task is code-shaped, start with a DeepSeek Coder base; if it is reasoning-shaped, a DeepSeek R1 Distill base.

Step 2 — Prepare the dataset

Dataset quality is the single largest predictor of fine-tune success. Parameter-efficient techniques like LoRA and QLoRA let teams without massive GPU budgets adapt these models to specialised tasks with a few hundred to a few thousand examples — but any gain disappears fast if the data is noisy.

Format

Use JSONL, one example per line, in ChatML-style messages. A minimal example for a support-classification task:

{"messages": [
  {"role": "system", "content": "Classify the ticket. Output one of: billing, bug, feature, other."},
  {"role": "user", "content": "Charged twice this month, need refund."},
  {"role": "assistant", "content": "billing"}
]}

One R1-specific note: DeepSeek’s R1 model card recommends avoiding a system prompt for the R1 series and putting all instructions in the user prompt, so for the distills consider folding the system line above into the user turn.

Splits and hygiene

1. Split 80 / 10 / 10 into train, validation, and held-out test. Never let the test split leak into training.
2. Deduplicate — exact matches and near-duplicates inflate validation accuracy without improving the model.
3. Balance classes when possible. If 90 % of tickets are other, the model will learn to say other.
4. Run a sanity prompt of every example through the base model first; if the base already gets it right, you don’t need it in training.

Step 3 — Configure LoRA / QLoRA

LoRA freezes the base model weights and injects small trainable low-rank matrices into specific layers, typically the attention projections, so only a tiny fraction of the parameters is trained. QLoRA goes further by loading the frozen base model in 4-bit quantised form, which is what lets a 7B model fit on a single consumer-class GPU.

Sensible starting defaults, in line with common published recipes:

• Rank (r): 16 for classification, 32 for instruction following, 64 only if you have signal that 32 is underfitting.
• Alpha: 2× rank is a safe starting point.
• Target modules: q_proj, k_proj, v_proj, o_proj. Add gate/up/down projections only when attention-only adapters underfit.
• Learning rate: 2e-4 for QLoRA, 1e-4 for LoRA on bf16.
• Epochs: 3 for >2,000 examples, up to 5 for smaller sets. Watch validation loss and stop early.
• Batch size: as a rough guide, 1–2 on a 16 GB card, 4–8 on 24 GB or more. Use gradient accumulation to reach an effective batch of 16–32.

Step 4 — Train

Below is a minimal Python QLoRA run using transformers, peft, and trl. It trains the 8B Llama-distilled DeepSeek on a JSONL file:

import torch
from datasets import load_dataset
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
from trl import SFTTrainer, SFTConfig

MODEL_ID = "deepseek-ai/DeepSeek-R1-Distill-Llama-8B"

bnb = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
)

tok = AutoTokenizer.from_pretrained(MODEL_ID)
model = AutoModelForCausalLM.from_pretrained(MODEL_ID, quantization_config=bnb, device_map="auto")
model = prepare_model_for_kbit_training(model)

lora = LoraConfig(
    r=16, lora_alpha=32, lora_dropout=0.05,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
    bias="none", task_type="CAUSAL_LM",
)
model = get_peft_model(model, lora)

ds = load_dataset("json", data_files={"train": "train.jsonl", "eval": "eval.jsonl"})

cfg = SFTConfig(
    output_dir="ds-r1-distill-tuned",
    num_train_epochs=3,
    per_device_train_batch_size=2,
    gradient_accumulation_steps=8,
    learning_rate=2e-4,
    bf16=True,
    logging_steps=20,
    eval_strategy="steps",
    eval_steps=100,
    save_steps=200,
)

trainer = SFTTrainer(model=model, args=cfg, train_dataset=ds["train"],
                     eval_dataset=ds["eval"], processing_class=tok)
trainer.train()
trainer.save_model("ds-r1-distill-tuned/final")

The processing_class argument is the name recent TRL releases use for the tokenizer; older releases called it tokenizer. If you want a higher-level wrapper, open-source trainers such as LlamaFactory support DeepSeek models with LoRA and QLoRA and hide most of the boilerplate above behind a YAML config; check the project’s README for the current list of methods and models.

Step 5 — Verify it worked

Three checks, in order:

1. Validation loss curve: should drop and then plateau. A loss that keeps falling while held-out accuracy stalls is overfitting — stop earlier next time.
2. Held-out accuracy or exact-match: compute on the test split you set aside in step 2. Compare against the same metric for the un-tuned base model. If the gap is under 5 percentage points, the fine-tune is not pulling its weight.
3. Spot-check 20 outputs by hand. Numerical wins sometimes hide format regressions, hallucinated tags, or repeated tokens.

Then merge the adapter and serve. For local serving, vLLM and SGLang both load LoRA adapters directly. If you prefer a managed serverless path, see DeepSeek Docker deployment for the container side, or push the adapter to Hugging Face and load it from any inference runtime that supports PEFT.

Step 6 — Common errors and fixes

Where DeepSeek V4 fits in

The current API changes the calculus for some of these projects. DeepSeek’s API now lists two models: deepseek-flash, served by DeepSeek-V4.1-Flash-1017 (the only one with image input), and deepseek-v4-pro, served by DeepSeek-V4-Pro-0813. Both have a 1M-token context window with output up to 384K tokens — context that previously demanded a fine-tune for retrieval-style tasks now often fits inline. If your fine-tune was meant to extend the behaviour of the old deepseek-chat model ID (scheduled for retirement on 24 July 2026 at 15:59 UTC and no longer listed in DeepSeek’s docs), check first whether prompting deepseek-flash closes the gap.

Thinking mode is a parameter, not a separate model, and it is on by default: reasoning_effort takes "low", "high" or "max", and the response returns reasoning_content alongside the final content. Other features worth knowing before deciding to fine-tune: JSON mode (response_format={"type": "json_object"} — designed to return valid JSON, not guaranteed; include the word “json” plus a small example schema in the prompt and set max_tokens high enough to avoid truncation), tool calling, streaming, FIM completion (Beta, non-thinking mode only) and Chat Prefix Completion (Beta). DeepSeek’s temperature guidance — 0.0 for code and maths, 1.0 for data analysis, 1.3 for general chat and translation, 1.5 for creative writing — applies in non-thinking mode only, because thinking mode ignores temperature. The API is stateless: the client must resend conversation history with every request, unlike the web/app which keeps session history for the user. Request formats are covered in our DeepSeek API documentation overview.

Cost: train your own vs call the API

Run the numbers before you rent a GPU. Take a workload of 1,000,000 calls per month with a 2,000-token cached system prompt, a 200-token user message, and a 300-token response. On deepseek-flash rates as of October 2026 (peak / off-peak, per 1M tokens):

• Cached input: 2,000 × 1,000,000 = 2,000,000,000 tokens × $0.006/M = $12.00 peak; × $0.003/M = $6.00 off-peak
• Uncached input: 200 × 1,000,000 = 200,000,000 tokens × $0.30/M = $60.00 peak; × $0.15/M = $30.00 off-peak
• Output: 300 × 1,000,000 = 300,000,000 tokens × $1.20/M = $360.00 peak; × $0.60/M = $180.00 off-peak
• Total: $432.00 per month if run entirely in peak hours; $216.00 if run entirely off-peak

The same workload on deepseek-v4-pro ($0.044 / $1.32 / $3.96 per 1M at peak; $0.022 / $0.66 / $1.98 off-peak) totals $1,540.00 at peak or $770.00 off-peak — about 3.6× the Flash bill. Peak hours are 01:00–04:00 and 06:00–10:00 UTC, Monday to Friday (excluding Chinese public holidays); everything else is off-peak. By contrast, a single LoRA or QLoRA training run on a rented GPU is usually a small, one-off cost — but factor in iterations, evaluation, debugging, and ongoing serving on a dedicated endpoint, and a self-hosted fine-tune only pays for itself at much higher volume. Check your GPU provider’s current hourly rates, and for a fuller breakdown try the DeepSeek pricing calculator.

Always check the official DeepSeek pricing page before committing — DeepSeek says its prices may vary.

Licensing — read before you ship

Per-model, not generalised. DeepSeek-V4.1-Flash-1017 and DeepSeek-V4-Pro-0813 publish both code and weights under the MIT licence on Hugging Face, as do V3.2, V3.1 and R1. The R1 distills are published under MIT too, but DeepSeek’s R1 model card notes that the Qwen-based distills derive from Qwen2.5 (originally Apache 2.0) and DeepSeek-R1-Distill-Llama-8B from Llama 3.1-8B-Base (originally under the Llama 3.1 licence), so those upstream terms matter as well. Older releases — V3 base, Coder-V2, VL2 — split MIT code from a separate DeepSeek Model License on the weights. If your fine-tune is going into a commercial product, check the specific Hugging Face repo for your base checkpoint before training.

Alternative paths

• Prompt engineering first. Prompts are reversible; fine-tunes are not. See DeepSeek prompt engineering.
• RAG instead of fine-tuning. When the goal is recall over private documents, retrieval is almost always cheaper. The DeepSeek RAG tutorial covers the pipeline.
• Hosted SFT. If you do not want to run a GPU at all, some hosted inference providers offer managed fine-tuning for open DeepSeek checkpoints; check each provider’s current model list and pricing.
• Other tutorials in this series. Browse the DeepSeek tutorials hub for related step-by-steps.