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

Resposta e Utilização

Aula 4 de 16 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Compreenda o Que a API Devolve
  2. Anatomia Completa da Resposta
  3. O Array choices
  4. Valores de finish_reason
  5. O Objeto usage — Monitorize os Seus Custos
  6. Conteúdo da Resposta
  7. Coloque em Prática
  8. Pontos-chave

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 — length significa uma resposta incompleta
  • usage conta 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