Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Skemi JSON u Validazzjoni

Lezzjoni 2 / 20 Zviluppatur
F'din il-paġna
  1. Skemi JSON u Validazzjoni
  2. Struttura tal-Iskema tal-Funzjoni
  3. Modalità Stretta (Strict Mode)
  4. Validazzjoni fuq in-Naħa tal-Klijent
  5. Deskrizzjonijiet Effettivi
  6. Skemi Mbejjna u Referenzi
  7. Punti Ewlenin

Skemi JSON u Validazzjoni

Skema ta’ funzjoni mhix sempliċiment pajpijiet ta’ validazzjoni: hija l-uniku kuntratt bejn il-mudell u l-kodiċi tiegħek. M’hemm l-ebda kanal ieħor. Il-mudell ma jaqrax l-implimentazzjoni tiegħek, ma jafx il-konvenzjonijiet interni tiegħek, u ma jissuspettax li qasam date jistenna format ISO minflok format Franċiż.

Kull ma ma jkunx miktub fl-iskema jiġi deċiż mill-inferenzi każwali tal-mudell. Dan jispjega l-iżbilanc fl-isforz irrakkomandat f’din il-lezzjoni: huwa aħjar li tonfoq għaxar minuti fuq skema milli sagħtejn tiddibbuggja argumenti erratici.

Struttura tal-Iskema tal-Funzjoni

Kull funzjoni ddikjarata f’tools issegwi l-format JSON Schema. Hawnhekk hija l-istruttura sħiħa:

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
}

Modalità Stretta (Strict Mode)

Il-modalità stretta tbiddel il-probabbiltà f’garanzija. Mingħajrha, il-mudell ġeneralment jipproduċi argumenti konformi—u inti tiskopri l-eċċezzjonijiet fil-produzzjoni, fuq każijiet limitu. B’ha, il-konformità hija żgurata bil-kostruzzjoni fil-livell tad-dekodifikazzjoni. Iddendilha b’mod predefinit: il-vincoli li timponi, dettaljati eżatt hawn taħt, huma prezz żgħir biex telimina klassi sħiħa ta’ bugs.

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
}]

Vincoli tal-Modalità Stretta

Fil-modalità stretta, japplikaw ċerti regoli:

  • Il-qasam kollha għandhom ikunu f’required
  • additionalProperties għandu jkun false
  • It-tipi fakultattivi jużaw anyOf ma’ null
  • L-ebda pattern, minLength, jew maxLength fil-livell ogħla
# Qasam fakultattiv fil-modalità stretta
"commentaire": {
    "anyOf": [
        {"type": "string"},
        {"type": "null"}
    ],
    "description": "Optional free-text comment"
}

Validazzjoni fuq in-Naħa tal-Klijent

Il-modalità stretta tiggarantixxi l-forma, qatt it-tifsira. Data miktuba sew tista’ tkun fil-passat, identifikatur bit-tip korrett jista’ ma jaqbel ma’ l-ebda klijent, u ammont validu jista’ jaqbeż il-limitu awtorizzat. Dawn ir-regoli huma loġika tan-negozju: l-ebda skema JSON ma tesprimihom, u għandhom jiġu vverifikati fil-kodiċi tiegħek—b’, fil-każ ta’ rifjut, messaġġ ta’ żball mibgħut lura lill-mudell li jispjega x’mara ħażin.

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}"})

    # Loġika tan-negozju wara l-validazzjoni
    return creer_facture(**args)

Deskrizzjonijiet Effettivi

Ikteb deskrizzjoni ta’ funzjoni bħal struzzjonijiet għal kollega ġdid: meta ssejjaħha, u speċjalment meta ma ssejjaħhiex. Hija dik it-tieni parti li ninsu sistematikament, madankollu hija ssolvi l-biċċa l-kbira tas-sejħiet żbaljati—“tużax għal ordnijiet arkvjati” tipprevjeni vjaġġ mhux meħtieġ li tliet sentenzi ta’ deskrizzjoni pożittiva ma kinux iwaqqfu.

# Ħażin: wisq vag
{
    "name": "get_data",
    "description": "Retrieve data"
}

# Tajjeb: speċifiku u kuntestwali
{
    "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."
}

Deskrizzjonijiet tal-Parametri

Fil-livell tal-parametru, l-għadu huwa l-impliċitu. Unità (ewro jew ċenteżmi?), format (ISO jew lokali?), konvenzjoni (ID intern jew referenza tal-klijent?) li ma jkunux miktuba jiġu ssuspettati—xi kultant korrettament, xi kultant le, mingħajr l-ebda sinjal fiż-żewġ direzzjonijiet. L-enum huwa l-aħjar għodda tiegħek hawn: ma jiddeskrivix il-valur mistenni, iżda jillimitah.

"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."
    }
}

Skemi Mbejjna u Referenzi

Skema mbejjna fil-fond hija diffiċli biex terġa’ taqraha int u biex il-mudell jimliha korrettament. Jekk tilħaq tliet livelli, il-mistoqsija li għandek tagħmel mhix kif tiktebha aħjar iżda jekk il-funzjoni qed tagħmilx wisq: żewġ funzjonijiet b’ambitu ċar huma kważi dejjem preferibbli għal funzjoni waħda konfigurabbli li tkopri ż-żewġ każijiet.

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
}]

Punti Ewlenin

  • Iddendil strict: true biex tiggarantixxi l-konformità tal-argumenti
  • Xorta valida fuq in-naħa tal-klijent b’jsonschema għar-regoli tan-negozju
  • Ikteb deskrizzjonijiet preċiżi: huma l-leva primarja tal-kwalità
  • Uża enum biex tillimita l-valuri aċċettati
  • Aqsam skemi kumplessi f’sotto-strutturi li jistgħu jerġgħu jintużaw