Magistral Small: Hướng dẫn kèm dự án demo trên vLLM và Ollama

Mistral đã ra mắt mô hình suy luận đầu tiên của mình, Magistral, với hai biến thể: Magistral Small (mở trọng số) và Magistral Medium (đóng).

Bài viết này tập trung vào Magistral Small, một mô hình suy luận mở trọng số được thiết kế cho các tác vụ đòi hỏi logic có cấu trúc, hiểu đa ngôn ngữ và khả năng cung cấp lời giải thích có thể truy vết. Khi kết hợp với các engine suy luận thông lượng cao như vLLM hoặc công cụ dễ dùng như Ollama, đây là một công cụ tuyệt vời để gỡ lỗi logic sai và các tác vụ suy luận.

Trong hướng dẫn này, tôi sẽ trình bày từng bước cách:

• Chạy Magistral Small (24B) với vLLM và Ollama
• Xây dựng một dự án demo gỡ lỗi logic với suy luận minh bạch theo từng bước

Chúng tôi cập nhật cho độc giả những điều mới nhất về AI qua The Median, bản tin miễn phí vào thứ Sáu, tóm lược những câu chuyện quan trọng trong tuần. Đăng ký để luôn bắt kịp chỉ trong vài phút mỗi tuần:

Magistral của Mistral là gì?

Magistral là mô hình suy luận chuyên dụng đầu tiên của Mistral AI, được xây dựng cho logic theo từng bước, độ chính xác đa ngôn ngữ và đầu ra có thể truy vết. Đây là một mô hình phát hành kép với hai biến thể:

• Magistral Small (24B): Hoàn toàn mã nguồn mở, theo giấy phép Apache 2.0 và phù hợp để triển khai cục bộ. 
• Magistral Medium: Mô hình mạnh hơn cấp doanh nghiệp, truy cập qua Le Chat của Mistral, SageMaker và các đám mây doanh nghiệp khác.

Nguồn: Mistral

Magistral Small, mô hình mở mà chúng ta tập trung, hỗ trợ cửa sổ ngữ cảnh 128K (khuyến nghị 40K để hiệu năng ổn định). Mô hình được huấn luyện bằng fine-tuning có giám sát trên các vết suy luận của Magistral Medium và học tăng cường.

Cách thiết lập và chạy Magistral Small cục bộ với Ollama

Trong phần này, chúng ta sẽ thực hiện suy luận trên mô hình Magistral của Mistral cục bộ bằng Ollama. Lưu ý mô hình này cần khoảng 14GB dung lượng và có thể chạy trên một RTX 4090 đơn hoặc MacBook RAM 32GB sau khi được lượng tử hóa. Tôi chạy bản demo này trên MacBook Pro M3.

Bước 1: Kéo mô hình qua Ollama

Tải Ollama cho macOS, Windows, hoặc Linux từ: https://ollama.com/download.

Làm theo hướng dẫn cài đặt, và sau khi cài xong, xác minh bằng cách chạy lệnh sau trong terminal:

ollama --versionĐược hỗ trợ bởi

Tiếp theo, kéo mô hình Magistral bằng cách chạy lệnh sau:

ollama pull magistralĐược hỗ trợ bởi

Lệnh này sẽ kéo mô hình Magistral về máy cục bộ của bạn. Lưu ý: sẽ mất thời gian do mô hình khoảng 14 GB.

Bước 2: Cài đặt phụ thuộc

Bắt đầu cài đặt tất cả phụ thuộc cần thiết.

pip install ollama
pip install requestsĐược hỗ trợ bởi

Sau khi cài xong phụ thuộc, chúng ta sẵn sàng chạy suy luận.

Bước 3: Tạo mẫu prompt có cấu trúc

Bây giờ, ta thiết lập cấu trúc mẫu prompt (như nêu trong bài báo Magistral gốc) để định hướng quá trình suy nghĩ của mô hình.

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]
"""Được hỗ trợ bởi

Hàm trên trả về một prompt được định dạng để hướng dẫn Magistral:

• Suy nghĩ theo từng bước bằng thẻ <think>...</think>
• Đưa ra kết luận rõ ràng sau độc thoại nội tâm
• Bỏ qua mọi đề cập đến “gỡ lỗi” để lời giải thích tự nhiên

Cấu trúc này quan trọng với các mô hình như Magistral đã được huấn luyện với prompt có tăng cường công cụ. Cùng một cấu trúc system prompt cũng có thể dùng cho cả bài toán toán học và mã nguồn.

Bước 4: Stream suy luận và xây dựng UI Gradio

Trong bước này, chúng ta stream đầu ra của mô hình Magistral theo thời gian thực qua API cục bộ của Ollama. Vì tập trung gỡ lỗi logic sai với suy luận minh bạch từng bước, việc người dùng thấy cách mô hình đi đến kết luận là rất quan trọng. Cuối cùng, chúng ta hiển thị lời giải thích qua giao diện Gradio gọn gàng.

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)Được hỗ trợ bởi

Tóm lược những gì đang diễn ra:

• Bắt đầu với hàm tái sử dụng build_prompt() để bọc đầu vào người dùng thành prompt có cấu trúc, hướng dẫn mô hình với thẻ suy luận <think>.
• Khi người dùng gửi một chứng minh hoặc mệnh đề logic sai, hàm call_ollama_stream() gửi prompt tới API HTTP của Ollama tại localhost:11434 bằng yêu cầu POST dạng stream.
• Hàm lắng nghe phản hồi stream theo từng dòng bằng requests.iter_lines(). Với mỗi dòng nhận được, nó trích trường response từ payload JSON và nối vào bộ đệm văn bản.
• Khi thu thập xong tất cả các dòng, phản hồi đầy đủ của mô hình được trả về và hiển thị trong UI Gradio.

Đây là đầu vào tôi đã thử:

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.Được hỗ trợ bởi

Trong thử nghiệm trên MacBook Pro M3, mô hình xử lý khá tốt các chuỗi logic đơn giản và chứng minh toán học. Tuy nhiên, với các tác vụ suy luận sâu hoặc chuỗi suy nghĩ dài hơn, đôi khi mô hình bỏ sót các trường hợp biên—điều có thể kỳ vọng ở một mô hình mở 24B. Cách làm này lý tưởng cho các bản demo suy luận gọn nhẹ hoặc ứng dụng chuỗi suy nghĩ trên thiết bị, không phụ thuộc vào API đám mây.

Chạy Magistral Small với vLLM

Trong phần này, tôi sẽ giải thích cách cung cấp một instance GPU mạnh trên RunPod, triển khai mô hình Magistral của Mistral bằng vLLM, và mở API tương thích OpenAI cho suy luận cục bộ và từ xa.

Bước 1: Thiết lập môi trường RunPod 

Trước khi khởi chạy mô hình, hãy đảm bảo tài khoản RunPod của bạn đã được thiết lập:

• Đăng nhập vào RunPod.io và cấu hình thanh toán.
• Nạp tối thiểu $10 vào số dư để có thể chạy một instance GPU A100 trong suốt dự án này.

Bước 2: Triển khai pod với GPU A100

Bây giờ, hãy cung cấp một pod có khả năng lưu trữ mô hình. Để thiết lập pod, làm theo các bước sau:

• Vào mục Pods và chọn A100 SXM GPU với 80GB VRAM. Trong dự án này, chúng ta chỉ dùng một GPU A100.

• Vào phần “Deploy a Pod” và bấm Edit Template.

• Tăng dung lượng container disk và volume disk lên 60 GB rồi bấm Set Overrides.

• Tiếp theo, bấm Deploy On-Demand, và pod của bạn sẽ được triển khai. Pod đã triển khai sẽ xuất hiện trong mục pods cùng với mọi cấu hình đã đặt. Chờ vài giây cho đến khi nút Connect kích hoạt.

Bước 3: Kết nối với pod của bạn

Khi nút Connect có thể bấm, hãy bấm vào. Bạn sẽ thấy nhiều tùy chọn kết nối—bạn có thể:

• Mở terminal JupyterLab để chạy lệnh shell hoặc notebook Jupyter (khuyến nghị).
• Hoặc dùng SSH hoặc cổng HTTP nếu bạn muốn điều khiển từ xa.

Lưu ý: Hãy chờ đến khi thấy chấm xanh 🟢 kèm trạng thái Ready dưới Jupyter Lab.

Bấm vào Jupyter Lab—bạn sẽ được chuyển đến cửa sổ khác với tùy chọn tạo notebook Jupyter mới. Mở terminal mới hoặc tạo file Python mới.

Bước 4: Cài đặt vLLM và thư viện cần thiết

Trong terminal hoặc Jupyter Notebook bên trong pod của bạn, cài vLLM và các phụ thuộc.

pip install -U vllm --pre --extra-index-url https://wheels.vllm.ai/nightly
pip install gradioĐược hỗ trợ bởi

Ngoài ra, đảm bảo bạn đang chạy mistral_common >= 1.6.0 bằng cách chạy:

python -c "import mistral_common; print(mistral_common.__version__)"Được hỗ trợ bởi

Bước 5: Phục vụ mô hình

Bây giờ, hãy phục vụ mô hình. Bấm dấu “+” ở góc trên bên trái và chọn terminal, sau đó chạy lệnh sau:

vllm serve mistralai/Magistral-Small-2506 \
  --tokenizer_mode mistral \
  --config_format mistral \
  --load_format mistral \
  --tool-call-parser mistral \
  --enable-auto-tool-choiceĐược hỗ trợ bởi

Giữ terminal này chạy vì lệnh này khởi chạy mô hình Magistral Small bằng vLLM và cung cấp một endpoint API tương thích OpenAI, tốc độ cao (http://localhost:8000/v1). Dưới đây là phần giải thích cho từng cờ:

Bước 6: Gỡ lỗi logic sai với Magistral và vLLM

Chúng ta sẽ xây dựng một demo yêu cầu Magistral gỡ lỗi một logic hoặc chứng minh toán học sai. Mô hình sẽ xuất ra độc thoại nội tâm chi tiết trong thẻ <think> và phần tóm tắt cuối.

Bước 6.1: Khởi tạo OpenAI client và system prompt

Bắt đầu bằng cách thiết lập import và khởi tạo OpenAI client trong Jupyter Notebook. Sau đó đặt system prompt của Magistral như gợi ý trong bài báo gốc.

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]"""Được hỗ trợ bởi

SYSTEM_PROMPT định nghĩa định dạng có cấu trúc về cách mô hình phản hồi:

• Mô hình được yêu cầu tạo một vết <think> trước (như độc thoại nội tâm),
• Sau đó tạo phần tóm tắt cuối sau thẻ </think>.

Bước 6.2: Stream đầu ra mô hình và cho phép ngắt

Tiếp theo, chúng ta xử lý stream đầu ra mô hình bằng cách đặt temperature, top_p, và max_tokens như gợi ý trong blog gốc của 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.")Được hỗ trợ bởi

Đoạn mã trên xử lý stream đầu ra trực tiếp từng token từ mô hình. stop_signal cho phép người dùng ngắt stream bằng cách bấm nút "Stop".

Bộ đệm tích lũy toàn bộ nội dung, nhưng chỉ trả về phần tóm tắt (loại bỏ thẻ <think>) bằng biểu thức chính quy. Nếu có lỗi (ví dụ lỗi mạng), sẽ trả về thông báo lỗi.

Bước 6.3: Xây dựng UI Gradio

Ghép lại thành một ứng dụng Gradio đơn giản cho phép người dùng thêm logic hoặc chứng minh sai và gửi đến mô hình để suy luận.

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)Được hỗ trợ bởi

Đoạn mã trên tạo giao diện Gradio đơn giản với:

• Ô nhập văn bản để người dùng dán logic sai.
• Ô đầu ra trực tiếp cập nhật khi token stream về.
• Submit để bắt đầu gỡ lỗi, và Stop để dừng.

Ứng dụng dùng gr.State để theo dõi việc người dùng có muốn ngắt quá trình stream hay không. Sau đó, phương thức launch() chạy ứng dụng cục bộ và mở trong trình duyệt. Đây là đầu vào tôi đã thử:

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.Được hỗ trợ bởi

Bạn có thể chuyển sang terminal đang chạy vLLM để xem log sử dụng KV cache, cũng như tỷ lệ hit tăng lên khi mô hình trả về đầu ra.

So với Ollama, vLLM nhanh và ổn định hơn thấy rõ trong quá trình suy luận. Stream mượt, và đầu ra hầu hết có cấu trúc tốt. Dù vậy, đôi khi mô hình lặp ý trong phần <think>, có lẽ do đặc tính giải mã tự hồi quy không có phạt sampling.

Ollama vs. vLLM để chạy Magistral Small 

Trong khi Ollama hỗ trợ phiên bản lượng tử hóa 4-bit của mô hình để suy luận hiệu quả trên thiết bị, vLLM yêu cầu tăng tốc GPU, khiến chi phí chạy cao hơn một chút (khoảng $5 cho dự án này). Mô hình Magistral 4-bit cần khoảng 14GB bộ nhớ, có thể chạy trên một GPU RTX 4090 hoặc thậm chí MacBook với RAM 32GB. Tuy nhiên, suy luận có thể chậm, lên đến 4 phút mỗi phản hồi do hạn chế tính toán.

Ngược lại, vLLM cho suy luận nhanh hơn đáng kể (thường dưới một phút mỗi phản hồi) khi triển khai trên GPU hiệu năng cao như A100 SXM, phù hợp hơn cho ứng dụng cần phản hồi nhanh hoặc triển khai quy mô.

Nếu bạn chỉ thử nghiệm và có tài nguyên cục bộ, Ollama là lựa chọn lý tưởng nhờ chi phí thiết lập thấp. Nhưng với hiệu năng cấp sản xuất hoặc khối lượng công việc lớn, vLLM là khuyến nghị. Lưu ý rằng vLLM có thể chạy cục bộ nhưng vẫn cần GPU đủ mạnh.

Kết luận

Trong hướng dẫn này, chúng ta dùng Magistral Small—một LLM ưu tiên suy luận từ Mistral—để xây dựng trình gỡ lỗi logic theo từng bước. Chúng ta triển khai mô hình cục bộ bằng cả Ollama cho thử nghiệm nhanh trên thiết bị và vLLM cho suy luận GPU thông lượng cao với API tương thích OpenAI. Chúng ta cũng kiểm thử khả năng suy luận của mô hình với ứng dụng Gradio. Dù bạn đang gỡ lỗi logic sai hay xây dựng công cụ AI suy luận, Magistral Small có thể là một lựa chọn tốt.