Magistral Small: una guida con progetto demo su vLLM e Ollama

Mistral ha rilasciato il suo primo modello di reasoning, Magistral, disponibile in due varianti: Magistral Small (open-weight) e Magistral Medium (modello chiuso).

In questo blog mi concentrerò su Magistral Small, un modello di reasoning open-weight progettato per compiti che richiedono logica strutturata, comprensione multilingue e la capacità di fornire spiegazioni tracciabili. Abbinato a motori di inferenza ad alto throughput come vLLM o a strumenti semplici da usare come Ollama, diventa un ottimo strumento per il debug di logiche fallaci e attività di ragionamento.

In questo tutorial ti spiegherò passo dopo passo come:

• Eseguire Magistral Small (24B) con vLLM e Ollama
• Costruire un progetto demo che esegue il debug della logica con un ragionamento trasparente, passo dopo passo

Teniamo aggiornati i nostri lettori sulle ultime novità in AI con The Median, la nostra newsletter gratuita del venerdì che riassume le storie chiave della settimana. Iscriviti e resta sul pezzo in pochi minuti a settimana:

Che cos'è Magistral di Mistral?

Magistral è il primo modello di reasoning dedicato di Mistral AI, costruito per logica passo dopo passo, accuratezza multilingue e output tracciabili. È un rilascio doppio disponibile in due varianti:

• Magistral Small (24B): modello completamente open source, disponibile sotto Apache 2.0 e adatto al deployment locale. 
• Magistral Medium: un modello enterprise più potente, disponibile tramite Le Chat di Mistral, SageMaker e altri cloud enterprise.

Fonte: Mistral

Magistral Small, il modello open su cui ci concentreremo, supporta una finestra di contesto di 128K (40K consigliata per prestazioni stabili). È addestrato con fine-tuning supervisionato su tracce di Magistral Medium e reinforcement learning.

Come configurare ed eseguire Magistral Small in locale con Ollama

In questa sezione eseguiremo l'inferenza sul modello Magistral di Mistral in locale usando Ollama. Nota che questo modello richiede circa 14 GB di spazio e può essere eseguito su una singola RTX 4090 o su un MacBook con 32 GB di RAM una volta quantizzato. Ho eseguito questa demo su un MacBook Pro M3.

Passaggio 1: Recupera il modello tramite Ollama

Scarica Ollama per macOS, Windows o Linux da: https://ollama.com/download.

Segui le istruzioni dell’installer e, dopo l’installazione, verifica eseguendo nel terminale:

ollama --versionOfferto da

Poi recupera il modello Magistral eseguendo il seguente comando:

ollama pull magistralOfferto da

Questo scaricherà il modello Magistral sulla tua macchina locale. Nota: servirà del tempo perché il modello è di circa 14 GB.

Passaggio 2: Installa le dipendenze

Iniziamo installando tutte le dipendenze necessarie.

pip install ollama
pip install requestsOfferto da

Con le dipendenze installate, siamo pronti per eseguire l'inferenza.

Passaggio 3: Crea un template di prompt strutturato

Ora impostiamo una struttura di prompt template (come indicato nell’articolo originale su Magistral) che guidi il modo di pensare del modello.

import gradio as gr
import requests
import json
def build_prompt(flawed_logic):
    return f"""<s>[SYSTEM_PROMPT]
A user will ask you to solve a task. You should first draft your thinking process (inner monologue) until you have derived the final answer. Afterwards, write a self-contained summary of your thoughts.
Your thinking process must follow the template below:
<think>
Your thoughts or/and draft, like working through an exercise on scratch paper. Be as casual and detailed as needed until you're confident.
</think>
Do not mention that you're debugging — just present your thought process and conclusion naturally.
[/SYSTEM_PROMPT][INST]
Here is a flawed solution. Can you debug it and correct it step by step?
\"\"\"{flawed_logic}\"\"\"
[/INST]
"""Offerto da

La funzione sopra restituisce un prompt formattato che guida Magistral a:

• Ragionare passo dopo passo usando i tag <think>...</think>
• Fornire una conclusione chiara dopo il monologo interno
• Ignorare qualsiasi menzione di “debugging” per una spiegazione naturale

Questa struttura è importante per modelli come Magistral addestrati con prompt potenziati da strumenti. Lo stesso system prompt può essere utilizzato sia per problemi matematici che di coding.

Passaggio 4: Effettua lo streaming dell'inferenza e costruisci la UI con Gradio

In questo passaggio, trasmettiamo in tempo reale l’output del modello Magistral usando le API locali di Ollama. Dato che ci concentriamo sul debug di logiche difettose con un ragionamento tracciabile, passo dopo passo, è importante che l’utente possa vedere come il modello arriva alle sue conclusioni. Infine, mostriamo la spiegazione tramite un’interfaccia Gradio pulita.

def call_ollama_stream(flawed_logic):
    prompt = build_prompt(flawed_logic)
    response_text = ""
    with requests.post(
        "http://localhost:11434/api/generate",
        json={"model": "magistral", "prompt": prompt, "stream": True},
        stream=True,
    ) as r:
        for line in r.iter_lines():
            if line:
                content = json.loads(line).get("response", "")
                response_text += content
    return response_text
with gr.Blocks(theme=gr.themes.Base()) as demo:
    gr.Markdown("## Chain-of-Logic Debugger (Magistral + Ollama)")
    gr.Markdown("Paste a flawed logical argument or math proof, and Magistral will debug it with step-by-step reasoning.")
    with gr.Row():
        input_box = gr.Textbox(lines=8, label="Flawed Logic / Proof")
        output_box = gr.Textbox(lines=15, label="Debugged Explanation")  
    debug_button = gr.Button("Run Debugger")
    debug_button.click(fn=call_ollama_stream, inputs=input_box, outputs=output_box)
demo.launch(debug = True, share=True)Offerto da

Ecco cosa succede qui in sintesi:

• Partiamo con una funzione riutilizzabile build_prompt() per incapsulare l’input dell’utente in un prompt strutturato che guida il modello con tag di ragionamento <think>.
• Quando l’utente invia una dimostrazione o un’asserzione logica difettosa, la funzione call_ollama_stream() invia il prompt all’API HTTP di Ollama su localhost:11434 usando una richiesta POST in streaming.
• La funzione ascolta le risposte trasmesse riga per riga usando requests.iter_lines(). Per ogni riga ricevuta, estrae il campo di risposta dal payload JSON e lo aggiunge a un buffer di testo cumulativo.
• Una volta raccolte tutte le righe, la risposta completa del modello viene restituita e mostrata nella UI di Gradio.

Ecco l’input che ho provato:

Assume x = y. Then, x² = xy. Subtracting both sides gives x² - y² = xy - y². So, (x+y)(x−y) = y(x−y). Cancelling x−y gives x+y = y. But since x = y, this means 2y = y → 2 = 1.Offerto da

Nei miei test su un MacBook Pro M3, il modello ha gestito abbastanza bene catene logiche semplici e dimostrazioni matematiche. Tuttavia, per compiti di ragionamento più profondi o catene di pensiero più lunghe, a volte ha mancato casi limite, cosa prevedibile per un modello open da 24B. Questo approccio è ideale per demo leggere di reasoning o applicazioni on-device con chain-of-thought, senza dipendere da API cloud.

Esecuzione di Magistral Small con vLLM

In questa sezione spiegherò come predisporre un’istanza GPU potente su RunPod, distribuire il modello Magistral di Mistral usando vLLM ed esporre un’API compatibile con OpenAI per inferenza sia locale che remota.

Passaggio 1: Configura l’ambiente RunPod 

Prima di lanciare il modello, assicurati che il tuo account RunPod sia configurato:

• Accedi a RunPod.io e configura la fatturazione.
• Aggiungi almeno 10 $ al tuo saldo per assicurarti di poter eseguire un’istanza con GPU A100 per la durata di questo progetto.

Passaggio 2: Distribuisci un pod con GPU A100

Ora predisponiamo un pod in grado di ospitare il modello. Per configurare un pod, segui questi passaggi:

• Vai alla sezione Pods e seleziona A100 SXM GPU con 80 GB di VRAM. Per questo progetto useremo una sola A100.

• Vai alla sezione “Deploy a Pod” e clicca su Edit Template.

• Ora aumenta il container disk e il volume disk a 60 GB e clicca su Set Overrides.

• Quindi clicca su Deploy On-Demand, e il tuo pod verrà distribuito. Il pod attivo comparirà nella sezione pods, insieme a tutte le configurazioni impostate. Attendi qualche secondo finché il pulsante Connect non diventa attivo.

Passaggio 3: Connettiti al tuo pod

Quando il pulsante Connect diventa cliccabile, cliccalo. Vedrai diverse opzioni di connessione — puoi:

• Aprire un terminale JupyterLab per eseguire comandi shell o un notebook Jupyter (consigliato).
• Oppure usare porte SSH o HTTP se vuoi il controllo remoto.

Nota: aspetta di vedere un pallino verde 🟢 con la dicitura Ready sotto Jupyter Lab.

Clicca su Jupyter Lab — verrai reindirizzato a un’altra finestra con le opzioni per creare un nuovo notebook Jupyter. Apri un nuovo terminale o crea un nuovo file Python.

Passaggio 4: Installa vLLM e le librerie necessarie

Dal terminale o dal notebook Jupyter dentro il tuo pod, installa vLLM e le sue dipendenze. 

pip install -U vllm --pre --extra-index-url https://wheels.vllm.ai/nightly
pip install gradioOfferto da

Assicurati anche di eseguire mistral_common >= 1.6.0 lanciando:

python -c "import mistral_common; print(mistral_common.__version__)"Offerto da

Passaggio 5: Metti in serving il modello

Ora mettiamo in serving il modello. Clicca sul segno “+” nell’angolo in alto a sinistra e seleziona il terminale tra le opzioni, quindi esegui il seguente comando:

vllm serve mistralai/Magistral-Small-2506 \
  --tokenizer_mode mistral \
  --config_format mistral \
  --load_format mistral \
  --tool-call-parser mistral \
  --enable-auto-tool-choiceOfferto da

Lascia questo terminale in esecuzione perché questo comando avvia il modello Magistral Small con vLLM e lo rende disponibile su un endpoint API veloce e compatibile con OpenAI (http://localhost:8000/v1). Ecco una spiegazione di ogni flag:

Passaggio 6: Debug della logica difettosa con Magistral e vLLM

Ora costruiremo una demo in cui chiediamo a Magistral di eseguire il debug di una logica o una dimostrazione matematica difettosa. Il modello produrrà un dettagliato monologo interno racchiuso nei tag <think> e un riepilogo finale.

Passaggio 6.1: Inizializza il client OpenAI e il system prompt

Iniziamo impostando gli import e inizializzando il client OpenAI nel Jupyter Notebook. Poi impostiamo il system prompt di Magistral come suggerito nell’articolo originale.

import gradio as gr
from openai import OpenAI
import re
import time
client = OpenAI(api_key="EMPTY", base_url="http://localhost:8000/v1")
SYSTEM_PROMPT = """<s>[SYSTEM_PROMPT]system_prompt
A user will ask you to solve a task. You should first draft your thinking process (inner monologue) until you have derived the final answer. Afterwards, write a self-contained summary of your thoughts.
<think>
Your thoughts or draft, like working through an exercise on scratch paper.
</think>
Here, provide a concise summary that reflects your reasoning and presents a clear final answer to the user.
Problem:
[/SYSTEM_PROMPT]"""Offerto da

Il SYSTEM_PROMPT definisce il formato strutturato di risposta del modello:

• Si chiede al modello di generare prima una traccia <think> (come un monologo interno),
• Poi produrre un riepilogo finale dopo il tag </think>.

Passaggio 6.2: Esegui lo streaming dell’output del modello e consenti interruzioni

Successivamente gestiamo lo streaming dell’output del modello impostando temperature, top_p e max_tokens come suggerito nel blog originale su Magistral.

# Streaming logic with stop control
def debug_faulty_logic_stream(faulty_proof, stop_signal):
    stop_signal["stop"] = False 
    messages = [
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": f"Here is a flawed logic or math proof. Can you debug it step-by-step?\n\n{faulty_proof}"}
    ]
    try:
        response = client.chat.completions.create(
            model="mistralai/Magistral-Small-2506",
            messages=messages,
            stream=True,
            temperature=0.7,
            top_p=0.95,
            max_tokens=2048
        )
        buffer = ""
        for chunk in response:
            if stop_signal.get("stop"):
                break
            delta = chunk.choices[0].delta
            if hasattr(delta, "content") and delta.content:
                buffer += delta.content
                filtered = re.sub(r"<think>.*?</think>", "", buffer, flags=re.DOTALL).strip()
                yield filtered
            time.sleep(0.02)
    except Exception as e:
        yield f"Error: {str(e)}"
# Set stop flag when stop button is clicked
def stop_streaming(stop_signal):
    stop_signal["stop"] = True
    return gr.Textbox.update(value="Stopped.")Offerto da

Lo snippet sopra gestisce lo streaming live dell’output token-by-token dal modello. stop_signal permette agli utenti di interrompere lo streaming cliccando un pulsante "Stop".

Il buffer accumula tutto il contenuto, ma restituisce solo il riepilogo (escludendo il tag <think>) tramite un’espressione regolare. In caso di errore (ad es., problema di rete), ritorna il messaggio di errore.

Passaggio 6.3: Costruisci la UI in Gradio

Mettiamo tutto insieme con una semplice app Gradio che consente agli utenti di inserire la loro logica o dimostrazione difettosa e inviarla al modello per il ragionamento.

with gr.Blocks() as demo:
    gr.Markdown("## Chain-of-Logic Debugger (Streaming via Magistral + vLLM)")

    input_box = gr.Textbox(
        label="Paste Your Faulty Logic or Proof",
        lines=8,
        placeholder="e.g., Assume x = y, then x² = xy..."
    )
    output_box = gr.Textbox(label="Corrected Reasoning (Streaming Output)")

    submit_btn = gr.Button("Submit")
    stop_btn = gr.Button("Stop")

    stop_flag = gr.State({"stop": False})

    submit_btn.click(
        fn=debug_faulty_logic_stream,
        inputs=[input_box, stop_flag], 
        outputs=output_box
    )

    stop_btn.click(
        fn=stop_streaming,
        inputs=stop_flag,
        outputs=output_box
    )

if __name__ == "__main__":
    demo.launch(share=True, inbrowser=True, debug=True)Offerto da

Il codice sopra crea una semplice interfaccia Gradio con:

• Una casella di testo per incollare la logica difettosa.
• Una casella di output live che si aggiorna mentre arrivano i token.
• Un pulsante Submit per avviare il debugger e un pulsante Stop per interromperlo.

Usa gr.State per tenere traccia dell’intenzione dell’utente di interrompere lo streaming. Quindi il metodo launch() esegue l’app in locale e la apre nel browser. Ecco l’input che ho provato:

Assume x = y. Then, x² = xy. Subtracting both sides gives x² - y² = xy - y². So, (x+y)(x−y) = y(x−y). Cancelling x−y gives x+y = y. But since x = y, this means 2y = y → 2 = 1.Offerto da

Puoi passare al terminale già in esecuzione in cui vLLM sta servendo per controllare i log sull’uso della KV cache, nonché l’aumento del tasso di hit quando il modello sta restituendo output.

Rispetto a Ollama, vLLM è risultato sensibilmente più veloce e stabile durante l’inferenza. Lo streaming è fluido e gli output per lo più ben strutturati. Detto ciò, a volte il modello ripeteva pensieri nelle sezioni <think>, probabilmente per la natura della decodifica autoregressiva senza penalità di campionamento.

Ollama vs. vLLM per eseguire Magistral Small 

Mentre Ollama supporta una versione quantizzata a 4 bit del modello per un’inferenza efficiente on-device, vLLM richiede l’accelerazione GPU, risultando leggermente più costoso da eseguire (circa 5 $ per questo progetto). Il modello Magistral quantizzato a 4 bit richiede circa 14 GB di memoria, che può essere ospitato su una singola RTX 4090 o anche su un MacBook con 32 GB di RAM. Tuttavia, l’inferenza può essere lenta, fino a 4 minuti per risposta a causa del compute limitato.

Al contrario, vLLM offre un’inferenza notevolmente più rapida (in genere meno di un minuto per risposta) quando distribuito su GPU ad alte prestazioni come A100 SXM, rendendolo più adatto per app reattive o deployment su scala.

Se stai solo sperimentando e hai risorse locali, Ollama è ideale per i bassi costi di setup. Ma per prestazioni di livello produttivo o carichi più grandi, vLLM è la scelta consigliata. Tieni presente che, sebbene vLLM possa girare in locale, richiede comunque una GPU capace.

Conclusione

In questo tutorial abbiamo usato Magistral Small — un LLM orientato al reasoning di Mistral — per creare un debugger logico passo dopo passo. Abbiamo distribuito il modello in locale sia con Ollama per test rapidi on-device sia con vLLM per inferenza GPU ad alto throughput con API compatibili con OpenAI. Abbiamo anche testato le capacità di reasoning del modello con un’applicazione Gradio. Che tu stia facendo debug di logiche difettose o costruendo strumenti di AI per il ragionamento, Magistral Small può essere una buona soluzione.