Blocos de raciocínio: ler o raciocínio do modelo
Nesta página
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
textno 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 campothinkingé, por sua vez, uma lista de fragmentosTextChunk;TextChunk(type: "text") transporta a resposta final, no seu campotext.
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:
- Fase de raciocínio:
delta.contenté uma lista contendo umThinkChunk; - Transição: uma única lista contendo tanto o
ThinkChunkde fecho como o primeiroTextChunk; - 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 comnone, uma lista de blocos comhigh: trate sempre ambos os casosThinkChunk.thinkingé uma lista deTextChunk; a resposta final reside numTextChunkde nível superior- Uma função
separateque 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