Resposta e Utilização
Nesta página
Compreenda o Que a API Devolve
A maioria dos programadores que se inicia na API lê apenas uma linha da resposta — o texto gerado — e ignora todo o resto. Isso é um erro. Cada chamada a /v1/chat/completions devolve um objeto JSON rico. É aqui que encontrará os dados necessários para monitorizar custos, detetar uma resposta truncada antes de chegar ao utilizador e identificar uma chamada específica ao abrir um ticket de suporte.
Anatomia Completa da Resposta
Comecemos pelos metadados. Estes são os campos que raramente verifica, mas que desejará ter registado no dia em que ocorrer um incidente:
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": "user", "content": "What is machine learning?"}],
max_tokens=500
)
# Access metadata
print(f"Request ID : {response.id}")
print(f"Model used : {response.model}")
print(f"Created at : {response.created}")
O campo id é um identificador único atribuído a cada pedido. Esta é a referência que fornecerá ao suporte técnico e que lhe permitirá ligar uma reclamação de um utilizador a uma chamada específica nos seus registos. O campo model confirma qual o modelo realmente utilizado. Isto é mais importante do que possa pensar quando chama um alias -latest e o comportamento muda da noite para o dia sem qualquer alteração no seu código.
O Array choices
O cerne da resposta reside em choices. Por predefinição, este array contém um único elemento. É a partir dele que extrai tanto o texto como o veredicto sobre como a geração terminou:
choice = response.choices[0]
# The generated message
print(choice.message.role) # "assistant"
print(choice.message.content) # The response text
# The index of this response in the array
print(choice.index) # 0
# The stop reason
print(choice.finish_reason) # "stop", "length", or "tool_calls"
Se solicitar múltiplas respostas utilizando o parâmetro n, que abordaremos na lição 15, choices conterá vários elementos e o índice voltará a ser relevante.
Valores de finish_reason
Este campo determina a fiabilidade da sua aplicação. Existem três valores possíveis. stop sinaliza que o modelo terminou a sua resposta naturalmente. Este é o caso normal, onde pode apresentar o conteúdo sem reservas. length significa que a geração foi cortada por max_tokens, pelo que a resposta está potencialmente incompleta — um resumo sem conclusão ou uma lista que para no sétimo item. Finalmente, tool_calls indica que o modelo está a solicitar a execução de uma ferramenta externa no âmbito da chamada de funções, e a bola está agora no seu campo.
Cada um destes casos exige um tratamento distinto, que deve implementar de uma vez por todas:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Write a detailed report."}],
max_tokens=200
)
choice = response.choices[0]
if choice.finish_reason == "stop":
# Complete response — normal processing
result = choice.message.content
elif choice.finish_reason == "length":
# Truncated response — retry with more tokens or warn the user
print("Warning: The response was truncated.")
# Option: Retry with a higher max_tokens limit
# Option: Ask the model to continue
elif choice.finish_reason == "tool_calls":
# The model requests a tool call
for tool_call in choice.message.tool_calls:
print(f"Requested tool: {tool_call.function.name}")
Repare que o ramo length não deixa simplesmente o texto passar. Ou tenta novamente com um limite superior, pede ao modelo para continuar ou avisa o utilizador. O que nunca deve fazer é apresentar texto truncado como se fosse completo.
O Objeto usage — Monitorize os Seus Custos
O campo usage conta os tokens consumidos pelo pedido, separando a entrada da saída:
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
Esta distinção não é cosmética. Os modelos Mistral têm tarifas diferentes para entrada e saída. Uma funcionalidade que envia um contexto longo para receber três palavras de volta tem um perfil de custos completamente diferente de um rascunho longo gerado a partir de um prompt breve. O cálculo requer apenas algumas linhas:
# Hypothetical rates per million tokens (check current pricing)
RATE_INPUT = 2.0 # $/M tokens input
RATE_OUTPUT = 6.0 # $/M tokens output
cost_input = (usage.prompt_tokens / 1_000_000) * RATE_INPUT
cost_output = (usage.completion_tokens / 1_000_000) * RATE_OUTPUT
cost_total = cost_input + cost_output
print(f"Cost of this call: ${cost_total:.6f}")
Uma única chamada custa uma fração de cêntimo, o que é falsamente tranquilizador. Multiplique isso pelo tráfego real de uma aplicação e a questão passa a ser: qual a funcionalidade que consome o quê? Para responder a isso, agregue métricas de utilização desde a sua primeira implementação. Registe cada chamada juntamente com o nome da funcionalidade que a desencadeou:
import json
from datetime import datetime
def log_usage(response, endpoint_name: str):
"""Logs usage metrics for each API call."""
log_entry = {
"timestamp": datetime.utcnow().isoformat(),
"endpoint": endpoint_name,
"model": response.model,
"prompt_tokens": response.usage.prompt_tokens,
"completion_tokens": response.usage.completion_tokens,
"total_tokens": response.usage.total_tokens,
"finish_reason": response.choices[0].finish_reason,
"request_id": response.id
}
with open("api_usage.jsonl", "a") as f:
f.write(json.dumps(log_entry) + "\n")
# Usage
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Hello"}]
)
log_usage(response, "main_chatbot")
Um ficheiro JSONL como este, revisto após duas semanas, dir-lhe-á sem ambiguidades qual o ecrã do seu produto que mais pesa na fatura — e quantas chamadas terminam com length.
Conteúdo da Resposta
O campo content da mensagem do assistente pode assumir duas formas, exatamente como no lado do pedido:
# Simple form — string
content = response.choices[0].message.content
# "Machine learning is a branch of artificial intelligence..."
# Structured form — list of blocks (rare in standard chat)
# [{"type": "text", "text": "..."}]
Na prática, para chamadas padrão de Chat Completions, content é sempre uma cadeia de caracteres (string). A forma estruturada está reservada para respostas multimodais.
Coloque em Prática
Vamos reunir tudo isto numa função utilitária — aquela que copiará de projeto para projeto. Esta função monta as mensagens, efetua a chamada e devolve um dicionário que expõe tanto as métricas como o texto:
from mistralai.client import Mistral
def chat_complete(
client: Mistral,
prompt: str,
system: str = "",
model: str = "mistral-large-latest",
max_tokens: int = 1000
) -> dict:
"""Chat Completions call with error handling and metrics."""
messages = []
if system:
messages.append({"role": "system", "content": system})
messages.append({"role": "user", "content": prompt})
response = client.chat.complete(
model=model,
messages=messages,
max_tokens=max_tokens
)
return {
"content": response.choices[0].message.content,
"finish_reason": response.choices[0].finish_reason,
"tokens_in": response.usage.prompt_tokens,
"tokens_out": response.usage.completion_tokens,
"model": response.model,
"id": response.id
}
O ponto crucial é o que a função devolve: nunca apenas o texto. Ao propagar finish_reason, a contagem de tokens e o ID do pedido para quem chama, torna impossível o erro mais comum — tratar uma resposta cortada como válida.
Pontos-chave
- A resposta contém
choices(conteúdo),usage(tokens) e metadados (id,model) - Verifique sempre
finish_reason—lengthsignifica uma resposta incompleta usageconta os tokens de entrada e saída separadamente para um rastreio preciso de custos- Configure o registo de métricas desde a sua primeira implementação em produção
- O campo
idé essencial para depuração e suporte técnico