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

Formato da resposta: id, choices e finish_reason

Aula 8 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Anatomia de uma resposta Chat Completions
  2. Estrutura completa da resposta
  3. A matriz choices
  4. Valores de finish_reason
  5. Gestão de diferentes casos
  6. Pontos-chave

Atualizado a 3 de novembro de 2026 com base na referência da API Chat Completions da xAI: apenas stop, length e, em streaming, end_turn ou null estão documentados para finish_reason; os valores tool_calls e content_filter da versão anterior não constam na lista, e as chamadas de ferramentas são detetadas através de message.tool_calls. max_tokens está obsoleto em favor de max_completion_tokens. Fonte: Chat Completions.

Anatomia de uma resposta Chat Completions

Cada chamada ao endpoint Chat Completions devolve um objeto JSON estruturado com campos padronizados. Compreender esta estrutura é essencial para extrair dados corretamente, gerir casos limite e depurar as suas integrações.

id
Identificador único
choices
Matriz de respostas
usage
Contadores de tokens
system_fingerprint
Impressão digital do sistema

Estrutura completa da resposta

Eis um exemplo de uma resposta típica devolvida pela API:

{
  "id": "chatcmpl-abc123xyz",
  "object": "chat.completion",
  "created": 1712345678,
  "model": "grok-4.20-0309-reasoning",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Deep learning is a branch of machine learning..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 156,
    "total_tokens": 198
  },
  "system_fingerprint": "fp_abc123"
}

Campos de nível superior

  • id: Identificador único da conclusão (formato chatcmpl-...). Útil para rastreio e depuração.
  • object: Sempre "chat.completion". Permite distinguir este tipo de resposta de outros endpoints.
  • created: Timestamp Unix do momento em que a resposta foi criada.
  • model: O modelo que gerou a resposta. Pode diferir ligeiramente do modelo solicitado se utilizar um alias.
  • choices: Matriz que contém a resposta ou respostas geradas.
  • usage: Contadores de tokens para faturação.
  • system_fingerprint: Impressão digital da configuração do sistema utilizada.

A matriz choices

O campo choices é uma matriz que geralmente contém um único elemento (índice 0). Cada elemento contém:

  • index: Posição na matriz (começa em 0)
  • message: Objeto com role (sempre "assistant") e content (o texto gerado)
  • finish_reason: O motivo pelo qual a geração parou

Para extrair a resposta de texto:

# Python
response_text = response.choices[0].message.content
// JavaScript
const responseText = response.choices[0].message.content;

Valores de finish_reason

O campo finish_reason indica por que motivo o modelo parou de gerar texto:

stop

"finish_reason": "stop"

O modelo concluiu a sua resposta naturalmente. Este é o caso mais comum e desejável: o modelo disse tudo o que tinha a dizer.

length

"finish_reason": "length"

A geração parou porque o limite de saída foi atingido — max_completion_tokens, que substitui o agora obsoleto max_tokens, e conta apenas a resposta visível. A resposta está, portanto, truncada: aumente o limite ou reinicie um pedido de continuação.

end_turn ou null em streaming

Em streaming, cada bloco intermédio transporta "end_turn" ou null em finish_reason; apenas o bloco final indica o motivo da paragem.

O que a referência não documenta

A referência da API da xAI documenta apenas estes valores. Não menciona nem content_filter nem o valor devolvido durante uma chamada de ferramenta: para saber se o modelo solicita uma ferramenta, verifique a presença de message.tool_calls em vez do valor de finish_reason.

Gestão de diferentes casos

Em produção, deve verificar finish_reason para adaptar o seu comportamento:

choice = response.choices[0]

if choice.message.tool_calls:
    # O modelo quer chamar uma ou mais ferramentas
    for tool_call in choice.message.tool_calls:
        print(f"Tool requested: {tool_call.function.name}")

elif choice.finish_reason == "length":
    # Resposta truncada: notificar o utilizador ou continuar
    print(choice.message.content)
    print("[Truncated response: increase max_completion_tokens]")

else:
    # Resposta completa
    print(choice.message.content)

Pontos-chave

  • A resposta contém um id único, uma matriz choices e um objeto usage
  • O texto gerado encontra-se em choices[0].message.content
  • finish_reason indica por que motivo a geração parou: a referência documenta stop e length (e end_turn ou null em streaming)
  • Verifique finish_reason para detetar respostas truncadas e message.tool_calls para chamadas de ferramentas
  • O system_fingerprint identifica a configuração do sistema utilizada para a geração