Μορφή απόκρισης: id, choices και finish_reason
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 3 Νοεμβρίου 2026 με βάση την αναφορά API Chat Completions της xAI: για το πεδίο
finish_reasonτεκμηριώνονται μόνο οι τιμέςstop,lengthκαι, κατά τη ροή δεδομένων (streaming),end_turnήnull. Οι τιμέςtool_callsκαιcontent_filterαπό την παλαιότερη έκδοση δεν αναφέρονται, ενώ οι κλήσεις εργαλείων εντοπίζονται μέσω τουmessage.tool_calls. Τοmax_tokensέχει καταργηθεί υπέρ τουmax_completion_tokens. Πηγή: Chat Completions.
Δομή μιας απόκρισης Chat Completions
Κάθε κλήση στο σημείο τελικού χρήστη (endpoint) Chat Completions επιστρέφει ένα αντικείμενο JSON δομημένο με τυποποιημένα πεδία. Η κατανόηση αυτής της δομής είναι απαραίτητη για την ορθή εξαγωγή δεδομένων, τη διαχείριση οριακών περιπτώσεων και την αποσφαλμάτωση των ενσωματώσεών σας.
Πλήρης δομή απόκρισης
Ακολουθεί ένα παράδειγμα μιας τυπικής απόκρισης που επιστρέφεται από το 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"
}
Πεδία ανώτατου επιπέδου
id: Μοναδικό αναγνωριστικό για την ολοκλήρωση (μορφήchatcmpl-...). Χρήσιμο για την παρακολούθηση και την αποσφαλμάτωση.object: Πάντα"chat.completion". Σας επιτρέπει να διακρίνετε αυτόν τον τύπο απόκρισης από άλλα σημεία τελικού χρήστη.created: Χρονική σφραγίδα Unix της στιγμής δημιουργίας της απόκρισης.model: Το μοντέλο που παρήγαγε την απόκριση. Ενδέχεται να διαφέρει ελαφρώς από το ζητούμενο μοντέλο εάν χρησιμοποιείτε ψευδώνυμο.choices: Πίνακας που περιέχει την παραγόμενη απόκριση ή τις αποκρίσεις.usage: Μετρητές token για τη χρέωση.system_fingerprint: Αποτύπωμα της διαμόρφωσης συστήματος που χρησιμοποιήθηκε.
Ο πίνακας choices
Το πεδίο choices είναι ένας πίνακας που συνήθως περιέχει ένα μόνο στοιχείο (δείκτης 0). Κάθε στοιχείο περιλαμβάνει:
index: Θέση στον πίνακα (ξεκινά από το 0)message: Αντικείμενο μεrole(πάντα"assistant") καιcontent(το παραγόμενο κείμενο)finish_reason: Ο λόγος διακοπής της παραγωγής
Για να εξάγετε την απόκριση κειμένου:
# Python
response_text = response.choices[0].message.content
// JavaScript
const responseText = response.choices[0].message.content;
Τιμές του finish_reason
Το πεδίο finish_reason υποδεικνύει γιατί το μοντέλο σταμάτησε να παράγει κείμενο:
stop
"finish_reason": "stop"
Το μοντέλο ολοκλήρωσε την απόκρισή του φυσικά. Αυτή είναι η πιο συνηθισμένη και επιθυμητή περίπτωση: το μοντέλο είπε ό,τι χρειαζόταν να πει.
length
"finish_reason": "length"
Η παραγωγή σταμάτησε επειδή επιτεύχθηκε το όριο εξόδου—max_completion_tokens, το οποίο αντικαθιστά το πλέον καταργημένο max_tokens και μετρά μόνο την ορατή απόκριση. Επομένως, η απόκριση είναι περικομμένη: αυξήστε το όριο ή ξεκινήστε εκ νέου ένα αίτημα συνέχισης.
end_turn ή null κατά τη ροή δεδομένων (streaming)
Κατά τη ροή δεδομένων, κάθε ενδιάμεσο τμήμα (chunk) φέρει την τιμή "end_turn" ή null στο finish_reason· μόνο το τελικό τμήμα υποδεικνύει τον λόγο διακοπής.
Τι δεν τεκμηριώνει η αναφορά
Η αναφορά API της xAI τεκμηριώνει μόνο αυτές τις τιμές. Δεν αναφέρει ούτε το content_filter ούτε την τιμή που επιστρέφεται κατά την κλήση εργαλείου: για να διαπιστώσετε αν το μοντέλο ζητά ένα εργαλείο, ελέγξτε την παρουσία του message.tool_calls και όχι την τιμή του finish_reason.
Διαχείριση διαφορετικών περιπτώσεων
Σε περιβάλλον παραγωγής, πρέπει να ελέγχετε το finish_reason για να προσαρμόζετε τη συμπεριφορά σας:
choice = response.choices[0]
if choice.message.tool_calls:
# Το μοντέλο θέλει να καλέσει ένα ή περισσότερα εργαλεία
for tool_call in choice.message.tool_calls:
print(f"Tool requested: {tool_call.function.name}")
elif choice.finish_reason == "length":
# Περικομμένη απόκριση: ειδοποιήστε τον χρήστη ή συνεχίστε
print(choice.message.content)
print("[Περικομμένη απόκριση: αυξήστε το max_completion_tokens]")
else:
# Πλήρης απόκριση
print(choice.message.content)
Βασικά σημεία
- Η απόκριση περιέχει ένα μοναδικό
id, έναν πίνακαchoicesκαι ένα αντικείμενοusage - Το παραγόμενο κείμενο βρίσκεται στο
choices[0].message.content - Το
finish_reasonυποδεικνύει γιατί σταμάτησε η παραγωγή: η αναφορά τεκμηριώνει ταstopκαιlength(καθώς καιend_turnήnullκατά τη ροή δεδομένων) - Ελέγξτε το
finish_reasonγια να εντοπίσετε περικομμένες αποκρίσεις και τοmessage.tool_callsγια κλήσεις εργαλείων - Το
system_fingerprintπροσδιορίζει τη διαμόρφωση συστήματος που χρησιμοποιήθηκε για την παραγωγή