Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Blocos de raciocínio: ler o raciocínio do modelo

Aula 3 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Duas formas de resposta
  2. Anatomia de um bloco de raciocínio
  3. Analisar a resposta em Python
  4. Exibir o raciocínio numa interface
  5. Streaming em três fases
  6. Pontos-chave

Lição reescrita em 2 de novembro de 2026 com base na secção Handling thinking chunks da documentação da Mistral. A versão anterior lia o raciocínio a partir de um campo text no bloco de raciocínio: esse campo não existe; o raciocínio é uma lista de blocos de texto.

Duas formas de resposta

Com reasoning_effort="high", o campo message.content de uma resposta deixa de ser uma cadeia de caracteres para se tornar uma lista de blocos. Com reasoning_effort="none", volta a ser uma cadeia simples, sem qualquer rasto de raciocínio. Um código robusto deve lidar sempre com ambas as formas: esta é a regra de ouro desta lição.

Anatomia de um bloco de raciocínio

Dois tipos de blocos surgem na lista:

  • ThinkChunk (type: "thinking") transporta o rasto do raciocínio. O seu campo thinking é, por sua vez, uma lista de fragmentos TextChunk;
  • TextChunk (type: "text") transporta a resposta final, no seu campo text.

Eis a estrutura de uma resposta do Mistral Small 4, retirada do exemplo oficial (textos abreviados):

{
  "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..."}
      ]
    }
  }]
}

O modelo de objetos do SDK Python segue exatamente esta estrutura: ThinkChunk.thinking contém os blocos de raciocínio e cada TextChunk expõe o seu conteúdo através de .text.

Analisar a resposta em Python

O código oficial distingue os blocos com isinstance, após excluir o caso da cadeia simples:

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)

Numa aplicação, vai querer uma função que devolva o raciocínio e a resposta separadamente. Vamos chamá-la separate e reutilizá-la mais tarde no curso:

from mistralai.client.models import TextChunk, ThinkChunk

def separate(content):
    """Devolve (raciocínio, resposta) para conteúdo que seja uma cadeia ou uma lista de blocos."""
    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)

Exibir o raciocínio numa interface

Separar as duas partes permite-lhe decidir o que o utilizador vê. Três abordagens comuns:

  • Ocultar o raciocínio e mostrar apenas a resposta, para um assistente virado para o consumidor;
  • Recolher o raciocínio num bloco que o utilizador pode abrir se desejar, para uma ferramenta especializada;
  • Mostrar todo o raciocínio, para um tutor educativo onde o processo importa tanto quanto o resultado.
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

Num projeto real, escape o texto antes de o inserir no HTML (por exemplo, com html.escape): tanto o raciocínio como a resposta são texto gerado, não markup fidedigno.

Streaming em três fases

No streaming, delta.content muda de forma à medida que a resposta se desenrola:

  1. Fase de raciocínio: delta.content é uma lista contendo um ThinkChunk;
  2. Transição: uma única lista contendo tanto o ThinkChunk de fecho como o primeiro TextChunk;
  3. Fase de resposta: delta.content é uma cadeia simples.

O código seguinte, adaptado do exemplo oficial, exibe ambas as fases acompanhando um indicador de estado:

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)

O streaming altera a experiência: em vez de esperar que um longo processo de raciocínio termine perante um ecrã congelado, o utilizador vê o modelo a trabalhar ou, pelo menos, um indicador de atividade se optar por ocultar o raciocínio.

Pontos-chave

  • content é uma cadeia com none, uma lista de blocos com high: trate sempre ambos os casos
  • ThinkChunk.thinking é uma lista de TextChunk; a resposta final reside num TextChunk de nível superior
  • Uma função separate que devolve (raciocínio, resposta) simplifica o resto do seu código
  • Em streaming: lista de raciocínio, transição mista e, depois, cadeias de resposta
  • Escape tanto o raciocínio como a resposta antes de os exibir