Salt la conținutul principal
Română— Alege o limbă
Meniu

Schemele JSON și validarea

Lecția 2 din 20 Dezvoltator
Pe această pagină
  1. Schemele JSON și validarea
  2. Structura schemei de funcție
  3. Modul Strict
  4. Validarea lato-client (Client-Side)
  5. Descrieri eficiente
  6. Scheme imbricate și referințe
  7. Puncte cheie

Schemele JSON și validarea

O schemă de funcție nu este o simplă instalație de validare: ea reprezintă unicul contract dintre model și codul dumneavoastră. Nu există niciun alt canal de comunicare. Modelul nu vă citește implementarea, nu cunoaște convențiile interne și nu va ghici că un câmp date așteaptă formatul ISO în locul formatului francez.

Orice nu este scris în schemă va fi decis de inferențele aleatorii ale modelului. Acest lucru explică dezechilibrul de efort recomandat în această lecție: este mai bine să petreceți zece minute pe o schemă decât două ore depanând argumente eraticе.

Structura schemei de funcție

Fiecare funcție declarată în tools respectă formatul JSON Schema. Iată structura completă:

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
}

Modul Strict

Modul strict transformă probabilitatea într-o garanție. Fără acesta, modelul produce de obicei argumente conforme – iar dumneavoastră descoperiți excepțiile în producție, la cazurile limită. Cu acesta, conformitatea este asigurată prin construcție, la nivelul decodării. Activați-l implicit: constrângerile pe care le impune, detaliate mai jos, reprezintă un preț mic de plătit pentru eliminarea unei clase întregi de erori.

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

Constrângeri ale modului Strict

În modul strict, se aplică anumite reguli:

  • Toate câmpurile trebuie să fie în required
  • additionalProperties trebuie să fie false
  • Tipurile opționale utilizează anyOf cu null
  • Fără pattern, minLength, maxLength la nivelul superior
# Câmp opțional în modul strict
"commentaire": {
    "anyOf": [
        {"type": "string"},
        {"type": "null"}
    ],
    "description": "Optional free-text comment"
}

Validarea lato-client (Client-Side)

Modul strict garantează forma, niciodată sensul. O dată bine formată poate fi în trecut, un identificator bine tipizat poate să nu corespundă niciunui client, iar o sumă validă poate depăși limita autorizată. Aceste reguli țin de logica de afaceri: nicio schemă JSON nu le exprimă, iar ele trebuie verificate în codul dumneavoastră – cu, în caz de respingere, un mesaj de eroare trimis înapoi modelului explicând ce nu a funcționat.

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

    # Logica de afaceri după validare
    return creer_facture(**args)

Descrieri eficiente

Scrieți descrierea unei funcții ca pe niște instrucțiuni pentru un coleg nou: când să o apeleze și, mai ales, când să nu o apeleze. Aceasta este partea pe care o uităm sistematic, deși rezolvă majoritatea apelurilor eronate – „a nu se utiliza pentru comenzile arhivate“ previne o rundă inutilă pe care trei propoziții de descriere pozitivă nu ar fi oprit-o.

# Rău: prea vag
{
    "name": "get_data",
    "description": "Retrieve data"
}

# Bun: specific și contextual
{
    "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."
}

Descrierile parametrilor

La nivelul parametrilor, inamicul este implicitul. O unitate de măsură (euro sau cenți?), un format (ISO sau local?), o convenție (ID intern sau referință client?) care nu sunt scrise vor fi ghicite – uneori corect, alteori nu, fără niciun semnal în acest sens. enum este cel mai bun instrument al dumneavoastră aici: el nu descrie valoarea așteptată, ci o constrânge.

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

Scheme imbricate și referințe

O schemă profund imbricată este greu de recitit pentru dumneavoastră și de completat corect pentru model. Dacă ajungeți la trei niveluri, întrebarea de pus nu este cum să o scrieți mai bine, ci dacă funcția face prea multe: două funcții cu un scop clar sunt aproape întotdeauna de preferat unei singure funcții configurabile care acoperă ambele cazuri.

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

Puncte cheie

  • Activați strict: true pentru a garanta conformitatea argumentelor
  • Validați în continuare lato-client cu jsonschema pentru regulile de afaceri
  • Scrieți descrieri precise: ele sunt pârghia principală de calitate
  • Utilizați enum pentru a constrânge valorile acceptate
  • Descompuneți schemele complexe în substructuri reutilizabile