Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Biċċiet ta' ħsieb: qari tar-raġunar tal-mudell

Lezzjoni 3 / 12 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Żewġ forom ta’ tweġiba
  2. Anatomija ta’ biċċa ta’ ħsieb
  3. Parsing tat-tweġiba fil-Python
  4. Wirja tar-raġunar f’interfaċċa
  5. Streaming fi tliet fażijiet
  6. Punti Ewlenin

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 text fil-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-qasam thinking tiegħu huwa nnifsu lista ta’ frammenti TextChunk;
  • TextChunk (type: "text") iġorr it-tweġiba finali, fil-qasam text tiegħ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:

  1. Fażi tar-raġunar: delta.content hija lista li fiha ThinkChunk;
  2. Tranżizzjoni: lista waħda li fiha kemm il-ThinkChunk tal-għeluq kif ukoll l-ewwel TextChunk;
  3. Fażi tat-tweġiba: delta.content huwa 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

  • content huwa string b’none, lista ta’ biċċiet b’high: ittratta dejjem iż-żewġ forom
  • ThinkChunk.thinking hija lista ta’ TextChunk; it-tweġiba finali tinsab f’TextChunk fil-livell ogħla
  • Funzjoni separate li 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