Κατανόηση της μορφής απόκρισης
Σε αυτήν τη σελίδα
Ανατομία μιας απόκρισης
Όταν στέλνετε ένα αίτημα στο POST /v1/responses, ο διακομιστής της xAI επιστρέφει ένα δομημένο αντικείμενο JSON. Η κατανόηση κάθε πεδίου σε αυτό το αντικείμενο είναι απαραίτητη για τη σωστή χρήση των αποτελεσμάτων στην εφαρμογή σας.
Πλήρης δομή
Ακολουθεί μια τυπική απόκριση:
{
"id": "resp-abc123def456",
"object": "response",
"created_at": 1712000000,
"status": "completed",
"model": "grok-4.20-0309-reasoning",
"output": [
{
"type": "message",
"content": [
{
"type": "output_text",
"text": "Le machine learning est une branche de l'IA...",
"annotations": []
}
],
"status": "completed"
}
],
"usage": {
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
}
Κύρια πεδία
id
Το μοναδικό αναγνωριστικό της απόκρισης, σε μορφή resp-xxx. Θα το χρησιμοποιήσετε για να:
- Συνδέσετε συνομιλίες με το
previous_response_id - Ανακτήσετε μια αποθηκευμένη απόκριση με
GET /v1/responses/{id} - Διαγράψετε μια απόκριση με
DELETE /v1/responses/{id}
status
Η κατάσταση της απόκρισης:
| Κατάσταση | Σημασία |
|---|---|
completed | Η απόκριση δημιουργήθηκε επιτυχώς |
failed | Σφάλμα κατά τη δημιουργία |
incomplete | Η απόκριση διακόπηκε (όριο tokens, φίλτρο περιεχομένου) |
in_progress | Δημιουργία σε εξέλιξη (streaming) |
Ελέγχετε πάντα την κατάσταση πριν χρησιμοποιήσετε το περιεχόμενο της απόκρισης στον κώδικά σας.
output
Ένας πίνακας που περιέχει τα στοιχεία της απόκρισης. Κάθε στοιχείο διαθέτει ένα type:
message: Κειμενική απόκριση από το μοντέλοfunction_call: Κλήση εργαλείου που ζητήθηκε από το μοντέλο
Το κειμενικό περιεχόμενο βρίσκεται στη θέση output[0].content[0].text. Οι σημειώσεις (παραπομπές, σύνδεσμοι) βρίσκονται στον πίνακα annotations του ίδιου αντικειμένου.
usage
Πληροφορίες χρήσης, οι οποίες αναλύονται παρακάτω.
Κατανόηση του αντικειμένου usage
Το αντικείμενο usage είναι κρίσιμο για την παρακολούθηση του κόστους σας:
{
"input_tokens": 45,
"output_tokens": 180,
"total_tokens": 225,
"output_tokens_details": {
"reasoning_tokens": 120
},
"cost_in_nano_usd": 500000
}
Tokens εισόδου και εξόδου
input_tokens: Αριθμός tokens στο prompt σας (και στο ιστορικό εάν συνδέετε συνομιλίες)output_tokens: Συνολικός αριθμός παραγόμενων tokens, συμπεριλαμβανομένης της συλλογιστικήςtotal_tokens: Άθροισμα και των δύο
Tokens συλλογιστικής
Το πεδίο output_tokens_details.reasoning_tokens υποδεικνύει πόσα tokens χρησιμοποίησε το μοντέλο για την εσωτερική του συλλογιστική διαδικασία. Αυτά τα tokens χρεώνονται, αλλά δεν είναι ορατά στην κειμενική απόκριση.
Στο παραπάνω παράδειγμα, από τα 180 tokens εξόδου, τα 120 αφορούν τη συλλογιστική και μόνο τα 60 αποτελούν την ορατή απόκριση. Αυτός είναι ένας τυπικός λόγος για μοντέλα συλλογιστικής.
Κόστος σε nano-USD
Το πεδίο cost_in_nano_usd δίνει το ακριβές κόστος του αιτήματος. Η μετατροπή είναι απλή:
Κόστος σε USD = cost_in_nano_usd / 1.000.000.000
Για το παράδειγμά μας: 500000 / 1.000.000.000 = 0.0005 USD (0,0005 $).
Χρήση εργαλείων από την πλευρά του διακομιστή
Όταν το μοντέλο χρησιμοποιεί ενσωματωμένα εργαλεία, το αντικείμενο usage περιλαμβάνει επίσης:
{
"server_side_tool_usage_details": {
"web_search_calls": 2,
"code_interpreter_calls": 0,
"x_search_calls": 1,
"document_search_calls": 0,
"file_search_calls": 0,
"mcp_calls": 0
}
}
Αυτό σας επιτρέπει να γνωρίζετε ακριβώς ποια εργαλεία κλήθηκαν και πόσες φορές.
Εξαγωγή κειμένου σε Python
Ακολουθεί ένα αξιόπιστο πρότυπο για την εξαγωγή κειμενικού περιεχομένου:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Explique les listes en Python."
)
# Check status
if response.status == "completed":
text = response.output[0].content[0].text
print(text)
else:
print(f"Error: status {response.status}")
# Display usage
print(f"Tokens used: {response.usage.total_tokens}")
print(f"Cost: {response.usage.cost_in_nano_usd / 1e9:.6f} USD")
Βασικά σημεία
- Κάθε απόκριση διαθέτει ένα μοναδικό
idεπαναχρησιμοποιήσιμο για αλυσίδωση ή ανάκτηση - Ελέγχετε πάντα το
statusπριν χρησιμοποιήσετε το περιεχόμενο - Το κείμενο βρίσκεται στη θέση
output[0].content[0].text - Τα
reasoning_tokensχρεώνονται αλλά είναι αόρατα στην απόκριση - Το
cost_in_nano_usdδιαιρεμένο με ένα δισεκατομμύριο δίνει το κόστος σε δολάρια