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

Parâmetros Básicos

Aula 3 de 16 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Configure as Suas Chamadas à API
  2. O Parâmetro model
  3. O Parâmetro max_tokens
  4. O Parâmetro temperature
  5. O Parâmetro top_p
  6. Exemplo Completo com Todos os Parâmetros
  7. Pontos-chave

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âmetroTipoPadrãoDescrição
modelstring—Identificador do modelo (obrigatório)
messagesarray—Matriz de mensagens (obrigatório)
max_tokensintegervariávelNúmero máximo de tokens de saída
temperaturefloat0.7Controla a criatividade (0.0 a 1.5)
top_pfloat1.0Amostragem por núcleo (0.0 a 1.0)
streambooleanfalseAtiva a transmissão SSE
safe_promptbooleanfalseAtiva 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

  • model e messages são os únicos parâmetros obrigatórios
  • max_tokens é um teto, não um alvo — verifique finish_reason para detetar truncagem
  • Utilize temperature baixa para tarefas factuais, alta para criatividade
  • top_p refina a distribuição de tokens — não o ajuste simultaneamente com temperature
  • Utilize identificadores de modelo versionados em produção para garantir a reprodutibilidade