Schémy JSON a validácia
Na tejto strane
Schémy JSON a validácia
Schéma funkcie nie je len technická súčasť validácie: je to jediná zmluva medzi modelom a tvojím kódom. Neexistuje žiadny iný kanál komunikácie. Model nečíta tvoju implementáciu, nepozná tvoje interné konvencie a nehádne, že pole date očakáva formát ISO namiesto francúzskeho formátu.
Všetko, čo nie je zapísané v schéme, prenecháš na náhodné inferencie modelu. To vysvetľuje nerovnováhu v úsilí, ktorú odporúčame v tejto lekcii: je lepšie stráviť desať minút tvorbou schémy než dve hodiny ladením erratických argumentov.
Štruktúra schémy funkcie
Každá funkcia deklarovaná v tools nasleduje formát JSON Schema. Tu je kompletná štruktú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
}
Prísny režim (Strict Mode)
Prísny režim mení pravdepodobnosť na záruku. Bez neho model zvyčajne generuje vyhovujúce argumenty – a ty objavíš výnimky až v produkcii pri hraničných prípadoch. S ním je súlad zabezpečený už pri dekodovaní. Povoľ ho predvolene: obmedzenia, ktoré ukladá a ktoré sú podrobne popísane nižšie, sú malou cenou za odstránenie celej triedy chýb.
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
}]
Obmedzenia prísneho režimu
V prísnom režime platia určité pravidlá:
- Všetky polia musia byť v
required additionalPropertiesmusí byťfalse- Voliteľné typy používajú
anyOfsnull - Žiadne
pattern,minLength,maxLengthna najvyššej úrovni
# Voliteľné pole v prísnom režime
"commentaire": {
"anyOf": [
{"type": "string"},
{"type": "null"}
],
"description": "Optional free-text comment"
}
Validácia na strane klienta
Prísny režim garantuje formu, nikdy nie význam. Dobre vytvorený dátum môže byť v minulosti, správne typovaný identifikátor sa nemusí zhodovať so žiadnym zákazníkom a platná suma môže prekročiť povolený limit. Tieto pravidlá sú business logika: žiadna JSON schéma ich nevyjadruje a musia byť overené vo tvojom kóde – pričom v prípade zamietnutia musíš modelu poslať späť chybovú správu vysvetľujúcu, čo sa pokazilo.
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}"})
# Business logic after validation
return creer_facture(**args)
Efektívne popisy
Popis funkcie napíš ako inštrukcie pre nového kolegu: kedy ju zavolať a hlavne kedy ju nezavolať. Práve tú druhú časť systematicky zabúdame, hoci rieši väčšinu chybných volaní – „nepoužívať pre archivované objednávky“ zabráni zbytočnému spätnému volaniu, ktoré by tri vety pozitívneho popisu nezastavili.
# Zlé: príše všeobecné
{
"name": "get_data",
"description": "Retrieve data"
}
# Dobré: špecifické a kontextové
{
"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."
}
Popisy parametrov
Na úrovni parametrov je nepriateľom implicitnosť. Jednotka (eurá alebo centy?), formát (ISO alebo lokálny?), konvencia (interné ID alebo referencia zákazníka?), ktoré nie sú zapísané, budú uhádnuté – niekedy správne, niekedy nie, bez akéhokoľvek signálu. enum je tu tvoj najlepší nástroj: neopisuje očakávanú hodnotu, ale obmedzuje ju.
"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."
}
}
Vnorené schémy a referencie
Hlboko vnorená schéma je ťažká na opätovné prečítanie pre teba aj na správne vyplnenie pre model. Ak dosiahneš tri úrovne, otázka neznie, ako ju napísať lepšie, ale či funkcia nerobí príliš veľa: dve funkcie s jasným rozsahom sú takmer vždy vhodnejšie než jedna konfigurovateľná funkcia pokrývajúca oba prípady.
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
}]
Kľúčové poznatky
- Povoľ
strict: truepre garantovanie súladu argumentov - Stále validuj na strane klienta pomocou
jsonschemapre business pravidlá - Píš presné popisy: sú hlavným pákou kvality
- Používaj
enumna obmedzenie akceptovaných hodnôt - Rozdeľ komplexné schémy na opakovane použiteľné podštruktúry