O parâmetro reasoning_effort
Nesta página
Lição reescrita em 2 de novembro de 2026. A versão anterior afirmava que o
reasoning_effortaceitava apenas dois valores e existia apenas no Mistral Small. Na realidade, os valores aceites dependem do modelo, e o Mistral Large 4 oferece três. Fonte: Reasoning (documentação da Mistral).
Definir a profundidade do pensamento
O raciocínio ajustável assenta num princípio simples: decide, pedido a pedido, quanto tempo o modelo deve pensar antes de responder. A alavanca chama-se reasoning_effort. Passa-a na chamada à API ao mesmo nível do modelo e das mensagens, sem necessidade de qualquer outra configuração.
Valores aceites, modelo a modelo
Esta é a armadilha mais comum: os valores aceites dependem do modelo.
| Modelo | Valores documentados | Recomendação oficial |
|---|---|---|
Mistral Small 4 (mistral-small-2603) | high, none | — |
Mistral Medium 3.5 (mistral-medium-3-5) | high, none | high para fluxos de trabalho agentivos e código |
Mistral Large 4 (mistral-large-4-0) | low, medium, high | Comece com high, depois mude para medium ou low se os tokens ou a latência forem prioritários |
No Small 4 e no Medium 3.5, o valor high gera um fragmento de raciocínio completo antes da resposta, ao custo de um maior consumo de tokens; o valor none reduz o raciocínio ao mínimo e omite-o da resposta. No Large 4, a escala tem três níveis: low para tarefas simples, medium para equilibrar qualidade, tokens e latência, e high para tarefas complexas. O Large 4 não aceita none: a documentação especifica que o nível anteriormente chamado none na sua versão de pré-visualização passa agora a chamar-se low.
Uma última nuance: o tipo ReasoningEffort nos SDKs também enumera minimal, xhigh e max, porque a enumeração cobre todos os modelos da plataforma (o max é usado, por exemplo, pelo modelo de terceiros zai-glm-5-3). O facto de um valor aparecer na enumeração não significa que o seu modelo o aceite.
Implementação em Python
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Mistral Small 4, raciocínio profundo
response_high = client.chat.complete(
model="mistral-small-2603",
messages=[{"role": "user", "content": "Solve x^3 - 6x^2 + 11x - 6 = 0 and verify each root."}],
reasoning_effort="high",
)
# Mistral Small 4, resposta direta
response_none = client.chat.complete(
model="mistral-small-2603",
messages=[{"role": "user", "content": "What is the capital of Portugal?"}],
reasoning_effort="none",
)
# Mistral Large 4, nível intermédio
response_medium = client.chat.complete(
model="mistral-large-4-0",
messages=[{"role": "user", "content": "Compare two caching strategies for a high-traffic API."}],
reasoning_effort="medium",
)
A estrutura da resposta muda consoante a definição. Com high, message.content é uma lista que começa com um fragmento de raciocínio; com none, é uma simples cadeia de caracteres. O seu código deve, portanto, lidar com ambas as formas, como mostra a próxima lição.
Em TypeScript, o parâmetro segue a convenção de nomes do JavaScript e escreve-se 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: 'Solve x^3 - 6x^2 + 11x - 6 = 0.' }],
reasoningEffort: 'high',
});
Escolher o nível por tarefa
Reserve o raciocínio profundo para problemas matemáticos em várias etapas, depuração de código complexo, análise comparativa, planeamento, puzzles de lógica e avaliação de riscos. Estes casos partilham uma característica comum: existem múltiplos caminhos possíveis e escolher o errado tem um custo elevado.
Desative-o (ou reduza ao nível mais baixo) para perguntas factuais simples, tradução, paráfrase, extração direta de informação e conversação do dia a dia. Aqui, o modelo não tem nada a arbitrar: apenas recupera ou transforma informação, e uma fase de raciocínio apenas adicionaria latência.
Medir o custo
O raciocínio consome tokens de saída. O exemplo da documentação oficial dá uma ordem de grandeza: um enigma sobre idades enviado ao Mistral Small 4 com high consome 77 tokens de entrada e 1.114 tokens de saída. À tarifa listada do Small 4 de 0,15 USD por milhão de tokens de entrada e 0,60 USD por milhão de tokens de saída, o pedido custa cerca de 0,0007 USD. É negligenciável por unidade, mas, num milhão de pedidos semelhantes, só o raciocínio representa várias centenas de dólares, sem ganho algum se metade das perguntas não o exigisse.
O campo usage em cada resposta dá-lhe a medida exata: monitore os completion_tokens por tipo de pedido antes de generalizar uma definição.
Roteamento por complexidade
Uma solução simples consiste em escolher o nível com base na pergunta, utilizando uma tabela por modelo para garantir que nunca envia um valor rejeitado:
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):
"""Escolhe o reasoning_effort com base na pergunta ou aplica um nível forçado."""
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,
)
As heurísticas por palavras-chave continuam a ser rudimentares; bastam para reservar o raciocínio aos pedidos que dele beneficiam, e o argumento level permite-lhe forçar uma definição. A Lição 12 propõe uma arquitetura de roteamento mais completa.
Limites a conhecer
O raciocínio aumenta a probabilidade de uma resposta correta, mas não a garante: verifique os resultados críticos (Lição 9). Aumenta também a latência, o que é relevante numa interface conversacional. Por fim, o valor passado deve corresponder ao modelo chamado: preveja uma tabela como a acima, em vez de dispersar cadeias de caracteres pelo seu código.
Pontos-chave
- O
reasoning_effortcontrola o raciocínio pedido a pedido, sem outra configuração - O Small 4 e o Medium 3.5 aceitam
highenone; o Large 4 aceitalow,mediumehigh, mas nãonone - As enumerações dos SDKs contêm valores que nem todos os modelos aceitam
- Com
high, ocontenté uma lista de fragmentos; comnone, é uma cadeia de caracteres - Meça o custo com
usage.completion_tokense faça o roteamento por complexidade