Ir al contenido principal
Español— Elegir un idioma
Menú

Bloques de pensamiento: leer el razonamiento del modelo

Lección 3 de 12 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Dos formas de respuesta
  2. Anatomía de un bloque de pensamiento
  3. Análisis de la respuesta en Python
  4. Visualización del razonamiento en una interfaz
  5. Transmisión en tres fases
  6. Puntos clave

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 text en 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 campo thinking es a su vez una lista de fragmentos TextChunk;
  • TextChunk (type: "text") contiene la respuesta final en su campo text.

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:

  1. Fase de razonamiento: delta.content es una lista que contiene un ThinkChunk;
  2. Transición: una única lista que contiene tanto el ThinkChunk de cierre como el primer TextChunk;
  3. Fase de respuesta: delta.content es 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

  • content es una cadena con none, una lista de bloques con high: gestiona siempre ambos casos
  • ThinkChunk.thinking es una lista de TextChunk; la respuesta final reside en un TextChunk de nivel superior
  • Una función separate que 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