JSON-skemaer og validering
På denne side
JSON-skemaer og validering
Et funktionsskema er ikke blot valideringsrør: det er den eneste kontrakt mellem modellen og din kode. Der findes ingen anden kanal. Modellen læser ikke din implementering, kender ikke dine interne konventioner og vil ikke gætte på, at et date-felt forventer ISO-format i stedet for fransk format.
Alt, der ikke er skrevet i skemaet, overlades til modellens tilfældige slutninger. Dette forklarer den ubalance i indsats, som anbefales i denne lektion: det er bedre at bruge ti minutter på et skema end to timer på at fejlsøge ustabile argumenter.
Struktur for funktionsskemaer
Alle funktioner, der erklæres i tools, følger JSON Schema-formatet. Her er den fulde struktur:
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
}
Streng tilstand (Strict Mode)
Streng tilstand omdanner sandsynlighed til en garanti. Uden den producerer modellen normalt kompatible argumenter – og du opdager undtagelserne i produktionen, når kanttilfælde opstår. Med den sikres overholdelse ved konstruktion på dekodningsniveauet. Aktiver den som standard: de begrænsninger, den pålægger, og som er detaljeret nedenfor, er en lille pris at betale for at eliminere en hel klasse af fejl.
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
}]
Begrænsninger i streng tilstand
I streng tilstand gælder visse regler:
- Alle felter skal være i
required additionalPropertiesskal værefalse- Valgfrie typer bruger
anyOfmednull - Ingen
pattern,minLength,maxLengthpå topniveau
# Valgfrit felt i streng tilstand
"commentaire": {
"anyOf": [
{"type": "string"},
{"type": "null"}
],
"description": "Optional free-text comment"
}
Validering på klientsiden
Streng tilstand garanterer formen, aldrig betydningen. En velformateret dato kan ligge i fortiden, en korrekt typed identifikator matcher måske ingen kunde, og et gyldigt beløb kan overstige den autoriserede grænse. Disse regler er forretningslogik: intet JSON-skema kan udtrykke dem, og de skal verificeres i din kode – med en fejlmeddelelse sendt tilbage til modellen, der forklarer, hvad der gik galt, hvis afvisning sker.
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}"})
# Forretningslogik efter validering
return creer_facture(**args)
Effektive beskrivelser
Skriv en funktionsbeskrivelse som instrukser til en ny kollega: hvornår den skal kaldes, og især hvornår den ikke skal kaldes. Det er den anden del, vi systematisk glemmer, alligevel løser den de fleste fejlagtige kald – „brug ikke til arkiverede ordrer” forhindrer en unødvendig rundtur, som tre sætninger med positiv beskrivelse ikke ville have stoppet.
# Dårligt: for vagt
{
"name": "get_data",
"description": "Retrieve data"
}
# Godt: specifikt og kontekstuelt
{
"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."
}
Parameterbeskrivelser
På parameterniveau er fjenden det implicitte. En enhed (euro eller cent?), et format (ISO eller lokalt?), en konvention (internt ID eller kundereference?), der ikke er skrevet, vil blive gættet – nogle gange korrekt, nogle gange ikke, uden signal i nogen af delene. enum er dit bedste værktøj her: det beskriver ikke den forventede værdi, det begrænser den.
"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."
}
}
Næstede skemaer og referencer
Et dybt næstet skema er svært for dig at genlæse og for modellen at udfylde korrekt. Hvis du når tre niveauer, er spørgsmålet ikke, hvordan du skriver det bedre, men om funktionen gør for meget: to funktioner med klart omfang er næsten altid at foretrække frem for én konfigurerbar funktion, der dækker begge tilfælde.
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
}]
Vigtige pointer
- Aktiver
strict: truefor at garantere overholdelse af argumenter - Valider stadig på klientsiden med
jsonschemafor forretningsregler - Skriv præcise beskrivelser: de er den primære kvalitetsløftestang
- Brug
enumtil at begrænse accepterede værdier - Opdel komplekse skemaer i genanvendelige understrukturer