Magistral fijnslijpen: een stapsgewijze gids

Mistral AI heeft onlangs een nieuwe familie van redeneermodellen gelanceerd, genaamd Magistral. Deze modellen zijn ontworpen om uit te blinken in specifieke domeinen, transparant te redeneren en meerdere talen te ondersteunen.

In deze tutorial richten we ons op het fijn-tunen van Magistral Small op de Medical MCQs-reasoningdataset. Magistral Small is een open-sourcevariant van de Magistral-familie met 24 miljard parameters. Het is gebaseerd op versie 3.1 (2503) en heeft verbeterde redeneercapaciteiten.

Dit zijn de stappen die we in deze tutorial volgen:

• Stel de omgeving in en installeer alle benodigde dependencies.
• Laad het voorgetrainde Magistral Small-model en de tokenizer ter voorbereiding op maatwerk.
• Laad de medische MCQ-dataset en verwerk deze zodat hij klaar is voor training.
• Voer modelinference uit vóór het fijn-tunen om een basislijn voor vergelijking vast te stellen.
• Configureer het model en de trainingsparameters en start vervolgens het fijn-tuneproces.
• Vergelijk de resultaten vóór en na het fijn-tunen om verbeteringen te evalueren.
• Sla het fijn-getunede model en de tokenizer op en upload ze naar een Hugging Face-repository om te delen en te deployen.

1. Aan de slag

Ik probeerde het fijn-tunescript eerst op Kaggle te draaien, maar zelfs met 4-bit kwantisatie bleken de gratis GPU’s onvoldoende voor deze taak. Vanwege deze beperkingen stapte ik over naar RunPod en koos ik een A100 SXM-GPU-instantie, die snellere prestaties en meer VRAM biedt.

1. Ga op RunPod naar “Pods”, kies de nieuwste PyTorch-image, selecteer de A100 SXM-machine en deploy je pod.

Bron: My Pods

2. Bewerk de Pod-instellingen om de containerschijfgrootte te vergroten en voeg je Hugging Face-toegangstoken toe voor authenticatie.

Bron: My Pods

3. Zodra de pod draait, klik je op de Connect-knop en start je een JupyterLab-instantie voor interactieve ontwikkeling.

4. Installeer alle benodigde Python-pakketten

%%capture
%pip install -U transformers==4.52.1
%pip install -U datasets 
%pip install -U accelerate 
%pip install -U peft 
%pip install -U trl 
%pip install -U bitsandbytesMogelijk gemaakt door

5. Log in bij Hugging Face met je toegangstoken (dat je eerder hebt opgeslagen). Zo kun je gated modellen laden en later je fijn-getunede model en tokenizer uploaden:

from huggingface_hub import login
import os

hf_token = os.environ.get("HF_TOKEN")
login(hf_token)Mogelijk gemaakt door

2. Het model en de tokenizer laden

We gebruiken de Unsloth 4-bit gekwantiseerde versie van Magistral-Small om zowel opslagruimte als VRAM te besparen. Deze aanpak is veel sneller en efficiënter dan het full-precision model downloaden en handmatig kwantiseren. 

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

# Load tokenizer & model

model_dir = "unsloth/Magistral-Small-2506-bnb-4bit"

tokenizer = AutoTokenizer.from_pretrained(model_dir, use_fast=True)
model = AutoModelForCausalLM.from_pretrained(
    model_dir,
    device_map="auto",  
    torch_dtype=torch.bfloat16,             
)

model.config.use_cache = False
model.config.pretraining_tp = 1Mogelijk gemaakt door

Controleer na het laden van het model je GPU-geheugengebruik.

!nvidia-smiMogelijk gemaakt door

Zoals we zien, gebruikt het slechts 23GB VRAM. 

3. De dataset laden en verwerken

Definieer een prompttemplate die het model instrueert te antwoorden met een van de gegeven opties, de redenering op te nemen tussen <analysis></analysis>-tags en het eindantwoord tussen <answer></answer>-tags.

train_prompt_style = """
Please answer with one of the options in the bracket. Write reasoning in between <analysis></analysis>. Write the answer in between <answer></answer>.
### Question:
{}

### Response:
{}"""
Mogelijk gemaakt door

Maak een Python-functie om elk voorbeeld te formatteren volgens de promptstijl en voeg de EOS-token toe als die ontbreekt.

EOS_TOKEN = tokenizer.eos_token  # Must add EOS_TOKEN

def formatting_prompts_func(examples):
    inputs = examples["input"]
    outputs = examples["output"]
    texts = []
    for question, response in zip(inputs, outputs):
        # Remove the "Q:" prefix from the question
        question = question.replace("Q:", "")
        
        # Append the EOS token to the response if it's not already there
        if not response.endswith(tokenizer.eos_token):
            response += tokenizer.eos_token
            
        text = train_prompt_style.format(question, response)
        texts.append(text)
    return {"text": texts}Mogelijk gemaakt door

Download en laad vervolgens de mamachang/medical-reasoning-dataset van Hugging Face. Pas de formatteringsfunctie toe om een nieuwe kolom "text" te maken met de gestructureerde prompt.

from datasets import load_dataset

dataset = load_dataset(
    "mamachang/medical-reasoning",
    split="train",
    trust_remote_code=True,
)
dataset = dataset.map(
    formatting_prompts_func,
    batched=True,
)
print(dataset["text"][10])Mogelijk gemaakt door

De kolom "text" bevat de systemprompt, vraag, analyse en antwoord, allemaal in het vereiste formaat.

Omdat de nieuwe SFTTrainer niet direct een tokenizer accepteert, zet je de tokenizer om in een datacollator voor taalmodellering.

from transformers import DataCollatorForLanguageModeling

data_collator = DataCollatorForLanguageModeling(
    tokenizer=tokenizer,
    mlm=False
)Mogelijk gemaakt door

4. Modelinference vóór het fijn-tunen

Vóór het fijn-tunen is het belangrijk om de prestatie van het basismodel op je dataset te evalueren. Deze basislijn helpt je om resultaten na het fijn-tunen objectief te vergelijken en verbeteringen te meten.

Definieer een prompttemplate voor inference met een systemprompt, een vragensectie (met placeholder) en een responssectie. 

inference_prompt_style = """
Please answer with one of the options in the bracket. Write reasoning in between <analysis></analysis>. Write the answer in between <answer></answer>.

### Question:
{}

### Response:
<analysis>
"""Mogelijk gemaakt door

Selecteer de 11e vraag uit je dataset, verwijder eventuele onnodige voorvoegsels en tokeniseer deze voor modelinput

question = dataset[10]['input']
question = question.replace("Q:", "")

inputs = tokenizer(
    [inference_prompt_style.format(question) + tokenizer.eos_token],
    return_tensors="pt"
).to("cuda")

outputs = model.generate(
    input_ids=inputs.input_ids,
    attention_mask=inputs.attention_mask,
    max_new_tokens=512,
    eos_token_id=tokenizer.eos_token_id,
    use_cache=True,
)
response = tokenizer.batch_decode(outputs, skip_special_tokens=True)
print(response[0].split("### Response:")[1])Mogelijk gemaakt door

In deze baseline-test was de door het model gegenereerde analyse buitensporig lang en leverde het vaak geen correct of beknopt antwoord op. 

5. Het model instellen

In dit deel stellen we het model in voor fijn-tunen. 

We gebruiken LoRA (Low-Rank Adaptation) om het model te fijn-tunen, wat ons geheugenverbruik aanzienlijk verlaagt en het trainingsproces versnelt, omdat we slechts een klein deel van de modelparameters fijn-tunen.

from peft import LoraConfig, get_peft_model

# LoRA config
peft_config = LoraConfig(
    lora_alpha=16,                           # Scaling factor for LoRA
    lora_dropout=0.05,                       # Add slight dropout for regularization
    r=64,                                    # Rank of the LoRA update matrices
    bias="none",                             # No bias reparameterization
    task_type="CAUSAL_LM",                   # Task type: Causal Language Modeling
    target_modules=[
        "q_proj",
        "k_proj",
        "v_proj",
        "o_proj",
        "gate_proj",
        "up_proj",
        "down_proj",
    ],  # Target modules for LoRA
)

model = get_peft_model(model, peft_config)Mogelijk gemaakt door

De klasse TrainingArguments laat je batchgrootte, optimizer, learning rate en andere traininghyperparameters configureren. De SFTTrainer uit de TRL-bibliotheek stroomlijnt supervised fine-tuning door model, dataset, datacollator, trainingsargumenten en LoRA-configuratie in één workflow te integreren.

from trl import SFTTrainer
from transformers import TrainingArguments


# Training Arguments
training_arguments = TrainingArguments(
    output_dir="Magistral-Medical-Reasoning",
    per_device_train_batch_size=1,
    per_device_eval_batch_size=1,
    gradient_accumulation_steps=2,
    optim="paged_adamw_32bit",
    num_train_epochs=1,
    logging_steps=0.2,
    warmup_steps=10,
    logging_strategy="steps",
    learning_rate=2e-4,
    fp16=False,
    bf16=False,
    group_by_length=True,
    report_to="none"
)

# Initialize the Trainer
trainer = SFTTrainer(
    model=model,
    args=training_arguments,
    train_dataset=dataset,
    peft_config=peft_config,
    data_collator=data_collator,
)Mogelijk gemaakt door

6. Modeltraining

Om Out of Memory (OOM)-fouten te voorkomen, is het belangrijk om vóór de training de Python-garbagecollector te legen en de CUDA-cache te wissen. Zo wordt ongebruikt geheugen van eerdere bewerkingen vrijgegeven.

Start daarna het trainingsproces met de SFTTrainer.

import gc, torch
gc.collect()
torch.cuda.empty_cache()
model.config.use_cache = False
trainer.train()Mogelijk gemaakt door

Tijdens de training bereikte het GPU-gebruik 100%, en er was voldoende VRAM beschikbaar om mogelijk nog een model parallel te laden.

Het trainingsproces duurde ongeveer 1 uur en 10 minuten, waarbij de training loss bij elke stap gestaag afnam, wat wijst op effectief leren.

7. Modelinference na het fijn-tunen

We evalueren de prestaties van het fijn-getunede model met dezelfde 11e voorbeeldvraag uit de dataset. Zo kunnen we de resultaten vergelijken met het basismodel en de verbeteringen door het fijn-tunen beoordelen.

question = dataset[10]['input']
question = question.replace("Q:", "")

inputs = tokenizer(
    [inference_prompt_style.format(question,) + tokenizer.eos_token],
    return_tensors="pt"
).to("cuda")

outputs = model.generate(
    input_ids=inputs.input_ids,
    attention_mask=inputs.attention_mask,
    max_new_tokens=512,
    eos_token_id=tokenizer.eos_token_id,
    use_cache=True,
)
response = tokenizer.batch_decode(outputs, skip_special_tokens=True)
print(response[0].split("### Response:")[1])Mogelijk gemaakt door

Het model genereert nu een beknopte en nauwkeurige analyse, en het antwoord is correct.

<analysis>
Analysis:

This is a prospective cohort study looking at the relationship between childhood diet and cardiovascular disease in adulthood. The key issue with the validity of this study is confounding. The researchers did not account for other factors that could influence cardiovascular disease risk in adulthood besides childhood diet. 

To address confounding, the researchers should have stratified the analysis by potential confounders like family history, physical activity levels, and smoking status. This would allow them to see if the relationship between diet and disease persists even when accounting for these other variables. 

Blinding, crossover, matching, and randomization do not address the main validity concern in this study design.
</analysis>
<answer>
D: Stratification
</answer>Mogelijk gemaakt door

Voer voor extra validatie inference uit op een andere sample.

question = dataset[100]['input']
question = question.replace("Q:", "")

inputs = tokenizer(
    [inference_prompt_style.format(question) + tokenizer.eos_token],
    return_tensors="pt"
).to("cuda")

outputs = model.generate(
    input_ids=inputs.input_ids,
    attention_mask=inputs.attention_mask,
    max_new_tokens=512,
    eos_token_id=tokenizer.eos_token_id,
    use_cache=True,
)
response = tokenizer.batch_decode(outputs, skip_special_tokens=True)
print(response[0].split("### Response:")[1])Mogelijk gemaakt door

Het model blijft nauwkeurige antwoorden en goed gestructureerde analyses geven, wat consistente verbeteringen laat zien, zelfs na slechts één epoch fijn-tunen.

<analysis>

This is a clinical vignette describing a 55-year-old man with burning and shooting pain in his feet and lower legs that worsens at night. He has a history of type 2 diabetes mellitus and hypertension. 

The key findings are:
- Burning and shooting pain in feet and lower legs 
- Pain worsens at night
- History of type 2 diabetes mellitus

This presentation is most consistent with diabetic peripheral neuropathy. The pain distribution, timing, and history of diabetes point towards a distal symmetric sensorimotor polyneuropathy as the etiology. The other options can be ruled out based on the clinical presentation.
</analysis>
<answer>
D: Distal symmetric sensorimotor polyneuropathy
</answer>Mogelijk gemaakt door

8. Het model opslaan 

Na het fijn-tunen kun je je model eenvoudig delen door het naar de Hugging Face Hub te pushen. Zo wordt het toegankelijk voor anderen om te gebruiken of verder te fijn-tunen.

new_model_name = "kingabzpro/Magistral-Small-Medical-QA"

trainer.model.push_to_hub(new_model_name)
trainer.processing_class.push_to_hub(new_model_name)Mogelijk gemaakt door

Het fijn-getunede model is nu beschikbaar op: kingabzpro/Magistral-Small-Medical-QA

Bron: kingabzpro/Magistral-Small-Medical-QA

9. Het fijn-getunede model laden vanaf Hugging Face

Na het fijn-tunen en opslaan van je LoRA op de Hugging Face Hub kun je deze eenvoudig opnieuw laden voor verdere analyse, inference of deployment als inference-server. Dit proces omvat het leegmaken van je huidige sessie, het laden van het basismodel en de LoRA-adapter, en het draaien van inference op nieuwe data. Je kunt meer leren over Werken met de Hugging Face Hub in onze cursus. 

1. Voordat je een nieuw model laadt, is het goed om bestaande model- en trainerobjecten te verwijderen en de GPU-cache te wissen om geheugenproblemen te voorkomen.

2. Download het basismodel en je fijn-getunede LoRA-adapter van de Hugging Face Hub en merge ze. Laad ook de tokenizer. 

del model
del trainer
torch.cuda.empty_cache()


from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
from peft import PeftModel
import torch

# Base model
base_model_id = "unsloth/Magistral-Small-2506-bnb-4bit"

# Your fine-tuned LoRA adapter repository
lora_adapter_id = "kingabzpro/Magistral-Small-Medical-QA"

# Load base model
base_model = AutoModelForCausalLM.from_pretrained(
    base_model_id,
    device_map="auto",
    torch_dtype=torch.bfloat16,
    trust_remote_code=True,
)

# Attach the LoRA adapter
model = PeftModel.from_pretrained(
    base_model,
    lora_adapter_id,
    device_map="auto",
    trust_remote_code=True,
)

# Load tokenizer
tokenizer = AutoTokenizer.from_pretrained(base_model_id, trust_remote_code=True)Mogelijk gemaakt door

3. Bereid een voorbeeldprompt voor, tokeniseer deze, genereer een respons en decodeer de output. 

# Inference example
prompt = """
Please answer with one of the options in the bracket. Write reasoning in between <analysis></analysis>. Write the answer in between <answer></answer>.

### Question:
A research group wants to assess the relationship between childhood diet and cardiovascular disease in adulthood.
A prospective cohort study of 500 children between 10 to 15 years of age is conducted in which the participants' diets are recorded for 1 year and then the patients are assessed 20 years later for the presence of cardiovascular disease.
A statistically significant association is found between childhood consumption of vegetables and decreased risk of hyperlipidemia and exercise tolerance.
When these findings are submitted to a scientific journal, a peer reviewer comments that the researchers did not discuss the study's validity.
Which of the following additional analyses would most likely address the concerns about this study's design? 
{'A': 'Blinding', 'B': 'Crossover', 'C': 'Matching', 'D': 'Stratification', 'E': 'Randomization'},
### Response:
<analysis>

"""

inputs = tokenizer(
    [prompt + tokenizer.eos_token],
    return_tensors="pt"
).to("cuda")

outputs = model.generate(
    input_ids=inputs.input_ids,
    attention_mask=inputs.attention_mask,
    max_new_tokens=1200,
    eos_token_id=tokenizer.eos_token_id,
    use_cache=True,
)
response = tokenizer.batch_decode(outputs, skip_special_tokens=True)
print(response[0].split("### Response:")[1])Mogelijk gemaakt door

4. De gegenereerde respons is accuraat en sluit nauw aan bij de stijl en structuur van je dataset, wat aantoont dat het fijn-getunede model klaar is voor inference en deployment in de praktijk.

<analysis>

Analysis:
This is a prospective cohort study looking at the relationship between childhood diet and cardiovascular disease in adulthood. The key concern from the peer reviewer is about the study's validity. 

To address concerns about validity, the researchers could perform additional analyses to control for confounding. Matching and stratification would help control for known confounders like socioeconomic status or family history. Crossover and blinding are not applicable to this observational study design. Randomization would not be possible since the study is observational.
</analysis>
<answer>
D: Stratification
</answer>
Mogelijk gemaakt door

Als je problemen tegenkomt bij het uitvoeren van bovenstaande code, raadpleeg dan de fine-tuning-magistral.ipynb Jupyter-notebook op Hugging Face.

Conclusie

In een aparte fine-tuninggids bekeken we hoe de gedistilleerde modus van DeepSeek-R1-0528 presteert. Terwijl DeepSeek-R1-0528 moeite had om zich aan te passen aan de specifieke stijl van de dataset en qua nauwkeurigheid, liet Magistral zich moeiteloos aanpassen en leverde het sterke resultaten met minimale inspanning. 

Deze ervaring versterkt mijn overtuiging dat Mistral AI zich snel ontwikkelt tot een toonaangevende speler in het AI-domein, niet alleen in taalmodellen maar ook in een breed scala aan oplossingen, waaronder computervisie.

In deze gids hebben we met succes Mistral AI’s nieuwste redeneermodel, Magistral, fijn-getuned op een medische MCQ-dataset. 

Houd er echter rekening mee dat het fijn-tunen van grote modellen zoals Magistral aanzienlijke hardware vereist, doorgaans GPU’s met minstens 40GB VRAM, aangezien zelfs de RTX 4090 mogelijk niet volstaat voor sommige configuraties. Ik experimenteerde ook met het Unsloth-framework en de 4-bit modelversie, maar liep toch tegen GPU-geheugenproblemen aan.

Wil je een praktijkgerichte cursus om vertrouwd te raken met fijn-tunen? Bekijk dan zeker Fine-Tuning With Llama 3.