A Sua Primeira Chamada de API em Python
Nesta página
O Seu Primeiro Intercâmbio com um Modelo Mistral
O SDK está instalado e a sua chave de API está pronta: chegou a altura de enviar um pedido real e, mais importante, compreender o que é devolvido. Muitos programadores param na primeira linha da resposta e ignoram o restante do objeto retornado. Isso é um erro, pois o rastreio de custos e o diagnóstico de respostas truncadas residem exatamente nesses dados restantes. Vamos começar com um código mínimo e evoluir até à estrutura completa.
Inicializar o Cliente
O cliente é o ponto de entrada para todas as suas interações com a API:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Este gere as ligações HTTP, as novas tentativas em caso de erros de rede e a serialização dos pedidos. Instancie-o uma única vez no arranque da aplicação. Recriar um cliente para cada chamada obriga-o a pagar desnecessariamente pela configuração da ligação e é uma das causas mais subtis de latência excessiva.
Enviar um Pedido com chat.complete()
Vai utilizar o método chat.complete() na maioria das vezes. Este envia as suas mensagens e aguarda a resposta completa do modelo antes de devolver o controlo:
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": "Explain the concept of tokenization in three sentences."
}
]
)
print(response.choices[0].message.content)
Dois parâmetros são suficientes aqui. O model especifica o ID do modelo: mistral-small-latest aponta sempre para a versão mais recente do Mistral Small, tornando-o a escolha natural para começar, dado que é rápido e económico. O parâmetro messages espera uma lista de mensagens estruturadas, cada uma com um role — system, user ou assistant — e um campo content que contém o texto. Esta estrutura pode parecer pesada para uma única pergunta, mas faz todo o sentido quando chegar à lição sobre conversas com múltiplas intervenções.
Ler o Objeto Retornado
O objeto response contém muito mais do que apenas o texto gerado:
# Response text
text = response.choices[0].message.content
# Role (always "assistant" for a response)
role = response.choices[0].message.role
# Stop reason
finish = response.choices[0].finish_reason # "stop", "length", etc.
# Token statistics
input_tokens = response.usage.prompt_tokens
output_tokens = response.usage.completion_tokens
total_tokens = response.usage.total_tokens
print(f"Response ({output_tokens} tokens): {text}")
print(f"Total tokens consumed: {total_tokens}")
Preste muita atenção ao campo usage desde o primeiro dia. Registar este dado em cada chamada indica-lhe exatamente qual a funcionalidade da sua aplicação que está a consumir o seu orçamento, sem ter de fazer engenharia reversa da sua fatura no final do mês.
Quanto ao finish_reason, este indica por que motivo o modelo parou e assume um destes valores:
stop: o modelo concluiu a sua resposta naturalmentelength: a resposta foi cortada porque atingiu o limite demax_tokensmodel_length: o contexto total (entrada + saída) atingiu o limite do modelo
Uma resposta que termina a meio de uma frase não é um erro do modelo: é um finish_reason de length que ninguém verificou. Verifique sempre este campo antes de concluir que existe um problema de qualidade.
Ajustar o Comportamento do Modelo
Três parâmetros adicionais permitem-lhe orientar a geração:
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "user",
"content": "Propose three names for an educational AI startup."
}
],
temperature=0.7,
max_tokens=500,
top_p=0.95,
)
A Temperature controla o grau de liberdade do modelo. Em 0.0, as respostas são determinísticas: o mesmo prompt produz sempre o mesmo texto, o que é ideal para extração ou classificação. Entre 0.3 e 0.5, obtém um bom equilíbrio para tarefas factuais. Entre 0.7 e 1.0, as respostas tornam-se mais criativas e variadas — esta é a gama utilizada no exemplo acima, uma vez que estamos a pedir ideias de nomes e ver a mesma ideia três vezes seria inútil. Acima de 1.0, a geração torna-se altamente aleatória e raramente tem utilidade prática.
O max_tokens limita o comprimento da resposta, o que ajuda a controlar custos e a manter os resultados geríveis. Lembre-se apenas de que, se o modelo for cortado, o finish_reason será "length". O top_p afeta a diversidade através de um mecanismo diferente: filtra os tokens menos prováveis. Um valor de 0.95 significa que o modelo considera apenas os tokens que representam 95% da probabilidade cumulativa.
Uma Chamada Pronta para Produção
Em condições reais, a rede falha, as chaves expiram e as quotas esgotam-se. Envolva sempre as suas chamadas em tratamento de erros:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
try:
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{"role": "user", "content": "What is the capital of France?"}
],
max_tokens=100,
)
text = response.choices[0].message.content
print(f"Response: {text}")
print(f"Tokens used: {response.usage.total_tokens}")
except Exception as e:
print(f"API call error: {e}")
Utilize este esqueleto para as suas próprias experiências, substituindo simplesmente o conteúdo da mensagem. Este é o ponto de partida para tudo o que se segue neste curso.
Pontos-chave
client.chat.complete()é o método principal para interagir com os modelos- O texto da resposta encontra-se em
response.choices[0].message.content response.usageindica quantos tokens foram consumidos (útil para o rastreio de custos)temperaturecontrola a criatividade;max_tokenslimita o comprimento- Comece com
mistral-small-latest: é rápido, económico e performante