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

A Sua Primeira Chamada de API em Python

Aula 5 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. O Seu Primeiro Intercâmbio com um Modelo Mistral
  2. Inicializar o Cliente
  3. Enviar um Pedido com chat.complete()
  4. Ler o Objeto Retornado
  5. Ajustar o Comportamento do Modelo
  6. Uma Chamada Pronta para Produção
  7. Pontos-chave

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 naturalmente
  • length: a resposta foi cortada porque atingiu o limite de max_tokens
  • model_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.usage indica quantos tokens foram consumidos (útil para o rastreio de custos)
  • temperature controla a criatividade; max_tokens limita o comprimento
  • Comece com mistral-small-latest: é rápido, económico e performante