Fine-Tune DeepSeek V3 on Custom Domain Data: Complete 2026 Guide

# Verify GPU
nvidia-smi

# Expected: A100 40GB or equivalent
# Minimum: 40GB VRAM for QLoRA on DeepSeek V3

# Create isolated environment
uv venv .venv --python 3.11
source .venv/bin/activate

# Install Unsloth with DeepSeek V3 support (requires Unsloth >= 2025.3)
uv pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"
uv pip install torch==2.4.0 --index-url https://download.pytorch.org/whl/cu121
uv pip install xformers trl peft accelerate bitsandbytes datasets

# Verify Unsloth installed correctly
python -c "import unsloth; print(unsloth.__version__)"

# dataset_prep.py
import json

# Each record: instruction + input (optional context) + output
examples = [
    {
        "instruction": "Convert this plain English query to SQL for our orders schema.",
        "input": "Show me all orders over $500 placed in Q1 2026 that haven't shipped.",
        "output": "SELECT * FROM orders WHERE total_amount > 500 AND order_date BETWEEN '2026-01-01' AND '2026-03-31' AND shipped_at IS NULL;"
    },
    # ... add your domain examples here
]

with open("domain_data.json", "w") as f:
    json.dump(examples, f, indent=2)

print(f"Saved {len(examples)} examples")

# Each record is a list of turns with role + content
examples = [
    {
        "conversations": [
            {"from": "human", "value": "What does error code E4021 mean in our system?"},
            {"from": "gpt", "value": "E4021 is a payment gateway timeout. It fires when our Stripe webhook doesn't receive a response within 30 seconds. Check the `payment_logs` table for the `gateway_request_id` to trace the specific transaction."}
        ]
    }
]

# Validate your dataset before training
python -c "
import json
data = json.load(open('domain_data.json'))
print(f'Records: {len(data)}')
print(f'Sample keys: {list(data[0].keys())}')
print(f'Sample output length: {len(data[0][\"output\"])} chars')
"

# train.py
from unsloth import FastLanguageModel
import torch

# Load DeepSeek V3 in 4-bit — requires ~38GB VRAM
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="deepseek-ai/DeepSeek-V3",
    max_seq_length=4096,   # Increase to 8192 if your examples are long
    dtype=None,            # Auto-detect: bf16 on Ampere+, fp16 on older
    load_in_4bit=True,     # QLoRA: reduces memory from ~160GB to ~38GB
)

print(f"Model loaded. Parameters: {model.num_parameters():,}")

# Attach LoRA to attention and MLP layers
# r=16 is a good default; increase to 32 for harder domain shifts
model = FastLanguageModel.get_peft_model(
    model,
    r=16,                          # LoRA rank — higher = more capacity, more VRAM
    target_modules=[
        "q_proj", "k_proj", "v_proj", "o_proj",  # Attention projections
        "gate_proj", "up_proj", "down_proj",       # MLP projections (MoE gates)
    ],
    lora_alpha=16,                 # Scale factor; keep equal to r as a starting point
    lora_dropout=0.05,             # Small dropout prevents overfitting on small datasets
    bias="none",
    use_gradient_checkpointing="unsloth",  # Unsloth's optimized checkpointing saves ~30% VRAM
    random_state=42,
    use_rslora=False,              # Set True if training > 5,000 examples — stabilizes learning
)

# Confirm trainable parameter count
trainable = sum(p.numel() for p in model.parameters() if p.requires_grad)
total = sum(p.numel() for p in model.parameters())
print(f"Trainable: {trainable:,} / {total:,} ({100 * trainable / total:.2f}%)")

from datasets import load_dataset
from trl import SFTTrainer
from transformers import TrainingArguments
from unsloth import is_bfloat16_supported

# Load and format dataset
dataset = load_dataset("json", data_files="domain_data.json", split="train")

# Alpaca prompt template — consistent formatting improves training signal
alpaca_prompt = """Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request.

### Instruction:
{}

### Input:
{}

### Response:
{}"""

EOS_TOKEN = tokenizer.eos_token

def format_prompts(examples):
    instructions = examples["instruction"]
    inputs = examples.get("input", [""] * len(instructions))
    outputs = examples["output"]
    texts = []
    for instruction, inp, output in zip(instructions, inputs, outputs):
        # EOS token tells the model where the response ends — critical to include
        text = alpaca_prompt.format(instruction, inp, output) + EOS_TOKEN
        texts.append(text)
    return {"text": texts}

dataset = dataset.map(format_prompts, batched=True)

# Training config
trainer = SFTTrainer(
    model=model,
    tokenizer=tokenizer,
    train_dataset=dataset,
    dataset_text_field="text",
    max_seq_length=4096,
    dataset_num_proc=4,
    packing=False,   # Set True for short examples (< 512 tokens) to speed up training
    args=TrainingArguments(
        per_device_train_batch_size=2,
        gradient_accumulation_steps=4,   # Effective batch size = 2 * 4 = 8
        warmup_steps=10,
        num_train_epochs=3,              # 3 epochs is usually enough; watch for overfitting
        learning_rate=2e-4,
        fp16=not is_bfloat16_supported(),
        bf16=is_bfloat16_supported(),
        logging_steps=10,
        optim="adamw_8bit",              # 8-bit Adam cuts optimizer memory by ~75%
        weight_decay=0.01,
        lr_scheduler_type="cosine",
        seed=42,
        output_dir="./outputs",
        save_strategy="epoch",
    ),
)

# Start training
trainer_stats = trainer.train()

# Print training summary
print(f"Training time: {trainer_stats.metrics['train_runtime']:.0f}s")
print(f"Final loss: {trainer_stats.metrics['train_loss']:.4f}")

# Watch GPU memory and utilization every 2 seconds
watch -n 2 nvidia-smi

# Save LoRA adapter only (~200MB, not the full 38GB model)
model.save_pretrained("deepseek-v3-domain-adapter")
tokenizer.save_pretrained("deepseek-v3-domain-adapter")

print("Adapter saved to ./deepseek-v3-domain-adapter")

# Optional: merge adapter into model weights for faster inference
# This requires full VRAM — only do this if deploying to a dedicated server
model.save_pretrained_merged(
    "deepseek-v3-domain-merged",
    tokenizer,
    save_method="merged_16bit",   # "merged_4bit" for smaller file
)

from unsloth import FastLanguageModel

# Reload the base model and apply adapter
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="deepseek-ai/DeepSeek-V3",
    max_seq_length=4096,
    dtype=None,
    load_in_4bit=True,
)
model.load_adapter("deepseek-v3-domain-adapter")
FastLanguageModel.for_inference(model)  # Unsloth 2x faster inference mode

# Test with a domain example NOT in your training set
inputs = tokenizer(
    [alpaca_prompt.format(
        "Convert this to SQL for our orders schema.",
        "All customers who made more than 3 purchases last month",
        "",  # Leave output blank — the model fills this in
    )],
    return_tensors="pt"
).to("cuda")

outputs = model.generate(**inputs, max_new_tokens=256, temperature=0.1)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

# Create a Modelfile pointing to your merged weights
cat > Modelfile << 'EOF'
FROM ./deepseek-v3-domain-merged
SYSTEM "You are a SQL assistant for the Acme Corp orders database. Always use our schema conventions."
PARAMETER temperature 0.1
PARAMETER num_ctx 4096
EOF

ollama create deepseek-acme -f Modelfile
ollama run deepseek-acme

# Serve base model and load adapter at runtime — no merge needed
python -m vllm.entrypoints.openai.api_server \
  --model deepseek-ai/DeepSeek-V3 \
  --enable-lora \
  --lora-modules domain-adapter=./deepseek-v3-domain-adapter \
  --quantization awq \
  --tensor-parallel-size 4