Bloques de pensamiento: leer el razonamiento del modelo
En esta página
Lección reescrita el 2 de noviembre de 2026 basándose en la sección Handling thinking chunks de la documentación de Mistral. La versión anterior leía el razonamiento desde un campo
texten el bloque de pensamiento: ese campo no existe; el razonamiento es una lista de bloques de texto.
Dos formas de respuesta
Con reasoning_effort="high", el campo message.content de una respuesta deja de ser una cadena para convertirse en una lista de bloques. Con reasoning_effort="none", vuelve a ser una cadena simple, sin rastro del razonamiento. Un código robusto debe gestionar siempre ambas formas: esta es la regla de oro de esta lección.
Anatomía de un bloque de pensamiento
En la lista aparecen dos tipos de bloques:
ThinkChunk(type: "thinking") contiene el rastro del razonamiento. Su campothinkinges a su vez una lista de fragmentosTextChunk;TextChunk(type: "text") contiene la respuesta final en su campotext.
Esta es la estructura de una respuesta de Mistral Small 4, extraída del ejemplo 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..."}
]
}
}]
}
El modelo de objetos del SDK de Python sigue exactamente esta estructura: ThinkChunk.thinking contiene los bloques de razonamiento y cada TextChunk expone su contenido mediante .text.
Análisis de la respuesta en Python
El código oficial distingue los bloques con isinstance, tras descartar el caso de cadena simple:
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)
En una aplicación, querrás una función que devuelva el razonamiento y la respuesta por separado. La llamaremos separate y la reutilizaremos más adelante en el curso:
from mistralai.client.models import TextChunk, ThinkChunk
def separate(content):
"""Devuelve (razonamiento, respuesta) para un contenido que es una cadena o una lista de bloques."""
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)
Visualización del razonamiento en una interfaz
Separar las dos partes te permite decidir qué ve el usuario. Tres enfoques comunes:
- Ocultar el razonamiento y mostrar solo la respuesta, para un asistente orientado al consumidor;
- Contraer el razonamiento en un bloque que el usuario pueda abrir si lo desea, para una herramienta de expertos;
- Mostrar el razonamiento completo, para un tutor educativo donde el proceso importa tanto como el 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
En un proyecto real, escapa el texto antes de insertarlo en HTML (por ejemplo, con html.escape): tanto el razonamiento como la respuesta son texto generado, no marcado de confianza.
Transmisión en tres fases
En la transmisión (streaming), delta.content cambia de forma a medida que se despliega la respuesta:
- Fase de razonamiento:
delta.contentes una lista que contiene unThinkChunk; - Transición: una única lista que contiene tanto el
ThinkChunkde cierre como el primerTextChunk; - Fase de respuesta:
delta.contentes una cadena simple.
El siguiente código, adaptado del ejemplo oficial, muestra ambas fases siguiendo un 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)
La transmisión cambia la experiencia: en lugar de esperar a que un largo proceso de razonamiento termine frente a una pantalla congelada, el usuario ve al modelo trabajando o, al menos, un indicador de actividad si decides ocultar el razonamiento.
Puntos clave
contentes una cadena connone, una lista de bloques conhigh: gestiona siempre ambos casosThinkChunk.thinkinges una lista deTextChunk; la respuesta final reside en unTextChunkde nivel superior- Una función
separateque devuelve (razonamiento, respuesta) simplifica el resto de tu código - En transmisión: lista de razonamiento, transición mixta y luego cadenas de respuesta
- Escapa tanto el razonamiento como la respuesta antes de mostrarlos