Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

JSON shēmas un validācija

Nodarbība 2 no 20 Programmētājs
Šajā lapā
  1. JSON shēmas un validācija
  2. Funkcijas shēmas struktūra
  3. Stingrais režīms (Strict Mode)
  4. Klienta puses validācija
  5. Efektīvi apraksti
  6. Ligzdotās shēmas un atsauces
  7. Galvenās atziņas

JSON shēmas un validācija

Funkcijas shēma nav tikai validācijas cauruļvads: tā ir vienīgais līgums starp modeli un tavu kodu. Cita kanāla nav. Modelis nelasa tavu implementāciju, nezina tavas iekšējās konvencijas un neuzminēs, ka lauks date sagaida ISO formātu, nevis franču formātu.

Viss, kas nav uzrakstīts shēmā, tiks noteikts pēc modeļa nejaušām secinājumiem. Tas izskaidro šajā nodarbībā ieteicamo pūļu nelīdzsvarotību: ir labāk pavadīt desmit minūtes, veidojot shēmu, nekā divas stundas atkļūdot nestabilus argumentus.

Funkcijas shēmas struktūra

Katra funkcija, kas deklarēta tools, atbilst JSON shēmas formātam. Lūk, pilnā 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
}

Stingrais režīms (Strict Mode)

Stingrais režīms pārvērš varbūtību garantijā. Bez tā modelis parasti ģenerē atbilstošus argumentus, un tu uzzini par izņēmumiem tikai ražošanas vidē, apstrādājot robežgadījumus. Ar to atbilstība tiek nodrošināta jau dekodēšanas līmenī. Aktivizē to pēc noklusējuma: ierobežojumi, ko tas uzliek (detalizēti aprakstīti tālāk), ir maza cena, lai novērstu veselu kļūdu klasi.

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

Stingrā režīma ierobežojumi

Stingrajā režīmā ir spēkā noteikti noteikumi:

  • Visiem laukiem jābūt norādītiem required
  • additionalProperties ir jābūt false
  • Neobligātie tipi izmanto anyOf kopā ar null
  • Augšējā līmenī nav atļauts izmantot pattern, minLength, maxLength
# Neobligāts lauks stingrajā režīmā
"commentaire": {
    "anyOf": [
        {"type": "string"},
        {"type": "null"}
    ],
    "description": "Optional free-text comment"
}

Klienta puses validācija

Stingrais režīms garantē formu, nekad nozīmi. Labi noformēts datums var būt pagātnē, pareiza tipa identifikators var neatbilst nevienam klientam, un derīga summa var pārsniegt atļauto limitu. Šie noteikumi ir biznesa loģika: neviena JSON shēma tos neizsaka, un tie ir jāpārbauda tavā kodā – noraidījuma gadījumā atpakaļ modelim jānosūta kļūdas ziņojums, kas skaidro, kas notika nepareizi.

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

    # Biznesa loģika pēc validācijas
    return creer_facture(**args)

Efektīvi apraksti

Raksti funkcijas aprakstu kā instrukciju jaunam kolēģim: kad to izsaukt un, galvenais, kad to nedarīt. Tieši otro daļu mēs sistemātiski aizmirstam, taču tā atrisina lielāko daļu kļūdaino izsaukumu – „nelieto arhivētiem pasūtījumiem” novērš lieku apriti, ko neapturētu trīs teikumi ar pozitīvu aprakstu.

# Slikti: pārāk vispārīgi
{
    "name": "get_data",
    "description": "Retrieve data"
}

# Labi: specifiski un kontekstuāli
{
    "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."
}

Parametru apraksti

Parametru līmenī ienaidnieks ir implicītais. Mērvienība (eiro vai centi?), formāts (ISO vai lokāls?), konvencija (iekšējais ID vai klienta atsauce?), kas nav uzrakstīti, tiks uzminēti – dažreiz pareizi, dažreiz nē, un par to nebūs nekāda signāla. enum ir tavs labākais rīks šeit: tas neapraksta sagaidāmo vērtību, tas to ierobežo.

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

Ligzdotās shēmas un atsauces

Dziļi ligzdota shēma ir grūti pārlasāma tev un grūti pareizi aizpildāma modelim. Ja nonāc līdz trim līmeņiem, jautājums nav par to, kā to uzrakstīt labāk, bet gan vai funkcija nedara pārāk daudz: divas funkcijas ar skaidru darbības jomu gandrīz vienmēr ir vēlamākas par vienu konfigurējamu funkciju, kas aptver abus gadījumus.

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

Galvenās atziņas

  • Aktivizē strict: true, lai garantētu argumentu atbilstību
  • Joprojām veic validāciju klienta pusē ar jsonschema, lai pārbaudītu biznesa noteikumus
  • Raksti precīzus aprakstus: tie ir galvenais kvalitātes svira
  • Izmanto enum, lai ierobežotu pieņemtās vērtības
  • Sarežģītas shēmas sadali atkārtoti izmantojamās apakšstruktūrās