El parámetro reasoning_effort
En esta página
Lección reescrita el 2 de noviembre de 2026. La versión anterior indicaba que
reasoning_effortsolo aceptaba dos valores y existía únicamente en Mistral Small. En realidad, los valores aceptados dependen del modelo, y Mistral Large 4 ofrece tres. Fuente: Reasoning (documentación de Mistral).
Ajuste de la profundidad del pensamiento
El razonamiento ajustable se basa en un principio sencillo: tú decides, solicitud a solicitud, cuánto debe pensar el modelo antes de responder. La palanca de control se llama reasoning_effort. Se pasa en la llamada a la API al mismo nivel que el modelo y los mensajes, sin necesidad de ninguna otra configuración.
Valores aceptados, modelo por modelo
Este es el error más común: los valores aceptados dependen del modelo.
| Modelo | Valores documentados | Recomendación oficial |
|---|---|---|
Mistral Small 4 (mistral-small-2603) | high, none | — |
Mistral Medium 3.5 (mistral-medium-3-5) | high, none | high para flujos de trabajo agentivos y código |
Mistral Large 4 (mistral-large-4-0) | low, medium, high | Comienza con high; cambia a medium o low si los tokens o la latencia son prioritarios |
En Small 4 y Medium 3.5, high genera un fragmento de razonamiento completo antes de la respuesta, a costa de un mayor consumo de tokens; none reduce el razonamiento al mínimo y lo omite de la respuesta. En Large 4, la escala tiene tres niveles: low para tareas sencillas, medium para equilibrar calidad, tokens y latencia, y high para tareas complejas. Large 4 no acepta none: la documentación especifica que el nivel anteriormente llamado none en su versión preliminar ahora se denomina low.
Un último matiz: el tipo ReasoningEffort en los SDK también enumera minimal, xhigh y max porque la enumeración cubre todos los modelos de la plataforma (max se usa, por ejemplo, con el modelo de terceros zai-glm-5-3). Que un valor aparezca en la enumeración no significa que tu modelo lo acepte.
Implementación en Python
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Mistral Small 4, razonamiento profundo
response_high = client.chat.complete(
model="mistral-small-2603",
messages=[{"role": "user", "content": "Resuelve x^3 - 6x^2 + 11x - 6 = 0 y verifica cada raíz."}],
reasoning_effort="high",
)
# Mistral Small 4, respuesta directa
response_none = client.chat.complete(
model="mistral-small-2603",
messages=[{"role": "user", "content": "¿Cuál es la capital de Portugal?"}],
reasoning_effort="none",
)
# Mistral Large 4, nivel intermedio
response_medium = client.chat.complete(
model="mistral-large-4-0",
messages=[{"role": "user", "content": "Compara dos estrategias de caché para una API de alto tráfico."}],
reasoning_effort="medium",
)
La forma de la respuesta cambia según la configuración. Con high, message.content es una lista que comienza con un fragmento de razonamiento; con none, es una cadena simple. Por tanto, tu código debe manejar ambas formas, como muestra la siguiente lección.
En TypeScript, el parámetro sigue la convención de nombres de JavaScript y se escribe reasoningEffort:
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const response = await client.chat.complete({
model: 'mistral-small-2603',
messages: [{ role: 'user', content: 'Resuelve x^3 - 6x^2 + 11x - 6 = 0.' }],
reasoningEffort: 'high',
});
Elección del nivel según la tarea
Reserva el razonamiento profundo para problemas matemáticos de varios pasos, depuración de código complejo, análisis comparativo, planificación, acertijos lógicos y evaluación de riesgos. Todos comparten una característica: existen múltiples caminos posibles y elegir el incorrecto tiene un coste elevado.
Desactívalo (o baja al nivel más bajo) para preguntas factuales simples, traducción, paráfrasis, extracción directa de información y conversación cotidiana. Aquí el modelo no tiene que arbitrar nada: solo recupera o transforma información, y una fase de razonamiento solo añadiría latencia.
Medición del coste
El razonamiento consume tokens de salida. El ejemplo de la documentación oficial da una idea de la magnitud: un acertijo sobre edades enviado a Mistral Small 4 con high consume 77 tokens de entrada y 1.114 tokens de salida. A la tarifa listada de Small 4 (0,15 $ por millón de tokens de entrada y 0,60 $ por millón de tokens de salida), la solicitud cuesta unos 0,0007 $. Es insignificante por unidad, pero en un millón de solicitudes similares, solo el razonamiento representa varios cientos de dólares, sin beneficio alguno si la mitad de las preguntas no lo necesitaban.
El campo usage en cada respuesta te ofrece la medida exacta: rastrea completion_tokens por tipo de solicitud antes de generalizar una configuración.
Enrutamiento por complejidad
Una solución sencilla es elegir el nivel basándose en la pregunta, utilizando una tabla por modelo para asegurar que nunca envías un valor rechazado:
LEVELS = {
"mistral-small-2603": {"simple": "none", "complex": "high"},
"mistral-large-4-0": {"simple": "low", "complex": "high"},
}
COMPLEX_WORDS = ("calculate", "prove", "compare", "analyze", "optimize", "debug", "why")
def query(client, question, model="mistral-small-2603", level=None):
"""Elige reasoning_effort basándose en la pregunta o aplica un nivel forzado."""
if level is None:
is_complex = any(word in question.lower() for word in COMPLEX_WORDS)
level = LEVELS[model]["complex" if is_complex else "simple"]
return client.chat.complete(
model=model,
messages=[{"role": "user", "content": question}],
reasoning_effort=level,
)
Las heurísticas basadas en palabras clave siguen siendo rudimentarias; bastan para reservar el razonamiento a las solicitudes que se benefician de él, y el argumento level permite forzar una configuración. La lección 12 propone una arquitectura de enrutamiento más completa.
Límites a tener en cuenta
El razonamiento aumenta la probabilidad de una respuesta correcta, pero no la garantiza: verifica los resultados críticos (lección 9). También aumenta la latencia, lo cual es relevante en una interfaz conversacional. Por último, el valor pasado debe coincidir con el modelo llamado: planifica una tabla como la anterior en lugar de dispersar cadenas de texto por todo tu código.
Puntos clave
reasoning_effortcontrola el razonamiento solicitud a solicitud, sin otra configuración- Small 4 y Medium 3.5 aceptan
highynone; Large 4 aceptalow,mediumyhigh, pero nonone - Las enumeraciones de los SDK contienen valores que no todos los modelos aceptan
- Con
high,contentes una lista de fragmentos; connone, una cadena - Mide el coste con
usage.completion_tokensy enruta según la complejidad