Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Format tar-risposta: id, choices, u finish_reason

Lezzjoni 8 / 12 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. L-anatomija ta’ risposta Chat Completions
  2. Struttura sħiħa tar-risposta
  3. L-array choices
  4. Valuri ta’ finish_reason
  5. Kif tittratta każijiet differenti
  6. Punti Ewlenin

Aġġornat fit-3 ta’ Novembru 2026 abbażi tar-referenza tal-API Chat Completions ta’ xAI: għal finish_reason, huma ddokumentati biss stop, length, u, fl-istreaming, end_turn jew null; il-valuri tool_calls u content_filter mill-verżjoni antika mhumiex elenkati, u s-sejħiet tal-għodod jiġu skoperti permezz ta’ message.tool_calls. max_tokens huwa deprekat favur max_completion_tokens. Sors: Chat Completions.

L-anatomija ta’ risposta Chat Completions

Kull sejħa lejn l-endpoint Chat Completions tirritorna oġġett JSON strutturat b’oqsma standardizzati. Li tifhem din l-istruttura huwa essenzjali biex testra d-data b’mod korrett, tittratta każijiet limitu, u tiddibbuggja l-integrazzjonijiet tiegħek.

id
Identifikatur uniku
choices
Array tar-risposta
usage
Għadd ta' tokens
system_fingerprint
Fingerprint tas-sistema

Struttura sħiħa tar-risposta

Hawnhekk hemm eżempju ta’ risposta tipika rritornata mill-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"
}

Oqsma fil-livell ogħla

  • id: Identifikatur uniku għat-tlestija (format chatcmpl-...). Utli għat-traċċar u d-dibbugging.
  • object: Dejjem "chat.completion". Jgħinek tiddistingwi dan it-tip ta’ risposta minn endpoints oħra.
  • created: Timestamp Unix ta’ meta nħolqot ir-risposta.
  • model: Il-mudell li ġġenera r-risposta. Jista’ jvarja ftit mill-mudell mitlub jekk tuża alias.
  • choices: Array li fih ir-risposta jew ir-risposti ġġenerati.
  • usage: Għadd ta’ tokens għall-fatturazzjoni.
  • system_fingerprint: Fingerprint tal-konfigurazzjoni tas-sistema użata.

L-array choices

Il-qasam choices huwa array li ġeneralment fih element wieħed biss (indiċi 0). Kull element fih:

  • index: Pożizzjoni fl-array (tibda minn 0)
  • message: Oġġett b’role (dejjem "assistant") u content (it-test iġġenerat)
  • finish_reason: Ir-raġuni għaliex waqfet il-ġenerazzjoni

Biex testra r-risposta tat-test:

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

Valuri ta’ finish_reason

Il-qasam finish_reason jindika għaliex il-mudell waqaf milli jiġġenera test:

stop

"finish_reason": "stop"

Il-mudell lema r-risposta tiegħu b’mod naturali. Dan huwa l-aktar każ komuni u mixtieq: il-mudell qal kollox li kellu bżonn jgħid.

length

"finish_reason": "length"

Il-ġenerazzjoni waqfet għax intlaħaq il-limitu tal-output—max_completion_tokens, li jissostitwixxi l-max_tokens issa deprekat, u jgħodd biss ir-risposta viżibbli. Għalhekk, ir-risposta hija moqtugħa: żid il-limitu jew ibda talba ta’ kontinwazzjoni.

end_turn jew null fl-istreaming

Fl-istreaming, kull biċċa intermedjarja ġġorr "end_turn" jew null f’finish_reason; biss il-biċċa finali tindika r-raġuni tal-waqfien.

X’ma tiddokumentax ir-referenza

Ir-referenza tal-API ta’ xAI tiddokumenta biss dawn il-valuri. Ma ssemmix content_filter u lanqas il-valur rritornat waqt sejħa ta’ għodda: biex tkun taf jekk il-mudell qed jitlob għodda, iċċekkja l-preżenza ta’ message.tool_calls minflok il-valur ta’ finish_reason.

Kif tittratta każijiet differenti

Fil-produzzjoni, trid tiċċekkja finish_reason biex tadatta l-imġiba tiegħek:

choice = response.choices[0]

if choice.message.tool_calls:
    # Il-mudell irid isejjaħ għodda waħda jew aktar
    for tool_call in choice.message.tool_calls:
        print(f"Tool requested: {tool_call.function.name}")

elif choice.finish_reason == "length":
    # Risposta moqtugħa: avża lill-utent jew kompli
    print(choice.message.content)
    print("[Risposta moqtugħa: żid max_completion_tokens]")

else:
    # Risposta sħiħa
    print(choice.message.content)

Punti Ewlenin

  • Ir-risposta fiha id uniku, array choices, u oġġett usage
  • It-test iġġenerat jinsab f’choices[0].message.content
  • finish_reason jindika għaliex waqfet il-ġenerazzjoni: ir-referenza tiddokumenta stop u length (u end_turn jew null fl-istreaming)
  • Iċċekkja finish_reason biex tidentifika risposti moqtugħin, u message.tool_calls għas-sejħiet tal-għodod
  • Is-system_fingerprint jidentifika l-konfigurazzjoni tas-sistema użata għall-ġenerazzjoni