Parâmetros Básicos
Nesta página
Configure as Suas Chamadas à API
Para além dos campos obrigatórios model e messages, a API de Completions de Chat aceita um conjunto de parâmetros que controlam o comportamento da geração. Estas definições distinguem um extrator de dados que devolve resultados idênticos para a mesma fatura de um gerador de slogans que nunca se repete. O código de chamada permanece inalterado de um caso de uso para o outro; apenas as definições mudam, e é exatamente por isso que precisa de compreender o que cada uma faz.
Aqui estão os parâmetros que vai manusear diariamente, juntamente com os seus tipos e valores padrão.
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
model | string | — | Identificador do modelo (obrigatório) |
messages | array | — | Matriz de mensagens (obrigatório) |
max_tokens | integer | variável | Número máximo de tokens de saída |
temperature | float | 0.7 | Controla a criatividade (0.0 a 1.5) |
top_p | float | 1.0 | Amostragem por núcleo (0.0 a 1.0) |
stream | boolean | false | Ativa a transmissão SSE |
safe_prompt | boolean | false | Ativa as barreiras de segurança |
O Parâmetro model
A sua escolha de modelo determina imediatamente as capacidades, a velocidade e o custo de cada chamada — três compromissos que não pode recuperar noutro lugar. Em abril de 2026, os modelos principais são:
# Modelo principal — raciocínio complexo, multilingue
model = "mistral-large-latest"
# Modelo compacto — rápido, económico, ideal para produção
model = "mistral-small-latest"
# Modelo miniatura — ultra-rápido, computação de borda
model = "ministral-3b-latest"
# Modelo de código — especializado em programação
model = "codestral-latest"
O sufixo -latest é conveniente durante o desenvolvimento: aponta sempre para a versão mais recente sem exigir alterações no código. Em produção, no entanto, esta conveniência torna-se um risco, pois uma atualização do lado da Mistral pode alterar subtilmente o comportamento da sua aplicação. Prefira identificadores versionados como mistral-large-2512 para garantir a reprodutibilidade dos seus testes.
O Parâmetro max_tokens
Este parâmetro define o limite superior do número de tokens que o modelo pode gerar na sua resposta. Não força o modelo a produzir exatamente esse número; define apenas um teto, nada mais.
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Resuma este texto numa frase."}],
max_tokens=100 # A resposta não excederá 100 tokens
)
Se o modelo atingir este limite, a resposta é cortada abruptamente e finish_reason devolve "length" em vez de "stop". Esta é a causa mais comum de respostas que param a meio de uma frase, e ninguém se apercebe até monitorizar este campo. O reflexo correto é calibrar o teto conforme a tarefa: a classificação cabe em 10 a 50 tokens, uma vez que espera apenas um rótulo; um resumo precisa de 200 a 500 tokens; a escrita livre leva 1.000 a 4.000; e a geração de código atinge facilmente 2.000 ou 8.000 tokens, pois um ficheiro completo é longo.
O Parâmetro temperature
A temperatura controla o grau de aleatoriedade na seleção de tokens. Quanto menor o valor, mais determinístico e previsível se torna o modelo; quanto maior for, mais tentará continuações improváveis. Para perguntas factuais, quer a primeira abordagem; para exercícios de naming, a segunda.
# Baixa temperatura — extração, classificação, factual
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Qual é a capital de França?"}],
temperature=0.1
)
# Alta temperatura — criatividade, brainstorming
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Invente um nome para uma startup de IA."}],
temperature=1.2
)
O intervalo varia de 0.0 a 1.5. Não confie em temperature=0 para um determinismo perfeito: persistem ligeiras variações devido ao arredondamento de vírgula flutuante ao nível do hardware.
O Parâmetro top_p
A amostragem por núcleo, ou Top P, atua na mesma alavanca, mas por um caminho diferente: limita os tokens candidatos por um limiar de probabilidade cumulativa. Com top_p=0.5, apenas os tokens mais prováveis cujas probabilidades somadas atingem 50% permanecem em competição; o resto é descartado de imediato.
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Complete: O gato está em cima do..."}],
temperature=0.7,
top_p=0.9 # Considera tokens que cobrem 90% da probabilidade
)
A Mistral recomenda ajustar apenas um parâmetro de cada vez, seja a temperatura ou o top_p, nunca ambos em conjunto. A razão é prática: se um resultado se tornar estranho após mover ambos os controlos, nada lhe indica qual deles o causou, e perde tanto a capacidade de depuração como a reprodutibilidade.
Exemplo Completo com Todos os Parâmetros
Combinadas numa única chamada, estas definições criam um gerador de slogans intencionalmente breve e ligeiramente arrojado, ao mesmo tempo que rastreia o consumo de tokens:
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "Você é um redator de marketing conciso e impactante."
},
{
"role": "user",
"content": "Escreva um slogan para uma aplicação de meditação."
}
],
max_tokens=50,
temperature=0.9,
top_p=1.0
)
print(response.choices[0].message.content)
print(f"Tokens utilizados: {response.usage.total_tokens}")
Execute este script três vezes seguidas, depois substitua temperature=0.9 por 0.1 e execute-o mais três vezes. A diferença entre as duas séries ensinar-lhe-á mais sobre este parâmetro do que qualquer definição poderia fazer.
Pontos-chave
modelemessagessão os únicos parâmetros obrigatóriosmax_tokensé um teto, não um alvo — verifiquefinish_reasonpara detetar truncagem- Utilize
temperaturebaixa para tarefas factuais, alta para criatividade top_prefina a distribuição de tokens — não o ajuste simultaneamente comtemperature- Utilize identificadores de modelo versionados em produção para garantir a reprodutibilidade