Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Κατανόηση της μορφής απόκρισης

Μάθημα 4 / 16 Ενημερώθηκε 30 Ιουλίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Ανατομία μιας απόκρισης
  2. Πλήρης δομή
  3. Κύρια πεδία
  4. Κατανόηση του αντικειμένου usage
  5. Χρήση εργαλείων από την πλευρά του διακομιστή
  6. Εξαγωγή κειμένου σε Python
  7. Βασικά σημεία

Ανατομία μιας απόκρισης

Όταν στέλνετε ένα αίτημα στο 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 διαιρεμένο με ένα δισεκατομμύριο δίνει το κόστος σε δολάρια