Escolher o nível de raciocínio adequado
Nesta página
Lição reescrita em 2 de novembro de 2026. Anteriormente, contrastava o raciocínio «ajustável» do Mistral Small com o raciocínio «nativo» do Magistral, mas o Magistral foi desativado em 31 de julho de 2026. A escolha reside agora entre modelos generalistas e níveis de
reasoning_effort. Fontes: Reasoning · Cartões de modelo Small 4 e Large 4.
Dois botões em vez de uma linha de modelos
Escolher um modelo de raciocínio na Mistral significava, antigamente, optar entre duas linhas distintas. Hoje, significa ajustar dois botões: o modelo (Small 4 para a maioria das tarefas, Large 4 para os casos mais difíceis) e o nível de raciocínio (none ou high no Small 4; low, medium ou high no Large 4). Uma única aplicação pode, e muitas vezes deve, utilizar múltiplas combinações.
A matriz de decisão
| Situação | Configuração inicial | Porquê |
|---|---|---|
| Pergunta factual, reformulação, extração | Small 4, none | Nada a deliberar: o raciocínio apenas adicionaria latência e tokens |
| Cálculo em várias etapas, depuração de rotina, comparação simples | Small 4, high | O raciocínio corrige erros de encadeamento por um custo moderado |
| Resumo ou reformulação no Large 4 | Large 4, low | O Large 4 não aceita none; low é o seu nível mais económico |
| Análise multicritério, plano de migração, erro subtil | Large 4, medium depois high | Teste primeiro o nível intermédio; suba se a qualidade o exigir |
| Decisão crítica (jurídica, financeira, médica) | Large 4, high + verificação | O raciocínio reduz erros, mas não os elimina: uma segunda passagem ou revisão humana permanece necessária |
Esta matriz fornece pontos de partida, não verdades absolutas: as suas próprias avaliações decidem. Lembre-se também de que o Large 4 está em Pré-visualização Pública desde 2 de novembro de 2026.
Calcule antes de escalar
As tarifas listadas (por milhão de tokens, registadas em 2 de novembro de 2026) permitem estimar o custo de uma configuração a partir do campo usage nas respostas:
RATES = { # USD por milhão de tokens: (entrada, saída)
"mistral-small-2603": (0.15, 0.60),
"mistral-large-4-0": (0.70, 2.10),
"mistral-medium-3-5": (1.50, 7.50), # descontinuado, desativação em 30 de abril de 2027
}
def cost(response, model):
"""Custo de uma resposta, incluindo raciocínio (excluindo descontos de cache)."""
input_rate, output_rate = RATES[model]
u = response.usage
return (u.prompt_tokens * input_rate + u.completion_tokens * output_rate) / 1_000_000
Some este custo por tipo de pedido ao longo de alguns dias de tráfego real: esse valor indica se uma configuração high generalizada é sustentável.
Uma arquitetura de roteamento
Numa aplicação real, a maioria dos pedidos é simples. Pagar por raciocínio nestes casos não agrega valor. O seguinte roteador pergunta primeiro ao Small 4, sem raciocínio, para estimar a complexidade da questão, encaminhando depois a consulta para a configuração adequada:
import os
from mistralai.client import Mistral
class ReasoningRouter:
"""Encaminha cada questão para um modelo e um nível de raciocínio."""
def __init__(self):
self.client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
def complexity(self, question):
r = self.client.chat.complete(
model="mistral-small-2603",
messages=[{"role": "user", "content":
f"Avalie a complexidade desta questão de 0 a 10. Responda apenas com o número: {question}"}],
reasoning_effort="none",
)
try:
return min(max(int(str(r.choices[0].message.content).strip()), 0), 10)
except ValueError:
return 5 # valor conservador se a resposta não for um número
def respond(self, question, system_prompt=None):
score = self.complexity(question)
if score <= 3:
model, level = "mistral-small-2603", "none"
elif score <= 7:
model, level = "mistral-small-2603", "high"
else:
model, level = "mistral-large-4-0", "high"
messages = [{"role": "system", "content": system_prompt}] if system_prompt else []
messages.append({"role": "user", "content": question})
return self.client.chat.complete(model=model, messages=messages, reasoning_effort=level)
A chamada de classificação custa pouco: algumas dezenas de tokens no modelo mais barato, sem raciocínio. Ajuste os limiares após observação, comparando a qualidade e o custo de cada ramo.
Boas práticas de produção
Registe o uso por ramo. Para cada resposta, guarde o modelo, o nível, usage.prompt_tokens, usage.completion_tokens e o custo calculado acima. Sem estes números, não consegue determinar se o raciocínio compensa.
Fixe identificadores datados. Em produção, utilize mistral-small-2603 em vez de mistral-small-latest: um alias pode mudar para uma nova versão sem que o seu código altere. Centralize estes identificadores numa única configuração.
MODELS = {
"fast": ("mistral-small-2603", "none"),
"reasoning": ("mistral-small-2603", "high"),
"deep": ("mistral-large-4-0", "high"),
}
Planee um fallback. Como o Large 4 está em Pré-visualização Pública, um fallback para o Small 4 no modo high protege o seu serviço se a chamada falhar. Todos os erros HTTP do SDK herdam de MistralError:
from mistralai.client import errors
def query_with_fallback(client, messages):
try:
return client.chat.complete(model="mistral-large-4-0", messages=messages, reasoning_effort="high")
except errors.MistralError:
return client.chat.complete(model="mistral-small-2603", messages=messages, reasoning_effort="high")
Fique atento às descontinuações. A página de modelos da Mistral lista datas de descontinuação e desativação. O Medium 3.5 será desativado em 30 de abril de 2027: se o utilizar, o prazo já está definido.
Resumo do curso
O raciocínio dá ao modelo um espaço para pensar antes de responder; na Mistral, configura isto por pedido com reasoning_effort, cujos valores dependem do modelo. A resposta chega então como fragmentos — pensamento e depois resposta — que deve saber ler, inclusive em modo de streaming, e reproduzir na íntegra para conversas multi-turno. Os Agentes e a API de Conversas transportam a mesma configuração em completion_args. O Magistral está desativado: o Small 4 e o Large 4 assumem o controlo, servindo o Medium 3.5 apenas como passo de transição. Finalmente, o raciocínio justifica-se onde existem caminhos a explorar e erros a detetar (matemática, código, decisões), e deve ser sempre medido: qualidade, tokens, latência.
Pontos-chave
- Dois botões: o modelo (Small 4, Large 4) e o nível de
reasoning_effort - Small 4 em
nonepara tarefas simples, emhighpara várias etapas; Large 4 para os casos mais difíceis - Calcule cada configuração a partir de
usagee das tarifas oficiais antes de a escalar - Um roteador reserva o raciocínio para consultas que dele beneficiam
- Em produção: identificadores datados, registo de uso, fallback do Large 4 para o Small 4
Teste os seus conhecimentos
Cinco questões para validar os essenciais do curso.
1. Quais os valores de reasoning_effort que o Mistral Large 4 aceita e qual rejeita?
Resposta: low, medium e high (a documentação recomenda high como ponto de partida). Rejeita none: o nível anteriormente assim chamado na sua pré-visualização chama-se agora low.
2. Onde se encontra o texto de pensamento numa resposta com raciocínio?
Resposta: Num ThinkChunk (tipo thinking) dentro da lista message.content. O seu campo thinking é, por sua vez, uma lista de objetos TextChunk, de onde lê o campo text. A resposta final está num TextChunk de nível superior.
3. O que deve repor no histórico de uma conversa multi-turno em Chat Completions?
Resposta: A mensagem completa do assistente, incluindo os fragmentos de pensamento. Remover o pensamento poupa tokens, mas degrada significativamente a qualidade das voltas subsequentes.
4. O seu código ainda chama magistral-medium-latest: o que deve fazer?
Resposta: Migre imediatamente, pois o Magistral foi desativado em 31 de julho de 2026. Aponte para o Small 4 se a qualidade for suficiente, caso contrário para o Large 4 com reasoning_effort="high"; o Medium 3.5, o substituto designado, está ele próprio descontinuado até 30 de abril de 2027. Remova prompt_mode e o modelo de pensamento dos prompts de sistema.
5. Como define reasoning_effort num agente Mistral?
Resposta: No campo completion_args do agente, por exemplo completion_args={"reasoning_effort": "high"}. Com a API de Conversas, utilize o mesmo campo em cada start ou append.