Magistral Small: vLLM ve Ollama Üzerine Demo Projeli Bir Kılavuz

Mistral, ilk akıl yürütme modelini, Magistral’i yayımladı. İki varyantı bulunuyor: Magistral Small (açık ağırlık) ve Magistral Medium (kapalı model).

Bu blogda odak noktam Magistral Small olacak: yapısal mantık gerektiren görevler, çok dilli anlama ve izlenebilir açıklamalar sunma becerisi için tasarlanmış açık ağırlıklı bir akıl yürütme modeli. vLLM gibi yüksek aktarım hızlı çıkarım motorları veya Ollama gibi kullanımı kolay araçlarla eşleştirildiğinde, bozuk mantığı ayıklamak ve akıl yürütme görevleri için harika bir araca dönüşür.

Bu eğitimde, adım adım şunları nasıl yapacağımı açıklayacağım:

• Magistral Small’ı (24B) vLLM ve Ollama ile çalıştırmak
• Şeffaf, adım adım akıl yürütme ile mantık ayıklayan bir demo proje kurmak

Okurlarımızı yapay zekâdaki en son gelişmelerden haberdar etmek için, haftanın önemli haberlerini özetleyen ve ücretsiz olan Cuma bültenimiz The Median’ı gönderiyoruz. Abone olun; haftada sadece birkaç dakikada güncel kalın:

Mistral'in Magistral'i Nedir?

Magistral, adım adım mantık, çok dilli doğruluk ve izlenebilir çıktılar için geliştirilmiş Mistral AI’ın ilk özel akıl yürütme modelidir. İki varyantla ikili sürüm olarak gelir:

• Magistral Small (24B): Apache 2.0 altında sunulan, yerel dağıtım için uygun, tamamen açık kaynaklı bir modeldir. 
• Magistral Medium: Mistral’in Le Chat’i, SageMaker ve diğer kurumsal bulutlar üzerinden sunulan daha güçlü, kurumsal sınıf bir modeldir.

Kaynak: Mistral

Açık model olan ve odaklanacağımız Magistral Small, 128K bağlam penceresini destekler (stabil performans için 40K önerilir). İnce ayar ile Magistral Medium izleri üzerinde denetimli olarak ve pekiştirmeli öğrenme kullanılarak eğitilmiştir.

Magistral Small’ı Ollama ile Yerelde Nasıl Kurup Çalıştırırsınız

Bu bölümde, Mistral’ın Magistral modelinde çıkarımı Ollama kullanarak yerelde gerçekleştireceğiz. Bu modelin yaklaşık 14 GB alan gerektirdiğini ve kantize edildikten sonra tek bir RTX 4090’a veya 32 GB RAM’li bir MacBook’a sığabileceğini unutmayın. Bu demoyu M3 MacBook Pro’da çalıştırdım.

Adım 1: Modeli Ollama ile çekin

macOS, Windows veya Linux için Ollama’yı şu adresten indirin: https://ollama.com/download.

Yükleyici talimatlarını izleyin ve kurulumdan sonra terminalde şunu çalıştırarak doğrulayın:

ollama --versionAltyapı:

Ardından aşağıdaki kodu çalıştırarak Magistral modelini çekin:

ollama pull magistralAltyapı:

Bu işlem, Magistral modelini yerel makinenize indirecektir. Not: Model yaklaşık 14 GB olduğu için biraz zaman alacaktır.

Adım 2: Bağımlılıkları yükleyin

Gerekli tüm bağımlılıkları yükleyerek başlayalım.

pip install ollama
pip install requestsAltyapı:

Bağımlılıkları kurduğumuza göre, çıkarım çalıştırmaya hazırız.

Adım 3: Yapılandırılmış bir istem şablonu oluşturun

Şimdi, modelin düşünme sürecini yönlendiren bir istem şablonu yapısı kuruyoruz (orijinal Magistral makalesinde belirtildiği gibi).

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]
"""Altyapı:

Yukarıdaki fonksiyon, Magistral’ı şu konularda yönlendiren biçimlendirilmiş bir istem döndürür:

• <think>...</think> etiketlerini kullanarak adım adım düşünmek
• İçsel monologdan sonra net bir sonuç sunmak
• Doğal bir açıklama için “hata ayıklama”dan bahsetmeyi yok saymak

Bu yapı, araç destekli istemlerle eğitilmiş Magistral gibi modeller için önemlidir. Aynı sistem istemi yapısı hem matematiksel hem de kodlama problemleri için kullanılabilir.

Adım 4: Çıkarımı akışla yönetin ve Gradio arayüzünü oluşturun

Bu adımda, Magistral modelinin çıktısını Ollama’nın yerel API’sini kullanarak gerçek zamanlı olarak akıtıyoruz. İzlenebilir, adım adım akıl yürütme ile hatalı mantığı ayıklamaya odaklandığımız için, kullanıcının modelin sonuca nasıl ulaştığını görmesi önemlidir. Son olarak açıklamayı sade bir Gradio arayüzünde gösteriyoruz.

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)Altyapı:

Burada neler olduğunun özeti:

• build_prompt() adlı yeniden kullanılabilir bir fonksiyonla, kullanıcı girdisini modele <think> akıl yürütme etiketleriyle rehberlik eden yapılandırılmış bir isteme sararak başlıyoruz.
• Kullanıcı hatalı bir ispat veya mantık ifadesi gönderdiğinde, call_ollama_stream() fonksiyonu istemi streaming POST isteğiyle localhost:11434 adresindeki Ollama’nın HTTP API’sine gönderir.
• Fonksiyon, requests.iter_lines() kullanarak satır satır akış yanıtlarını dinler. Alınan her satır için, JSON yükünden response alanını çıkarır ve bir metin arabelleğine ekler.
• Tüm satırlar toplandıktan sonra, tam model yanıtı döndürülür ve Gradio arayüzünde gösterilir.

Denediğim girdi şuydu:

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.Altyapı:

M3 MacBook Pro’da yaptığım testlerde, model basit mantık zincirlerini ve matematik ispatlarını oldukça iyi ele aldı. Ancak, daha derin akıl yürütme görevlerinde veya daha uzun düşünce zincirlerinde zaman zaman uç durumları kaçırdı; bu da 24B açık bir modelden beklenebilir. Bu yaklaşım, bulut API’lerine başvurmadan, hafif akıl yürütme demoları veya cihaz üzerinde düşünce zinciri uygulamaları için idealdir.

Magistral Small’ı vLLM ile Çalıştırma

Bu bölümde, RunPod üzerinde güçlü bir GPU örneği sağlamayı, Mistral’ın Magistral modelini vLLM ile dağıtmayı ve hem yerel hem de uzaktan çıkarım için OpenAI uyumlu bir API sunmayı anlatacağım.

Adım 1: RunPod ortamınızı ayarlayın 

Modeli başlatmadan önce RunPod hesabınızın ayarlı olduğundan emin olun:

• RunPod.io’ya giriş yapın ve faturalandırmayı yapılandırın.
• Bu proje boyunca tek bir A100 GPU örneğini çalıştırabildiğinizden emin olmak için bakiyenize en az 10 $ ekleyin.

Adım 2: A100 GPU’lu bir pod dağıtın

Şimdi modeli barındırabilecek bir pod tedarik edelim. Pod kurmak için şu adımları izleyin:

• Pods bölümüne gidin ve 80 GB VRAM’li A100 SXM GPU’yu seçin. Bu projede yalnızca tek bir A100 GPU kullanacağız.

• “Deploy a Pod” bölümüne gidin ve Edit Template’e tıklayın.

• Şimdi, container disk ve volume diski 60 GB’a çıkarın ve Set Overrides’e tıklayın.

• Sonra Deploy On-Demand’e tıklayın; pod’unuz dağıtılacaktır. Dağıtılan pod, ayarlanan tüm yapılandırmalarla birlikte pods bölümünde görünecektir. Connect düğmesi etkin hale gelene kadar birkaç saniye bekleyin.

Adım 3: Pod’unuza bağlanın

Connect düğmesi tıklanabilir hale geldiğinde, tıklayın. Birden fazla bağlantı seçeneği göreceksiniz—şunlardan birini yapabilirsiniz:

• Kabuk komutları çalıştırmak veya bir Jupyter defteri kullanmak için bir JupyterLab terminali açın (önerilir).
• Ya da uzaktan kontrol istiyorsanız SSH veya HTTP portlarını kullanın.

Not: Jupyter Lab altında Ready işaretiyle yeşil bir nokta 🟢 görünene kadar bekleyin.

Jupyter Lab’e tıklayın—yeni bir Jupyter defteri oluşturma seçeneklerinin bulunduğu başka bir pencereye yönlendirileceksiniz. Yeni bir terminal açın veya yeni bir Python dosyası oluşturun.

Adım 4: vLLM’i ve gerekli kütüphaneleri yükleyin

Pod’unuz içindeki terminalde veya Jupyter Notebook’ta vLLM’i ve bağımlılıklarını yükleyin. 

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

Ayrıca, aşağıdakini çalıştırarak mistral_common >= 1.6.0 kullandığınızdan emin olun:

python -c "import mistral_common; print(mistral_common.__version__)"Altyapı:

Adım 5: Modeli servis edin

Şimdi, modeli servis edelim. Sol üst köşedeki “+” işaretine tıklayın ve seçeneklerden terminali seçin, ardından şu komutu çalıştırın:

vllm serve mistralai/Magistral-Small-2506 \
  --tokenizer_mode mistral \
  --config_format mistral \
  --load_format mistral \
  --tool-call-parser mistral \
  --enable-auto-tool-choiceAltyapı:

Bu terminali çalışır durumda bırakın; bu komut Magistral Small modelini vLLM kullanarak başlatır ve hızlı, OpenAI uyumlu bir API uç noktasında (http://localhost:8000/v1) kullanılabilir hale getirir. İşte her bayrağın açıklaması:

Adım 6: Magistral ve vLLM ile hatalı mantığı ayıklama

Şimdi, Magistral’dan hatalı bir mantık veya matematik ispatını ayıklamasını isteyeceğimiz bir demo oluşturacağız. Model, <think> etiketlerine sarılmış ayrıntılı bir iç monolog ve ardından nihai bir özet çıktısı verecek.

Adım 6.1: OpenAI istemcisini ve sistem istemini başlatın

Jupyter Notebook’ta içe aktarmaları ayarlayıp OpenAI istemcisini başlatarak başlıyoruz. Ardından, orijinal Magistral makalesinde önerildiği gibi Magistral’ın sistem istemini kuruyoruz.

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]"""Altyapı:

SYSTEM_PROMPT, modelin nasıl yanıt vermesi gerektiğine dair yapılandırılmış formatı tanımlar:

• Modelin önce bir <think> izi (iç monolog gibi) üretmesi istenir,
• Ardından </think> etiketinden sonra nihai bir özet üretmesi beklenir.

Adım 6.2: Model çıktısını akışla iletin ve kesintilere izin verin

Sonraki adımda, gerekli temperature, top_p ve max_tokens değerlerini orijinal Magistral blogunda önerildiği şekilde ayarlayarak model çıktısının akışını yönetiyoruz.

# 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.")Altyapı:

Yukarıdaki kod parçası, modelden canlı, token token çıktı akışını yönetir. stop_signal, kullanıcının “Durdur” düğmesine tıklayarak akışı kesmesine olanak tanır.

Arabellek tüm içeriği biriktirirken, normal ifade kullanarak yalnızca özeti (<think> etiketi hariç) verir. Herhangi bir hata oluşursa (ör. ağ sorunu), hata mesajını döndürür.

Adım 6.3: Gradio arayüzünü oluşturun

Bunu, kullanıcıların hatalı mantık veya ispatlarını ekleyip modele akıl yürütme için göndermesine olanak tanıyan basit bir Gradio uygulamasıyla bir araya getirelim.

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)Altyapı:

Yukarıdaki kod, aşağıdakilerle basit bir Gradio arayüzü oluşturur:

• Kullanıcıların hatalı mantığı yapıştıracağı bir metin girişi kutusu.
• Tokenlar akarken güncellenen canlı bir çıktı kutusu.
• Bir Submit düğmesi (ayıklayıcıyı başlatmak için) ve bir Stop düğmesi (durdurmak için).

Kullanıcının akış sürecini kesmek isteyip istemediğini takip etmek için gr.State kullanır. Ardından launch() yöntemi uygulamayı yerelde çalıştırır ve tarayıcınızda açar. Denediğim girdi şuydu:

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.Altyapı:

vLLM’in servis verdiği hâlihazırda çalışan terminale geçerek, model herhangi bir çıktı döndürürken KV önbellek kullanımının günlüklerini ve isabet oranının yükseldiğini kontrol edebilirsiniz.

Ollama ile karşılaştırıldığında, vLLM çıkarım sırasında fark edilir derecede daha hızlı ve daha kararlıydı. Akış pürüzsüz hissettirdi ve çıktılar çoğunlukla iyi yapılandırılmıştı. Bununla birlikte, model bazen <think> bölümleri içinde düşünceleri tekrarladı; bu muhtemelen örnekleme cezaları olmadan otoregresif çözümlemenin doğasından kaynaklanıyor.

Magistral Small’ı Çalıştırmak İçin Ollama vs. vLLM 

Ollama, verimli cihaz üstü çıkarım için modelin kantize edilmiş 4-bit sürümünü desteklerken, vLLM GPU hızlandırma gerektirir; bu da çalıştırmayı biraz daha maliyetli kılar (bu proje için yaklaşık 5 $). 4-bit kantize Magistral modeli yaklaşık 14 GB bellek gerektirir; tek bir RTX 4090 GPU’da veya hatta 32 GB RAM’li bir MacBook’ta barındırılabilir. Ancak, sınırlı hesaplama gücü nedeniyle çıkarım yavaş olabilir; yanıt başına 4 dakikaya kadar sürebilir.

Buna karşılık, vLLM, A100 SXM gibi yüksek performanslı GPU’larda dağıtıldığında belirgin şekilde daha hızlı çıkarım sunar (kabaca yanıt başına bir dakikadan az); bu da onu duyarlı uygulamalar veya ölçekli dağıtımlar için daha uygun kılar.

Sadece denemeler yapıyor ve yerel kaynaklara sahipseniz, düşük kurulum maliyeti nedeniyle Ollama idealdir. Ancak, üretim düzeyinde performans veya daha büyük iş yükleri için vLLM önerilir. vLLM’in yerelde çalıştırılabilse de yine de yetenekli bir GPU gerektirdiğini unutmayın.

Sonuç

Bu eğitimde, Mistral’ın akıl yürütmeyi önceleyen LLM’i Magistral Small’ı kullanarak adım adım mantık ayıklayıcı oluşturduk. Modeli, hızlı cihaz üstü testler için Ollama ve OpenAI uyumlu API’lerle yüksek aktarım hızlı GPU çıkarımı için vLLM kullanarak yerelde dağıttık. Ayrıca, modelin akıl yürütme yeteneklerini bir Gradio uygulamasıyla test ettik. Hatalı mantığı ayıklıyor veya akıl yürütme odaklı yapay zekâ araçları geliştiriyorsanız, Magistral Small iyi bir çözüm olabilir.