Σχήματα JSON και Περιγραφές
Σε αυτήν τη σελίδα
Η Γλώσσα των Εργαλείων: Σχήμα JSON
Για να καλέσει το Grok τις συναρτήσεις σας, πρέπει να γνωρίζει τι κάνουν και ποιες παραμέτρους αναμένουν. Αυτός είναι ο ρόλος των σχημάτων JSON. Κάθε εργαλείο περιγράφεται από ένα δομημένο αντικείμενο που περιέχει τρία βασικά στοιχεία: ένα όνομα, μια περιγραφή και ένα σχήμα παραμέτρων.
Ανατομία ενός Ορισμού Εργαλείου
Ακολουθεί η πλήρης δομή ενός εργαλείου όπως την αναμένει το API του Grok:
{
"type": "function",
"name": "get_weather",
"description": "Get the current weather for a given city",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city name (e.g., Paris, Lyon)"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"default": "celsius"
}
},
"required": ["city"]
}
}
Ας αναλύσουμε κάθε πεδίο:
Το Πεδίο type
Είναι πάντα "function" για προσαρμοσμένες συναρτήσεις. Υπάρχουν άλλοι τύποι για ενσωματωμένα εργαλεία (web_search, code_interpreter), αλλά για τις δικές σας συναρτήσεις, είναι αναπόφευκτα "function".
Το Πεδίο name
Το τεχνικό όνομα της συνάρτησής σας. Πρέπει να είναι:
- Μοναδικό μεταξύ όλων των εργαλείων στο αίτημα
- Περιγραφικό:
get_weatherαντί γιαfn1 - Σε snake_case κατά σύμβαση:
search_products,create_ticket - Σύντομο αλλά σαφές: το μοντέλο χρησιμοποιεί αυτό το όνομα για να αποφασίσει ποιο εργαλείο θα καλέσει
Το Πεδίο description
Αυτό είναι το πιο σημαντικό πεδίο για την ποιότητα της κλήσης. Το μοντέλο βασίζεται κυρίως στην περιγραφή για να αποφασίσει πότε και πώς θα χρησιμοποιήσει ένα εργαλείο. Μια καλή περιγραφή:
- Εξηγεί τι κάνει η συνάρτηση σε μία πρόταση
- Καθορίζει πότε να τη χρησιμοποιήσετε (αν δεν είναι προφανές)
- Αναφέρει οριακές περιπτώσεις εάν είναι απαραίτητο
Συγκρίνετε αυτές τις δύο περιγραφές:
❌ "Καιρός"
✅ "Λάβετε τον τρέχοντα καιρό για μια πόλη. Επιστρέφει τη θερμοκρασία, την υγρασία και τις συνθήκες."
Η δεύτερη παρέχει στο μοντέλο αρκετό πλαίσιο για να γνωρίζει ακριβώς πότε να καλέσει αυτή τη συνάρτηση και τι θα λάβει σε επιστροφή.
Το Μπλοκ parameters
Οι παράμετροι ακολουθούν τη μορφή JSON Schema. Οι υποστηριζόμενοι τύποι περιλαμβάνουν:
string— συμβολοσειρές χαρακτήρωνnumber/integer— αριθμοίboolean— true/falsearray— λίστεςobject— ένθετα αντικείμεναenum— λίστα επιτρεπόμενων τιμών
Ο πίνακας required αναφέρει τις υποχρεωτικές παραμέτρους. Οι υπόλοιπες είναι προαιρετικές — το μοντέλο μπορεί να επιλέξει να τις παραλείψει.
Περιγραφές Παραμέτρων
Κάθε παράμετρος πρέπει να έχει τη δική της description. Αυτό επιτρέπει στο μοντέλο να κατανοήσει ποια τιμή να περάσει:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Χωρίς περιγραφή, το μοντέλο πρέπει να μαντέψει την αναμενόμενη μορφή — κάτι που οδηγεί σε σφάλματα.
Προηγμένες Παράμετροι
Enums για Περιορισμό Τιμών
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Τα enums είναι ιδιαίτερα χρήσιμα: λένε στο μοντέλο τις ακριβείς τιμές που μπορεί να χρησιμοποιήσει, εξαλείφοντας τα σφάλματα μορφής.
Προεπιλεγμένες Τιμές
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Το μοντέλο κατανοεί ότι μπορεί να παραλείψει αυτή την παράμετρο εάν η προεπιλεγμένη τιμή λειτουργεί.
Ένθετα Αντικείμενα
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Βέλτιστες Πρακτικές για Περιγραφές
Η περιγραφή είναι το μοναδικό κανάλι μέσω του οποίου το μοντέλο κατανοεί το εργαλείο σας — κάθε λέξη μετράει. Προτεραιότητα η εξειδίκευση: η φράση «Αναζήτηση προϊόντων κατά όνομα ή κατηγορία στον κατάλογο» λέει στο μοντέλο ακριβώς πότε εφαρμόζεται αυτό το εργαλείο, ενώ η φράση «Αναζήτηση προϊόντων» το αφήνει να μαντέψει. Στη συνέχεια οι μορφές: ο καθορισμός «Ημερομηνία σε μορφή ISO 8601 (YYYY-MM-DD)» στην περιγραφή μιας παραμέτρου εξαλείφει τα μισά σφάλματα ορισμάτων, επειδή το μοντέλο αντιγράφει τη μορφή που του δείχνετε. Τα όρια αποτελούν μέρος της σύμβασης: το «Μέγιστο 50 αποτελέσματα ανά κλήση» εμποδίζει το μοντέλο να υποσχεθεί στον χρήστη πληρότητα που το εργαλείο δεν μπορεί να παρέχει. Και η περιγραφή της επιστροφής — «Επιστρέφει ένα αντικείμενο με τιμή, διαθεσιμότητα και περιγραφή» — βοηθά το μοντέλο να σχεδιάσει εκ των προτέρων: γνωρίζει τι θα έχει στη διάθεσή του πριν καν καλέσει.
Βασικά σημεία
- Κάθε εργαλείο ορίζεται από ένα
name, μιαdescriptionκαιparameters - Η περιγραφή είναι ο νούμερο ένα παράγοντας στην ποιότητα της κλήσης — επενδύστε χρόνο σε αυτήν
- Τα ονόματα πρέπει να είναι μοναδικά και σε snake_case
- Χρησιμοποιήστε
enumγια να περιορίσετε τις πιθανές τιμές - Κάθε παράμετρος πρέπει να έχει τη δική της περιγραφή με την αναμενόμενη μορφή
- Ο πίνακας
requiredδιακρίνει τις υποχρεωτικές παραμέτρους από τις προαιρετικές