JSON shēmas un validācija
Šajā lapā
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 additionalPropertiesir jābūtfalse- Neobligātie tipi izmanto
anyOfkopā arnull - 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