JSON schemos ir validavimas
Šiame puslapyje
JSON schemos ir validavimas
Funkcijos schema nėra tik techninis validavimo mechanizmas: tai vienintelė sutartis tarp modelio ir tavo kodo. Kitų kanalų nėra. Modelis neskaito tavo implementacijos, nežino tavo vidinių konvencijų ir nesuspės, kad laukas date tikisi ISO formato, o ne prancūziško.
Viskas, kas neparašyta schemoje, bus nuspręsta pagal atsitiktines modelio išvadas. Tai paaiškina šioje pamokoje rekomenduojamą pastangų disbalansą: geriau dešimt minučių skirti schemai nei dviem valandoms derinti nestabilus argumentus.
Funkcijos schemos struktūra
Kiekviena funkcija, deklaruota tools, laikosi JSON Schema formato. Štai pilna 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
}
Griežtas režimas (Strict Mode)
Griežtas režimas tikimybę paverčia garantija. Be jo modelis dažniausiai generuoja tinkamus argumentus – ir tu išimtis atrandi gamyboje, kraštutiniais atvejais. Su juo atitiktis užtikrinama jau dekoduavimo lygmenyje. Įjunk jį pagal nutylėjimą: jo nustatomi apribojimai, aprašyti žemiau, yra maža kaina, mokama norint pašalinti целą klaidų klasę.
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
}]
Griežto režimo apribojimai
Griežtu režimu galioja tam tikros taisyklės:
- Visi laukai privalo būti sąraše
required additionalPropertiesprivalo būtifalse- Neprivalomi tipai naudoja
anyOfsunull - Viršutiniame lygmenyje negalima naudoti
pattern,minLength,maxLength
# Neprivalomas laukas griežtu režimu
"commentaire": {
"anyOf": [
{"type": "string"},
{"type": "null"}
],
"description": "Optional free-text comment"
}
Kliento pusės validavimas
Griežtas režimas garantuoja formą, bet niekada prasmę. Teisingai suformuota data gali būti praeityje, teisingo tipo identifikatorius gali neatitikti jokio kliento, o galiojanti suma gali viršyti leistiną limitą. Tai verslo logikos taisyklės: jokia JSON schema jų neišreiškia, todėl jas reikia tikrinti tavo kode – o atmetus prašymą, modeliui siųsti klaidos žinutę, paaiškinančią, kas nutiko.
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}"})
# Verslo logika po validavimo
return creer_facture(**args)
Efektyvūs aprašymai
Funkcijos aprašymą rašyk kaip instrukciją naujam kolegai: kada ją kviesti ir, svarbiausia, kada nekviesti. Būtent antrąją dalį sistemingai pamirštame, nors ji išsprendžia daugumą klaidingų kvietimų – „nenaudoti archyvuotiems užsakymams“ sustabdo nereikalingą užklausą, kurios nebūtų sustabdę trys teigiamo aprašymo sakiniai.
# Blogai: per daug bendra
{
"name": "get_data",
"description": "Retrieve data"
}
# Gerai: specifiska ir kontekstualu
{
"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."
}
Parametrų aprašymai
Parametrų lygmenyje priešas yra numanymas. Vienetas (eurai ar centai?), formatas (ISO ar vietinis?), konvencija (vidinis ID ar kliento nuoroda?), kurie neparašyti, bus spėjami – kartais teisingai, kartais ne, ir jokio signalo apie tai nebus. Čia enum yra tavo geriausias įrankis: jis neapibūdina tikėtinos reikšmės, ją apriboja.
"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."
}
}
Įdėtosios schemos ir nuorodos
Giliai įdėta schema sunkiai perskaitoma tau ir sunkiai užpildoma modeliui. Jei pasieki tris lygmenis, klausk ne kaip tai geriau parašyti, o ar funkcija neatlieka per daug: dvi funkcijos su aiškia apimtimi beveik visada geriau nei viena konfigūruojama funkcija, apimanti abu atvejus.
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
}]
Svarbiausi punktai
- Įjunk
strict: true, kad garantuotum argumentų atitiktį - Vis tiek validuok kliento pusėje naudodamas
jsonschemaverslo taisyklėms - Rašyk tikslius aprašymus: tai pagrindinis kokybės svertas
- Naudok
enum, kad apribotum priimtinas reikšmes - Sudėtingas schemas skaidyk į pakartotinai naudojamas postruktūras