Biċċiet ta' ħsieb: qari tar-raġunar tal-mudell
F'din il-paġna
Lezzjon miktuba mill-ġdid fit-2 ta’ Novembru 2026 ibbażata fuq it-taqsima Handling thinking chunks tad-dokumentazzjoni ta’ Mistral. Il-verżjoni preċedenti kienet taqra r-raġunar minn qasam
textfil-biċċa tal-ħsieb: dak il-qasam ma jeżistix; ir-raġunar huwa lista ta’ biċċiet ta’ test.
Żewġ forom ta’ tweġiba
B’reasoning_effort="high", il-qasam message.content ta’ tweġiba m’għadux string iżda lista ta’ biċċiet. B’reasoning_effort="none", jerġa’ jkun string sempliċi, mingħajr l-ebda traċċa ta’ raġunar. Kodiċi robust jittratta dejjem iż-żewġ forom: dik hija r-regola tad-deheb ta’ din il-lezzjoni.
Anatomija ta’ biċċa ta’ ħsieb
Żewġ tipi ta’ biċċiet jidhru fil-lista:
ThinkChunk(type: "thinking") iġorr it-traċċa tar-raġunar. Il-qasamthinkingtiegħu huwa nnifsu lista ta’ frammentiTextChunk;TextChunk(type: "text") iġorr it-tweġiba finali, fil-qasamtexttiegħu.
Hawnhekk hija l-forma ta’ tweġiba minn Mistral Small 4, meħuda mill-eżempju uffiċjali (testi mqassra):
{
"model": "mistral-small-2603",
"usage": {"prompt_tokens": 77, "completion_tokens": 1114, "total_tokens": 1191},
"choices": [{
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": [
{"type": "thinking", "thinking": [
{"type": "text", "text": "Okay, let's try to figure out John's age..."}
]},
{"type": "text", "text": "Let's denote the ages of the sisters as follows..."}
]
}
}]
}
Il-mudell tal-oġġett tal-SDK tal-Python isegwi din l-istruttura eżattament: ThinkChunk.thinking iżomm il-biċċiet tar-raġunar, u kull TextChunk jesponi l-kontenut tiegħu permezz ta’ .text.
Parsing tat-tweġiba fil-Python
Il-kodiċi uffiċjali jiddistingwi l-biċċiet b’isinstance, wara li jeskludi l-każ ta’ string sempliċi:
from mistralai.client.models import TextChunk, ThinkChunk
content = chat_response.choices[0].message.content
if isinstance(content, str): # reasoning_effort="none"
print(content)
else:
for chunk in content:
if isinstance(chunk, ThinkChunk):
print("--- reasoning ---")
for inner in chunk.thinking:
if isinstance(inner, TextChunk):
print(inner.text)
print("--- end of reasoning ---")
elif isinstance(chunk, TextChunk):
print(chunk.text)
F’applikazzjoni, trid funzjoni li tirritorna r-raġunar u t-tweġiba separatament. Se nsejħulha separate u nużawha mill-ġdid aktar tard fil-kors:
from mistralai.client.models import TextChunk, ThinkChunk
def separate(content):
"""Irritorna (raġunar, tweġiba) għal kontenut li huwa jew string jew lista ta' biċċiet."""
if isinstance(content, str):
return "", content
reasoning, answer = [], []
for chunk in content or []:
if isinstance(chunk, ThinkChunk):
reasoning.extend(i.text for i in chunk.thinking if isinstance(i, TextChunk))
elif isinstance(chunk, TextChunk):
answer.append(chunk.text)
return "".join(reasoning), "".join(answer)
reasoning, answer = separate(chat_response.choices[0].message.content)
Wirja tar-raġunar f’interfaċċa
Is-separazzjoni taż-żewġ partijiet tippermettilek tiddeċiedi x’jara l-utent. Tliet approċċi komuni:
- Aħbi r-raġunar u uri biss it-tweġiba, għal assistent orjentat lejn il-konsumatur;
- Iċċekkja r-raġunar f’blokka li l-utent jista’ jiftaħ jekk irid, għal għodda għall-esperti;
- Uri r-raġunar sħiħ, għal tutor edukattiv fejn il-proċess huwa importanti daqs ir-riżultat.
def render_html(content, show_reasoning=False):
reasoning, answer = separate(content)
html = f"<div class='answer'>{answer}</div>"
if show_reasoning and reasoning:
html = (
"<details><summary>View model reasoning</summary>"
f"<pre>{reasoning}</pre></details>" + html
)
return html
F’proġett reali, eskapa t-test qabel ma tidħlu fl-HTML (pereżempju b’html.escape): kemm ir-raġunar kif ukoll it-tweġiba huma test iġġenerat, mhux markup affidabbli.
Streaming fi tliet fażijiet
Fil-streaming, delta.content ibiddel il-forma hekk kif it-tweġiba tiżvolġi:
- Fażi tar-raġunar:
delta.contenthija lista li fihaThinkChunk; - Tranżizzjoni: lista waħda li fiha kemm il-
ThinkChunktal-għeluq kif ukoll l-ewwelTextChunk; - Fażi tat-tweġiba:
delta.contenthuwa string sempliċi.
Il-kodiċi li ġej, adattat mill-eżempju uffiċjali, juri ż-żewġ fażijiet billi jsegwi flag tal-istat:
import os
from mistralai.client import Mistral
from mistralai.client.models import TextChunk, ThinkChunk
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
in_reasoning = False
for event in client.chat.stream(
model="mistral-large-4-0",
messages=[{"role": "user", "content": "What is 17 × 23?"}],
reasoning_effort="high",
):
delta = event.data.choices[0].delta.content
if not delta:
continue
if isinstance(delta, str): # answer phase
if in_reasoning:
print("\n--- end of reasoning ---")
in_reasoning = False
print(delta, end="", flush=True)
continue
for chunk in delta: # reasoning phase and transition
if isinstance(chunk, ThinkChunk):
if not in_reasoning:
print("--- reasoning ---")
in_reasoning = True
for inner in chunk.thinking:
if isinstance(inner, TextChunk):
print(inner.text, end="", flush=True)
elif isinstance(chunk, TextChunk):
if in_reasoning:
print("\n--- end of reasoning ---")
in_reasoning = False
print(chunk.text, end="", flush=True)
Il-streaming ibiddel l-esperjenza: minflok ma tistenna proċess twil ta’ raġunar jispiċċa quddiem skrin iffriżat, l-utent jara lill-mudell jaħdem, jew mill-inqas indikatur ta’ attività jekk tagħżel li taħbi r-raġunar.
Punti Ewlenin
contenthuwa string b’none, lista ta’ biċċiet b’high: ittratta dejjem iż-żewġ foromThinkChunk.thinkinghija lista ta’TextChunk; it-tweġiba finali tinsab f’TextChunkfil-livell ogħla- Funzjoni
separateli tirritorna (raġunar, tweġiba) tissimplifika l-bqija tal-kodiċi tiegħek - Fil-streaming: lista tar-raġunar, tranżizzjoni mħallta, imbagħad strings tat-tweġiba
- Eskapa kemm ir-raġunar kif ukoll it-tweġiba qabel ma turihom