Ir para o conteúdo principal
Português— Escolher um idioma
Menu

O parâmetro reasoning_effort

Aula 2 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Definir a profundidade do pensamento
  2. Valores aceites, modelo a modelo
  3. Implementação em Python
  4. Escolher o nível por tarefa
  5. Medir o custo
  6. Roteamento por complexidade
  7. Limites a conhecer
  8. Pontos-chave

Lição reescrita em 2 de novembro de 2026. A versão anterior afirmava que o reasoning_effort aceitava 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.

ModeloValores documentadosRecomendação oficial
Mistral Small 4 (mistral-small-2603)high, none—
Mistral Medium 3.5 (mistral-medium-3-5)high, nonehigh para fluxos de trabalho agentivos e código
Mistral Large 4 (mistral-large-4-0)low, medium, highComece 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_effort controla o raciocínio pedido a pedido, sem outra configuração
  • O Small 4 e o Medium 3.5 aceitam high e none; o Large 4 aceita low, medium e high, mas não none
  • As enumerações dos SDKs contêm valores que nem todos os modelos aceitam
  • Com high, o content é uma lista de fragmentos; com none, é uma cadeia de caracteres
  • Meça o custo com usage.completion_tokens e faça o roteamento por complexidade