JSON-sémák és validálás
Ezen az oldalon
JSON-sémák és validálás
A függvényséma nem csupán validálási csővezeték: ez az egyetlen szerződés a modell és a kódod között. Nincs más csatorna. A modell nem olvassa az implementációdat, nem ismeri a belső konvencióidat, és nem fogja kitalálni, hogy egy date mező ISO formátumot vár francia formátum helyett.
Bármi, ami nincs leírva a sémában, azt a modell véletlenszerű következtetései döntik el. Ez magyarázza az ebben a leckében javasolt erőfeszítés-egyensúlytalanságot: jobb tíz percet szánni a sémára, mint két órát hibakeresésre instabil argumentumok miatt.
Függvényséma felépítése
Minden, a tools listában deklarált függvény JSON-séma formátumot követ. Íme a teljes 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
}
Szigorú mód (Strict Mode)
A szigorú mód a valószínűséget garanciává változtatja. Enélkül a modell általában megfelel az elvárásoknak – és a kivételeket csak éles környezetben, szélsőséges esetekben fedezed fel. Ezzel szemben a megfelelés már a dekódolás szintjén, konstrukciós szinten biztosított. Alapértelmezetten engedélyezd: a rákényszerített kényszerek, amelyeket lentebb részletezünk, csekély árat jelentenek a hibák egy teljes osztályának kiküszöböléséért cserébe.
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
}]
A szigorú mód kényszerei
Szigorú módban bizonyos szabályok érvényesek:
- Minden mezőnek szerepelnie kell a
requiredlistában - Az
additionalPropertiesértékénekfalse-nak kell lennie - Az opcionális típusoknál
anyOf-ot használjnullértékkel - Nincs
pattern,minLength,maxLengtha legfelső szinten
# Opcionális mező szigorú módban
"commentaire": {
"anyOf": [
{"type": "string"},
{"type": "null"}
],
"description": "Optional free-text comment"
}
Kliensoldali validálás
A szigorú mód a formát, de sosem a tartalmat garantálja. Egy jól formázott dátum lehet a múltban, egy jól típusozott azonosító nem feltétlenül felel meg egyetlen ügyfélnek sem, és egy érvényes összeg túllépheti az engedélyezett limitet. Ezek üzleti logikai szabályok: egyetlen JSON-séma sem képes kifejezni őket, ezért ezeket a kódodban kell ellenőrizned – elutasítás esetén pedig hibaüzenetet küldesz vissza a modellnek, amely elmagyarázza, mi ment rosszul.
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}"})
# Üzleti logika a validálás után
return creer_facture(**args)
Hatékony leírások
Írd meg a függvény leírását úgy, mint egy új kollégának szóló utasítást: mikor kell hívni, és főleg mikor nem szabad hívni. Pont ezt a második részt felejtjük el szisztematikusan, pedig ez oldja meg a téves hívások többségét – a „ne használd archivált rendeléseknél“ kitétel megelőz egy felesleges körmenetet, amit három mondatnyi pozitív leírás nem állított volna meg.
# Rossz: túl általános
{
"name": "get_data",
"description": "Retrieve data"
}
# Jó: specifikus és kontextusba ágyazott
{
"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."
}
Paraméterleírások
Paraméter szinten az ellenség az implicit feltételezés. Egy mértékegység (euró vagy cent?), egy formátum (ISO vagy helyi?), egy konvenció (belső azonosító vagy ügyfélreferencia?), amit nem írsz le, azt a modell kitalálja – néha helyesen, néha nem, minden jelzés nélkül. Itt az enum a legjobb eszközöd: nem leírja a várt értéket, hanem kényszeríti azt.
"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."
}
}
Beágyazott sémák és hivatkozások
Egy mélyen beágyazott sémát nehéz neked is újraolvasni, és a modellnek is helyesen kitölteni. Ha eléred a három szintet, a kérdés nem az, hogyan írd meg jobban, hanem hogy a függvény nem csinál-e túl sokat: két jól körülhatárolt függvény szinte mindig előnyösebb, mint egyetlen konfigurálható függvény, amely mindkét esetet lefedi.
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
}]
Főbb megállapítások
- Engedélyezd a
strict: truebeállítást az argumentumok megfelelőségének garantálásához - Az üzleti szabályok miatt továbbra is végezz kliensoldali validálást
jsonschemasegítségével - Írj precíz leírásokat: ezek az elsődleges minőségi tényezők
- Használj
enum-ot az elfogadott értékek korlátozására - Bontsd fel a komplex sémákat újrafelhasználható alstruktúrákra