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

Σχήματα JSON και Επικύρωση

Μάθημα 2 / 20 Για developers
Σε αυτήν τη σελίδα
  1. Σχήματα JSON και Επικύρωση
  2. Δομή Σχήματος Συνάρτησης
  3. Λειτουργία Αυστηρής Επικύρωσης (Strict Mode)
  4. Επικύρωση στην Πλευρά του Πελάτη
  5. Αποτελεσματικές Περιγραφές
  6. Ένθετα Σχήματα και Αναφορές
  7. Βασικά σημεία

Σχήματα JSON και Επικύρωση

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

Οτιδήποτε δεν είναι γραμμένο στο σχήμα θα αποφασιστεί βάσει τυχαίων συμπερασμάτων του μοντέλου. Αυτό εξηγεί την ανισορροπία προσπάθειας που προτείνεται σε αυτό το μάθημα: είναι προτιμότερο να αφιερώσετε δέκα λεπτά σε ένα σχήμα παρά δύο ώρες στην αποσφαλμάτωση ασταθών ορισμάτων.

Δομή Σχήματος Συνάρτησης

Κάθε συνάρτηση που δηλώνεται στα tools ακολουθεί τη μορφή JSON Schema. Ακολουθεί η πλήρης δομή:

tool_definition = {
    "type": "function",
    "name": "creer_facture",
    "description": "Create an invoice for an existing customer",
    "parameters": {
        "type": "object",
        "properties": {
            "client_id": {
                "type": "string",
                "description": "Unique customer identifier (format: CLI-XXXXX)"
            },
            "lignes": {
                "type": "array",
                "description": "List of billing line items",
                "items": {
                    "type": "object",
                    "properties": {
                        "description": {
                            "type": "string",
                            "description": "Product or service description"
                        },
                        "quantite": {
                            "type": "integer",
                            "minimum": 1,
                            "description": "Number of units"
                        },
                        "prix_unitaire": {
                            "type": "number",
                            "minimum": 0,
                            "description": "Unit price excluding tax in euros"
                        }
                    },
                    "required": ["description", "quantite", "prix_unitaire"]
                }
            },
            "devise": {
                "type": "string",
                "enum": ["EUR", "USD", "GBP"],
                "default": "EUR"
            },
            "echeance_jours": {
                "type": "integer",
                "enum": [30, 45, 60, 90],
                "description": "Payment deadline in days"
            }
        },
        "required": ["client_id", "lignes"],
        "additionalProperties": False
    },
    "strict": True
}

Λειτουργία Αυστηρής Επικύρωσης (Strict Mode)

Η λειτουργία strict μετατρέπει την πιθανότητα σε εγγύηση. Χωρίς αυτήν, το μοντέλο συνήθως παράγει συμμορφούμενα ορίσματα—και εσείς ανακαλύπτετε τις εξαιρέσεις στην παραγωγή, σε οριακές περιπτώσεις. Με αυτήν ενεργοποιημένη, η συμμόρφωση διασφαλίζεται εκ κατασκευής στο επίπεδο της αποκωδικοποίησης. Ενεργοποιήστε την από προεπιλογή: οι περιορισμοί που επιβάλλει, οι οποίοι λεπτομερούνται αμέσως παρακάτω, αποτελούν μικρό τίμημα για την εξάλειψη μιας ολόκληρης κατηγορίας σφαλμάτων.

tools = [{
    "type": "function",
    "name": "enregistrer_commande",
    "description": "Record a new order",
    "parameters": {
        "type": "object",
        "properties": {
            "produit": {"type": "string"},
            "quantite": {"type": "integer"},
            "urgent": {"type": "boolean"}
        },
        "required": ["produit", "quantite", "urgent"],
        "additionalProperties": False
    },
    "strict": True
}]

Περιορισμοί Λειτουργίας Αυστηρής Επικύρωσης

Στη λειτουργία strict, ισχύουν ορισμένοι κανόνες:

  • Όλα τα πεδία πρέπει να περιλαμβάνονται στο required
  • Το additionalProperties πρέπει να είναι false
  • Οι προαιρετικοί τύποι χρησιμοποιούν anyOf με null
  • Δεν επιτρέπονται pattern, minLength, maxLength στο ανώτατο επίπεδο
# Προαιρετικό πεδίο σε λειτουργία strict
"commentaire": {
    "anyOf": [
        {"type": "string"},
        {"type": "null"}
    ],
    "description": "Optional free-text comment"
}

Επικύρωση στην Πλευρά του Πελάτη

Η λειτουργία strict εγγυάται τη μορφή, ποτέ όμως το νόημα. Μια καλά δομημένη ημερομηνία μπορεί να είναι στο παρελθόν, ένα αναγνωριστικό σωστού τύπου μπορεί να μην αντιστοιχεί σε κανέναν πελάτη και ένα έγκυρο ποσό μπορεί να υπερβαίνει το επιτρεπτό όριο. Αυτοί οι κανόνες αποτελούν επιχειρηματική λογική: κανένα σχήμα JSON δεν τους εκφράζει και πρέπει να επαληθεύονται στον κώδικά σας—με, σε περίπτωση απόρριψης, την αποστολή πίσω στο μοντέλο ενός μηνύματος σφάλματος που εξηγεί τι πήγε στραβά.

import json
from jsonschema import validate, ValidationError

SCHEMA_FACTURE = {
    "type": "object",
    "properties": {
        "client_id": {"type": "string", "pattern": "^CLI-[0-9]{5}$"},
        "lignes": {
            "type": "array",
            "minItems": 1,
            "items": {
                "type": "object",
                "properties": {
                    "description": {"type": "string", "minLength": 1},
                    "quantite": {"type": "integer", "minimum": 1},
                    "prix_unitaire": {"type": "number", "minimum": 0}
                },
                "required": ["description", "quantite", "prix_unitaire"]
            }
        }
    },
    "required": ["client_id", "lignes"]
}

def executer_fonction(name: str, arguments: str) -> str:
    args = json.loads(arguments)

    try:
        validate(instance=args, schema=SCHEMA_FACTURE)
    except ValidationError as e:
        return json.dumps({"error": f"Invalid arguments: {e.message}"})

    # Επιχειρηματική λογική μετά την επικύρωση
    return creer_facture(**args)

Αποτελεσματικές Περιγραφές

Γράψτε την περιγραφή μιας συνάρτησης σαν οδηγίες για έναν νέο συνάδελφο: πότε να την καλέσει και, κυρίως, πότε να μην την καλέσει. Είναι αυτό το δεύτερο μέρος που συστηματικά ξεχνάμε, παρόλο που λύνει τις περισσότερες εσφαλμένες κλήσεις—η φράση «μην χρησιμοποιείται για αρχειοθετημένες παραγγελίες» αποτρέπει μια περιττή επανάληψη επικοινωνίας που τρεις προτάσεις θετικής περιγραφής δεν θα μπορούσαν να σταματήσουν.

# Κακό: πολύ αόριστο
{
    "name": "get_data",
    "description": "Retrieve data"
}

# Καλό: συγκεκριμένο και με πλαίσιο
{
    "name": "rechercher_produits_catalogue",
    "description": "Search for products in the e-commerce catalog. "
                   "Returns name, price, stock, and category. "
                   "Use for questions about availability or pricing."
}

Περιγραφές Παραμέτρων

Στο επίπεδο των παραμέτρων, ο εχθρός είναι το υπονοούμενο. Μια μονάδα μέτρησης (ευρώ ή λεπτά;), μια μορφή (ISO ή τοπική;), μια σύμβαση (εσωτερικό ID ή αναφορά πελάτη;) που δεν είναι γραμμένες θα μαντευτούν—κάποτε σωστά, κάποτε λάθος, χωρίς κανένα σήμα προς καμία κατεύθυνση. Το enum είναι το καλύτερο εργαλείο σας εδώ: δεν περιγράφει την αναμενόμενη τιμή, την περιορίζει.

"properties": {
    "date_debut": {
        "type": "string",
        "description": "Start date in ISO 8601 format (YYYY-MM-DD). "
                       "Defaults to today's date if not specified."
    },
    "statut": {
        "type": "string",
        "enum": ["actif", "inactif", "suspendu"],
        "description": "Filter by account status. "
                       "'actif' = accounts in service, "
                       "'suspendu' = temporarily frozen accounts."
    }
}

Ένθετα Σχήματα και Αναφορές

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

adresse_schema = {
    "type": "object",
    "properties": {
        "rue": {"type": "string"},
        "code_postal": {"type": "string"},
        "ville": {"type": "string"},
        "pays": {"type": "string", "enum": ["FR", "BE", "CH", "LU"]}
    },
    "required": ["rue", "code_postal", "ville", "pays"]
}

tools = [{
    "type": "function",
    "name": "creer_livraison",
    "description": "Create a delivery with shipping and destination addresses",
    "parameters": {
        "type": "object",
        "properties": {
            "expedition": adresse_schema,
            "destination": adresse_schema,
            "poids_kg": {"type": "number", "minimum": 0.1}
        },
        "required": ["expedition", "destination", "poids_kg"],
        "additionalProperties": False
    },
    "strict": True
}]

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

  • Ενεργοποιήστε το strict: true για να εγγυηθείτε τη συμμόρφωση των ορισμάτων
  • Επικυρώστε πάντα στην πλευρά του πελάτη με το jsonschema για τους κανόνες επιχειρηματικής λογικής
  • Γράψτε ακριβείς περιγραφές: αποτελούν τον κύριο μοχλό ποιότητας
  • Χρησιμοποιήστε το enum για να περιορίσετε τις αποδεκτές τιμές
  • Διασπάστε τα πολύπλοκα σχήματα σε επαναχρησιμοποιήσιμες υποδομές