Sheme JSON in preverjanje
Na tej strani
Sheme JSON in preverjanje
Shema funkcije ni le infrastruktura za preverjanje: to je edina pogodba med modelom in tvojo kodo. Drugih kanalov ni. Model ne bere tvoje implementacije, ne pozna tvojih internih konvencij in ne bo uganil, da polje date pričakuje format ISO namesto francoskega formata.
Vse, kar ni zapisano v shemi, bo model določil s svojimi naključnimi sklepanji. To pojasnjuje neravnovesje v prizadevanjih, priporočeno v tej lekciji: bolje je porabiti deset minut za shemo kot dve uri za odpravljanje napak zaradi nestanovitnih argumentov.
Struktura sheme funkcije
Vsaka funkcija, deklarirana v tools, sledi formatu JSON Schema. Tukaj je popolna struktura:
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
}
Strogi način (Strict Mode)
Strogi način verjetnost spremeni v garancijo. Brez njega model običajno ustvari skladne argumente – izjeme pa odkriješ šele v produkciji, ob robnih primerih. Z njim je skladnost zagotovljena že pri konstrukciji, na ravni dekodiranja. Omogoči ga privzeto: omejitve, ki jih nalaga in so podrobneje opisane spodaj, so majhna cena za odpravo celotnega razreda napak.
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
}]
Omejitve strogega načina
V strogem načinu veljajo določena pravila:
- Vsa polja morajo biti v
required additionalPropertiesmora bitifalse- Izbirni tipi uporabljajo
anyOfznull - Na najvišji ravni ni dovoljenih
pattern,minLength,maxLength
# Izbirno polje v strogem načinu
"commentaire": {
"anyOf": [
{"type": "string"},
{"type": "null"}
],
"description": "Optional free-text comment"
}
Preverjanje na strani odjemalca
Strogi način zagotavlja obliko, nikoli pa pomena. Dobro oblikovan datum je lahko v preteklosti, pravilno tipiziran identifikator se morda ne ujema z nobenim kupcem, veljaven znesek pa lahko presega dovoljeno omejitev. Ta pravila so poslovna logika: nobena shema JSON jih ne more izraziti, zato jih je treba preveriti v tvoji kodi – v primeru zavrnitve pa modelu poslati sporočilo o napaki, ki pojasnjuje, kaj je šlo narobe.
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}"})
# Poslovna logika po preverjanju
return creer_facture(**args)
Učinkoviti opisi
Opis funkcije napiši kot navodila za novega sodelavca: kdaj jo poklicati in še posebej, kdaj je ne poklicati. Prav ta drugi del sistematično pozabimo, čeprav reši večino napačnih klicev – „ne uporabi za arhivirana naročila” prepreči nepotreben povratni krog, ki ga trije stavki pozitivnega opisa ne bi ustavili.
# Slabo: preveč ohlapno
{
"name": "get_data",
"description": "Retrieve data"
}
# Dobro: specifično in kontekstualno
{
"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."
}
Opisi parametrov
Na ravni parametrov je sovražnik implicitno. Enota (evri ali centi?), format (ISO ali lokalni?), konvencija (interni ID ali sklic stranke?), ki niso zapisani, bodo ugibani – včasih pravilno, včasih ne, brez kakršnega koli signala. enum je tukaj tvoje najboljše orodje: ne opisuje pričakovane vrednosti, temveč jo omejuje.
"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."
}
}
Gnezdenje shem in reference
Globoko gnezdena shema je težka za ponovno branje tebi in za pravilno izpolnjevanje modelu. Če dosežeš tri ravni, vprašanje ni, kako jo bolje zapisati, temveč ali funkcija dela preveč: dve funkciji z jasnim obsegom sta skoraj vedno boljši od ene konfigurabilne funkcije, ki pokriva oba primera.
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
}]
Ključne ugotovitve
- Omogoči
strict: trueza zagotovilo skladnosti argumentov - Še vedno preveri na strani odjemalca z
jsonschemaza poslovna pravila - Napiši natančne opise: so glavni vzvod za kakovost
- Uporabi
enumza omejitev sprejetih vrednosti - Razdeli kompleksne sheme na ponovno uporabne podstrukture