Lähe põhisisu juurde
Eesti— Vali keel
Menüü

JSON-i skeemid ja valideerimine

Õppetund 2 / 20 Arendajatele
Sellel lehel
  1. JSON-i skeemid ja valideerimine
  2. Funktsiooni skeemi struktuur
  3. Range režiim (Strict Mode)
  4. Kliendipoolne valideerimine
  5. Tõhusad kirjeldused
  6. Pesastatud skeemid ja viited
  7. Peamised punktid

JSON-i skeemid ja valideerimine

Funktsiooni skeem ei ole lihtsalt valideerimise taristu: see on ainus leping mudeli ja sinu koodi vahel. Muud kanalit pole. Mudel ei loe sinu implementatsiooni, ei tunne sinu sisemisi kokkuleppeid ja ei arva ära, et väli date eeldab ISO-vormingut, mitte prantsuse vormingut.

Kõik, mida skeemi ei kirjutata, jäetakse mudeli juhuslike järelduste hooleks. See seletab selles õppetükis soovitatud jõupingutuste tasakaalutust: parem on kulutada skeemile kümme minutit kui kaks tundi ebastabiilsete argumentide silumisele.

Funktsiooni skeemi struktuur

Iga tööriistade (tools) hulgas deklareeritud funktsioon järgib JSON Schema vormingut. Siin on täielik struktuur:

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
}

Range režiim (Strict Mode)

Range režiim muudab tõenäosuse garantiiks. Ilma selleta toodab mudel tavaliselt nõuetele vastavaid argumente – ja erandid avastad tootmises, piirjuhtudel. Sellega tagatakse vastavus juba dekodeerimise tasandil. Lülita see vaikimisi sisse: piirangud, mida see kehtestab (vt allpool), on väike hind terve veaklassi kõrvaldamise eest.

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

Range režiimi piirangud

Ranges režiimis kehtivad teatud reeglid:

  • Kõik väljad peavad olema loendis required
  • additionalProperties peab olema false
  • Valikulised tüübid kasutavad anyOf koos null-iga
  • Ülemisel tasandil ei tohi olla pattern, minLength ega maxLength
# Valikuline väli ranges režiimis
"commentaire": {
    "anyOf": [
        {"type": "string"},
        {"type": "null"}
    ],
    "description": "Optional free-text comment"
}

Kliendipoolne valideerimine

Range režiim garanteerib ainult vormi, mitte kunagi sisu. Hästi vormistatud kuupäev võib olla minevikus, õiget tüüpi identifikaator ei pruugi ühegi kliendiga sobida ja kehtiv summa võib ületada lubatud limiiti. Need reeglid on äriloogika: ükski JSON-i skeem neid ei väljenda ja need tuleb kontrollida sinu koodis – tagasilükkamise korral saada mudelile veateade, mis selgitab, mis valesti läks.

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

    # Äriloogika pärast valideerimist
    return creer_facture(**args)

Tõhusad kirjeldused

Kirjuta funktsiooni kirjeldus nagu juhised uuele kolleegile: millal seda kutsuda ja eriti millal mitte. Just teine osa unustatakse süstemaatiliselt, kuigi see lahendab enamiku valedest kutsetest – „ära kasuta arhiveeritud tellimuste puhul“ hoiab ära tarbetu päringu, mida kolm lauset positiivsest kirjeldusest poleks peatanud.

# Halb: liiga üldine
{
    "name": "get_data",
    "description": "Retrieve data"
}

# Hea: spetsiifiline ja kontekstipõhine
{
    "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."
}

Parameetrite kirjeldused

Parameetrite tasandil on vaenlane eeldus. Ühik (eurot või sendid?), vorming (ISO või kohalik?), kokkulepe (sisene ID või kliendi viide?), mida ei kirjutata, arvatakse ära – mõnikord õigesti, mõnikord mitte, ilma igasuguse signaalita. Siin on enum sinu parim tööriist: see ei kirjelda oodatavat väärtust, see piirab seda.

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

Pesastatud skeemid ja viited

Sügavalt pesastatud skeemi on sul raske uuesti läbi lugeda ja mudelil raske korrektselt täita. Kui jõuad kolme tasemeni, ei ole küsimus selles, kuidas seda paremini kirjutada, vaid kas funktsioon teeb liiga palju: kaks selge ulatusega funktsiooni on peaaegu alati eelistatavad ühele konfigureeritavale funktsioonile, mis katab mõlemad juhtumid.

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

Peamised punktid

  • Lülita sisse strict: true, et garanteerida argumentide vastavus
  • Valideeri kliendipoolselt ikka jsonschema abil ärireeglite jaoks
  • Kirjuta täpsed kirjeldused: need on peamine kvaliteedi hoob
  • Kasuta enum vastuvõetavate väärtuste piiramiseks
  • Jaota keerukad skeemid korduskasutatavateks alamstruktuurideks