JSON-i skeemid ja valideerimine
Sellel lehel
JSON-i skeemid ja valideerimine
Funktsiooni skeem ei ole lihtsalt valideerimise taristu: see on ainus leping mudeli ja sinu koodi vahel. Muud kanalit pole. Mudel ei loe sinu implementatsiooni, ei tunne sinu sisemisi kokkuleppeid ja ei arva ära, et väli date eeldab ISO-vormingut, mitte prantsuse vormingut.
Kõik, mida skeemi ei kirjutata, jäetakse mudeli juhuslike järelduste hooleks. See seletab selles õppetükis soovitatud jõupingutuste tasakaalutust: parem on kulutada skeemile kümme minutit kui kaks tundi ebastabiilsete argumentide silumisele.
Funktsiooni skeemi struktuur
Iga tööriistade (tools) hulgas deklareeritud funktsioon järgib JSON Schema vormingut. Siin on täielik struktuur:
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
}
Range režiim (Strict Mode)
Range režiim muudab tõenäosuse garantiiks. Ilma selleta toodab mudel tavaliselt nõuetele vastavaid argumente – ja erandid avastad tootmises, piirjuhtudel. Sellega tagatakse vastavus juba dekodeerimise tasandil. Lülita see vaikimisi sisse: piirangud, mida see kehtestab (vt allpool), on väike hind terve veaklassi kõrvaldamise eest.
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
}]
Range režiimi piirangud
Ranges režiimis kehtivad teatud reeglid:
- Kõik väljad peavad olema loendis
required additionalPropertiespeab olemafalse- Valikulised tüübid kasutavad
anyOfkoosnull-iga - Ülemisel tasandil ei tohi olla
pattern,minLengthegamaxLength
# Valikuline väli ranges režiimis
"commentaire": {
"anyOf": [
{"type": "string"},
{"type": "null"}
],
"description": "Optional free-text comment"
}
Kliendipoolne valideerimine
Range režiim garanteerib ainult vormi, mitte kunagi sisu. Hästi vormistatud kuupäev võib olla minevikus, õiget tüüpi identifikaator ei pruugi ühegi kliendiga sobida ja kehtiv summa võib ületada lubatud limiiti. Need reeglid on äriloogika: ükski JSON-i skeem neid ei väljenda ja need tuleb kontrollida sinu koodis – tagasilükkamise korral saada mudelile veateade, mis selgitab, mis valesti läks.
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}"})
# Äriloogika pärast valideerimist
return creer_facture(**args)
Tõhusad kirjeldused
Kirjuta funktsiooni kirjeldus nagu juhised uuele kolleegile: millal seda kutsuda ja eriti millal mitte. Just teine osa unustatakse süstemaatiliselt, kuigi see lahendab enamiku valedest kutsetest – „ära kasuta arhiveeritud tellimuste puhul“ hoiab ära tarbetu päringu, mida kolm lauset positiivsest kirjeldusest poleks peatanud.
# Halb: liiga üldine
{
"name": "get_data",
"description": "Retrieve data"
}
# Hea: spetsiifiline ja kontekstipõhine
{
"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."
}
Parameetrite kirjeldused
Parameetrite tasandil on vaenlane eeldus. Ühik (eurot või sendid?), vorming (ISO või kohalik?), kokkulepe (sisene ID või kliendi viide?), mida ei kirjutata, arvatakse ära – mõnikord õigesti, mõnikord mitte, ilma igasuguse signaalita. Siin on enum sinu parim tööriist: see ei kirjelda oodatavat väärtust, see piirab seda.
"properties": {
"date_debut": {
"type": "string",
"description": "Start date in ISO 8601 format (YYYY-MM-DD). "
"Defaults to today's date if not specified."
n },
"statut": {
"type": "string",
"enum": ["actif", "inactif", "suspendu"],
"description": "Filter by account status. "
"'actif' = accounts in service, "
"'suspendu' = temporarily frozen accounts."
}
}
Pesastatud skeemid ja viited
Sügavalt pesastatud skeemi on sul raske uuesti läbi lugeda ja mudelil raske korrektselt täita. Kui jõuad kolme tasemeni, ei ole küsimus selles, kuidas seda paremini kirjutada, vaid kas funktsioon teeb liiga palju: kaks selge ulatusega funktsiooni on peaaegu alati eelistatavad ühele konfigureeritavale funktsioonile, mis katab mõlemad juhtumid.
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
}]
Peamised punktid
- Lülita sisse
strict: true, et garanteerida argumentide vastavus - Valideeri kliendipoolselt ikka
jsonschemaabil ärireeglite jaoks - Kirjuta täpsed kirjeldused: need on peamine kvaliteedi hoob
- Kasuta
enumvastuvõetavate väärtuste piiramiseks - Jaota keerukad skeemid korduskasutatavateks alamstruktuurideks