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

Ορισμός Συναρτήσεων με JSON Schema

Μάθημα 3 / 14 Ενημερώθηκε 29 Ιουλίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Η σύμβαση μεταξύ του κώδικά σας και του μοντέλου
  2. Ανατομία μιας προδιαγραφής εργαλείου
  3. Υποστηριζόμενοι τύποι JSON Schema
  4. Πλήρες παράδειγμα: δύο συμπληρωματικές συναρτήσεις
  5. Υποχρεωτικές έναντι προαιρετικών παραμέτρων
  6. Βέλτιστες πρακτικές για περιγραφές
  7. Βασικά σημεία

Η σύμβαση μεταξύ του κώδικά σας και του μοντέλου

Για να καλέσει το μοντέλο Mistral τις συναρτήσεις σας, πρέπει να γνωρίζει τι υπάρχει και πώς να το χρησιμοποιήσει. Αυτός είναι ο ρόλος του JSON Schema: μια τυποποιημένη μορφή που περιγράφει κάθε συνάρτηση—το όνομά της, τι κάνει, ποιες παραμέτρους αναμένει και ποιες από αυτές είναι υποχρεωτικές.

Κρατήστε ένα πράγμα στο μυαλό σας καθ’ όλη τη διάρκεια αυτού του μαθήματος: το μοντέλο δεν βλέπει ποτέ τον κώδικα Python σας. Βλέπει μόνο αυτή την προδιαγραφή. Αν η συνάρτησή σας διαχειρίζεται κομψά τα πεζά αναγνωριστικά (IDs) αλλά το schema δεν το αναφέρει, το μοντέλο αγνοεί αυτή τη δυνατότητα. Όσο πιο ακριβές και καλά τεκμηριωμένο είναι το schema σας, τόσο πιο ακριβή θα είναι τα παραγόμενα ορίσματα.

Ανατομία μιας προδιαγραφής εργαλείου

Κάθε εργαλείο που αποστέλλεται στο API της Mistral ακολουθεί την ίδια δομή:

tool = {
    "type": "function",
    "function": {
        "name": "function_name",
        "description": "Clear description of what the function does",
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Parameter description"
                },
                "param2": {
                    "type": "integer",
                    "description": "Parameter description"
                }
            },
            "required": ["param1"]
        }
    }
}
ΠεδίοΡόλος
typeΠάντα "function" (άλλοι τύποι ενδέχεται να υπάρξουν στο μέλλον)
function.nameΤο ακριβές όνομα της συνάρτησης Python σας—αυτό επιστρέφει το μοντέλο στα tool_calls
function.descriptionΜια σαφής πρόταση που βοηθά το μοντέλο να επιλέξει τη σωστή συνάρτηση
function.parametersΈνα αντικείμενο JSON Schema που περιγράφει τις αναμενόμενες παραμέτρους
requiredΗ λίστα των υποχρεωτικών παραμέτρων

Υποστηριζόμενοι τύποι JSON Schema

Το λεξιλόγιο τύπων που διατίθεται για την περιγραφή παραμέτρων είναι σκόπιμα περιορισμένο και κάθε τύπος καθοδηγεί το μοντέλο με διαφορετικό τρόπο. Ένα enum, ειδικότερα, κάνει περισσότερα από το να τεκμηριώνει: κλείνει την πόρτα σε εφευρεμένες τιμές.

# String — ελεύθερο κείμενο ή περιορισμένο
{"type": "string", "description": "Transaction ID"}

# String με enum — περιορισμένες τιμές
{"type": "string", "enum": ["asc", "desc"], "description": "Sort order"}

# Integer — ακέραιος αριθμός
{"type": "integer", "description": "Number of results to return"}

# Number — δεκαδικός αριθμός
{"type": "number", "description": "Amount in euros"}

# Boolean — true/false
{"type": "boolean", "description": "Include canceled transactions"}

# Array — λίστα τιμών
{
    "type": "array",
    "items": {"type": "string"},
    "description": "List of transaction IDs"
}

# Object — ένθετο αντικείμενο
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Shipping address"
}

Διακρίνετε ξεκάθαρα μεταξύ integer και number: ένα ποσό σε ευρώ όπως 125,50 απαιτεί number, ενώ ένας αριθμός αποτελεσμάτων προς επιστροφή είναι integer. Η δήλωση ενός ποσού ως integer θα προκαλέσει στο μοντέλο να το στρογγυλοποιήσει.

Πλήρες παράδειγμα: δύο συμπληρωματικές συναρτήσεις

Ακολουθεί ένα ρεαλιστικό παράδειγμα με δύο συναρτήσεις σχετικές με πληρωμές, εμπνευσμένο από την επίσημη τεκμηρίωση της Mistral:

tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Retrieves the status of a payment (paid, pending, failed) "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_date",
            "description": "Retrieves the date when a payment was made "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

Και οι δύο συναρτήσεις αναμένουν ακριβώς την ίδια παράμετρο, την transaction_id, ωστόσο το μοντέλο πρέπει να επιλέξει ανάμεσά τους. Αυτή η επιλογή βασίζεται αποκλειστικά στην περιγραφή της συνάρτησης. Το «Πραγματοποιήθηκε αυτή η πληρωμή;» αντιστοιχεί στο retrieve_payment_status· το «Πότε έγινε;» αντιστοιχεί στο retrieve_payment_date. Αν είχατε γράψει δύο αόριστες, εναλλάξιμες περιγραφές, το μοντέλο θα έκανε λάθος τις μισές φορές—και θα κατηγορούσατε το μοντέλο ενώ το σφάλμα βρίσκεται στο schema.

Υποχρεωτικές έναντι προαιρετικών παραμέτρων

Η διάκριση μεταξύ υποχρεωτικών και προαιρετικών παραμέτρων καθορίζει τι επιτρέπεται να παραλείψει το μοντέλο.

{
    "type": "function",
    "function": {
        "name": "search_transactions",
        "description": "Searches for transactions based on various criteria",
        "parameters": {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string",
                    "enum": ["paid", "pending", "failed"],
                    "description": "Filter by payment status"
                },
                "date_from": {
                    "type": "string",
                    "description": "Start date in YYYY-MM-DD format"
                },
                "date_to": {
                    "type": "string",
                    "description": "End date in YYYY-MM-DD format"
                },
                "min_amount": {
                    "type": "number",
                    "description": "Minimum amount in euros"
                }
            },
            "required": ["status"]
        }
    }
}

Εδώ, μόνο το status είναι υποχρεωτικό· οι άλλες παράμετροι συμπεριλαμβάνονται μόνο αν τις αναφέρει ο χρήστης. Συγκρίνετε δύο διατυπώσεις. Για το «Εμφάνισε τις αποτυχημένες πληρωμές», το μοντέλο παράγει απλώς {"status": "failed"}. Για το «Εμφάνισε τις αποτυχημένες πληρωμές από τον Μάρτιο του 2026», προσθέτει μόνο του τα date_from και date_to. Το να καθορίζατε αυτές τις ημερομηνίες ως υποχρεωτικές θα είχε χαλάσει το πρώτο ερώτημα ή, χειρότερα, θα είχε ωθήσει το μοντέλο να εφεύρει ένα εύρος ημερομηνιών.

Βέλτιστες πρακτικές για περιγραφές

Η ποιότητα της περιγραφής επηρεάζει άμεσα την ακρίβεια του μοντέλου. Τα παρακάτω αντιπαραδείγματα είναι πιο διδακτικά από οποιονδήποτε αφηρημένο κανόνα.

# Κακό — πολύ αόριστο
{"description": "Retrieves data"}

# Καλό — ακριβές και contextual
{"description": "Retrieves the status of a payment (paid, pending, failed) "
                "based on the unique transaction ID"}

# Κακό — χωρίς περιγραφή για την παράμετρο
{"transaction_id": {"type": "string"}}

# Καλό — περιγραφή με παράδειγμα
{"transaction_id": {
    "type": "string",
    "description": "Unique transaction ID (format: T followed by 4 digits, e.g., T1001)"
}}

Μια καλή περιγραφή δηλώνει σε μία πρόταση τι κάνει η συνάρτηση, καθορίζει την αναμενόμενη μορφή για κάθε παράμετρο και παρέχει ένα παράδειγμα όποτε αυτή η μορφή δεν είναι προφανής—το T1001 είναι καλύτερο από το «αναγνωριστικό συναλλαγής». Όταν οι πιθανές τιμές είναι περιορισμένες, μην τις περιγράφετε με πεζό κείμενο: δηλώστε τες με enum. Αυτός είναι ο μόνος τρόπος για να τις καταστήσετε δεσμευτικές.

Βασικά σημεία

  • Το JSON Schema είναι η σύμβαση μεταξύ του κώδικά σας και του μοντέλου—περιγράφει τις συναρτήσεις σας χωρίς να εκθέτει τον κώδικα
  • Κάθε εργαλείο διαθέτει ένα name, μια description και typed parameters
  • Οι υποστηριζόμενοι τύποι περιλαμβάνουν string, integer, number, boolean, array και object
  • Η λίστα required διακρίνει τις υποχρεωτικές παραμέτρους από τις προαιρετικές
  • Οι ακριβείς περιγραφές με παραδείγματα βελτιώνουν σημαντικά την ακρίβεια του μοντέλου