Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

JSON schemos ir validavimas

Paskaita 2 iš 20 Kūrėjas
Šiame puslapyje
  1. JSON schemos ir validavimas
  2. Funkcijos schemos struktūra
  3. Griežtas režimas (Strict Mode)
  4. Kliento pusės validavimas
  5. Efektyvūs aprašymai
  6. Įdėtosios schemos ir nuorodos
  7. Svarbiausi punktai

JSON schemos ir validavimas

Funkcijos schema nėra tik techninis validavimo mechanizmas: tai vienintelė sutartis tarp modelio ir tavo kodo. Kitų kanalų nėra. Modelis neskaito tavo implementacijos, nežino tavo vidinių konvencijų ir nesuspės, kad laukas date tikisi ISO formato, o ne prancūziško.

Viskas, kas neparašyta schemoje, bus nuspręsta pagal atsitiktines modelio išvadas. Tai paaiškina šioje pamokoje rekomenduojamą pastangų disbalansą: geriau dešimt minučių skirti schemai nei dviem valandoms derinti nestabilus argumentus.

Funkcijos schemos struktūra

Kiekviena funkcija, deklaruota tools, laikosi JSON Schema formato. Štai pilna struktūra:

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
}

Griežtas režimas (Strict Mode)

Griežtas režimas tikimybę paverčia garantija. Be jo modelis dažniausiai generuoja tinkamus argumentus – ir tu išimtis atrandi gamyboje, kraštutiniais atvejais. Su juo atitiktis užtikrinama jau dekoduavimo lygmenyje. Įjunk jį pagal nutylėjimą: jo nustatomi apribojimai, aprašyti žemiau, yra maža kaina, mokama norint pašalinti целą klaidų klasę.

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

Griežto režimo apribojimai

Griežtu režimu galioja tam tikros taisyklės:

  • Visi laukai privalo būti sąraše required
  • additionalProperties privalo būti false
  • Neprivalomi tipai naudoja anyOf su null
  • Viršutiniame lygmenyje negalima naudoti pattern, minLength, maxLength
# Neprivalomas laukas griežtu režimu
"commentaire": {
    "anyOf": [
        {"type": "string"},
        {"type": "null"}
    ],
    "description": "Optional free-text comment"
}

Kliento pusės validavimas

Griežtas režimas garantuoja formą, bet niekada prasmę. Teisingai suformuota data gali būti praeityje, teisingo tipo identifikatorius gali neatitikti jokio kliento, o galiojanti suma gali viršyti leistiną limitą. Tai verslo logikos taisyklės: jokia JSON schema jų neišreiškia, todėl jas reikia tikrinti tavo kode – o atmetus prašymą, modeliui siųsti klaidos žinutę, paaiškinančią, kas nutiko.

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

    # Verslo logika po validavimo
    return creer_facture(**args)

Efektyvūs aprašymai

Funkcijos aprašymą rašyk kaip instrukciją naujam kolegai: kada ją kviesti ir, svarbiausia, kada nekviesti. Būtent antrąją dalį sistemingai pamirštame, nors ji išsprendžia daugumą klaidingų kvietimų – „nenaudoti archyvuotiems užsakymams“ sustabdo nereikalingą užklausą, kurios nebūtų sustabdę trys teigiamo aprašymo sakiniai.

# Blogai: per daug bendra
{
    "name": "get_data",
    "description": "Retrieve data"
}

# Gerai: specifiska ir kontekstualu
{
    "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."
}

Parametrų aprašymai

Parametrų lygmenyje priešas yra numanymas. Vienetas (eurai ar centai?), formatas (ISO ar vietinis?), konvencija (vidinis ID ar kliento nuoroda?), kurie neparašyti, bus spėjami – kartais teisingai, kartais ne, ir jokio signalo apie tai nebus. Čia enum yra tavo geriausias įrankis: jis neapibūdina tikėtinos reikšmės, ją apriboja.

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

Įdėtosios schemos ir nuorodos

Giliai įdėta schema sunkiai perskaitoma tau ir sunkiai užpildoma modeliui. Jei pasieki tris lygmenis, klausk ne kaip tai geriau parašyti, o ar funkcija neatlieka per daug: dvi funkcijos su aiškia apimtimi beveik visada geriau nei viena konfigūruojama funkcija, apimanti abu atvejus.

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

Svarbiausi punktai

  • Įjunk strict: true, kad garantuotum argumentų atitiktį
  • Vis tiek validuok kliento pusėje naudodamas jsonschema verslo taisyklėms
  • Rašyk tikslius aprašymus: tai pagrindinis kokybės svertas
  • Naudok enum, kad apribotum priimtinas reikšmes
  • Sudėtingas schemas skaidyk į pakartotinai naudojamas postruktūras