Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

JSON-sémák és validálás

2. lecke 20 közül Fejlesztő
Ezen az oldalon
  1. JSON-sémák és validálás
  2. Függvényséma felépítése
  3. Szigorú mód (Strict Mode)
  4. Kliensoldali validálás
  5. Hatékony leírások
  6. Beágyazott sémák és hivatkozások
  7. Főbb megállapítások

JSON-sémák és validálás

A függvényséma nem csupán validálási csővezeték: ez az egyetlen szerződés a modell és a kódod között. Nincs más csatorna. A modell nem olvassa az implementációdat, nem ismeri a belső konvencióidat, és nem fogja kitalálni, hogy egy date mező ISO formátumot vár francia formátum helyett.

Bármi, ami nincs leírva a sémában, azt a modell véletlenszerű következtetései döntik el. Ez magyarázza az ebben a leckében javasolt erőfeszítés-egyensúlytalanságot: jobb tíz percet szánni a sémára, mint két órát hibakeresésre instabil argumentumok miatt.

Függvényséma felépítése

Minden, a tools listában deklarált függvény JSON-séma formátumot követ. Íme a teljes 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
}

Szigorú mód (Strict Mode)

A szigorú mód a valószínűséget garanciává változtatja. Enélkül a modell általában megfelel az elvárásoknak – és a kivételeket csak éles környezetben, szélsőséges esetekben fedezed fel. Ezzel szemben a megfelelés már a dekódolás szintjén, konstrukciós szinten biztosított. Alapértelmezetten engedélyezd: a rákényszerített kényszerek, amelyeket lentebb részletezünk, csekély árat jelentenek a hibák egy teljes osztályának kiküszöböléséért cserébe.

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

A szigorú mód kényszerei

Szigorú módban bizonyos szabályok érvényesek:

  • Minden mezőnek szerepelnie kell a required listában
  • Az additionalProperties értékének false-nak kell lennie
  • Az opcionális típusoknál anyOf-ot használj null értékkel
  • Nincs pattern, minLength, maxLength a legfelső szinten
# Opcionális mező szigorú módban
"commentaire": {
    "anyOf": [
        {"type": "string"},
        {"type": "null"}
    ],
    "description": "Optional free-text comment"
}

Kliensoldali validálás

A szigorú mód a formát, de sosem a tartalmat garantálja. Egy jól formázott dátum lehet a múltban, egy jól típusozott azonosító nem feltétlenül felel meg egyetlen ügyfélnek sem, és egy érvényes összeg túllépheti az engedélyezett limitet. Ezek üzleti logikai szabályok: egyetlen JSON-séma sem képes kifejezni őket, ezért ezeket a kódodban kell ellenőrizned – elutasítás esetén pedig hibaüzenetet küldesz vissza a modellnek, amely elmagyarázza, mi ment rosszul.

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

    # Üzleti logika a validálás után
    return creer_facture(**args)

Hatékony leírások

Írd meg a függvény leírását úgy, mint egy új kollégának szóló utasítást: mikor kell hívni, és főleg mikor nem szabad hívni. Pont ezt a második részt felejtjük el szisztematikusan, pedig ez oldja meg a téves hívások többségét – a „ne használd archivált rendeléseknél“ kitétel megelőz egy felesleges körmenetet, amit három mondatnyi pozitív leírás nem állított volna meg.

# Rossz: túl általános
{
    "name": "get_data",
    "description": "Retrieve data"
}

# Jó: specifikus és kontextusba ágyazott
{
    "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."
}

Paraméterleírások

Paraméter szinten az ellenség az implicit feltételezés. Egy mértékegység (euró vagy cent?), egy formátum (ISO vagy helyi?), egy konvenció (belső azonosító vagy ügyfélreferencia?), amit nem írsz le, azt a modell kitalálja – néha helyesen, néha nem, minden jelzés nélkül. Itt az enum a legjobb eszközöd: nem leírja a várt értéket, hanem kényszeríti azt.

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

Beágyazott sémák és hivatkozások

Egy mélyen beágyazott sémát nehéz neked is újraolvasni, és a modellnek is helyesen kitölteni. Ha eléred a három szintet, a kérdés nem az, hogyan írd meg jobban, hanem hogy a függvény nem csinál-e túl sokat: két jól körülhatárolt függvény szinte mindig előnyösebb, mint egyetlen konfigurálható függvény, amely mindkét esetet lefedi.

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

Főbb megállapítások

  • Engedélyezd a strict: true beállítást az argumentumok megfelelőségének garantálásához
  • Az üzleti szabályok miatt továbbra is végezz kliensoldali validálást jsonschema segítségével
  • Írj precíz leírásokat: ezek az elsődleges minőségi tényezők
  • Használj enum-ot az elfogadott értékek korlátozására
  • Bontsd fel a komplex sémákat újrafelhasználható alstruktúrákra