Funktsioonide defineerimine JSON Schema abil
Sellel lehel
Leping sinu koodi ja mudeli vahel
Selleks, et Mistrali mudel saaks sinu funktsioone kutsuda, peab ta teadma, mis on olemas ja kuidas neid kasutada. Selle eest vastutab JSON Schema: standardiseeritud vorming, mis kirjeldab iga funktsiooni – selle nime, tegevust, oodatavaid parameetreid ja seda, millised neist on kohustuslikud.
Pea selle õppetüki vältel meeles üht asja: mudel ei näe kunagi sinu Pythoni koodi. Ta näeb ainult seda spetsifikatsiooni. Kui sinu funktsioon töötleb väiketähtedega ID-sid, kuid skeem seda ei maini, eirab mudel seda võimalust. Mida täpsem ja paremini dokumenteeritud on sinu skeem, seda täpsemad on genereeritud argumendid.
Tööriista spetsifikatsiooni anatoomia
Iga Mistrali API-le saadetav tööriist järgib sama struktuuri:
tool = {
"type": "function",
"function": {
"name": "function_name",
"description": "Selge kirjeldus sellest, mida funktsioon teeb",
"parameters": {
"type": "object",
"properties": {
"param1": {
"type": "string",
"description": "Parameetri kirjeldus"
},
"param2": {
"type": "integer",
"description": "Parameetri kirjeldus"
}
},
"required": ["param1"]
}
}
}
| Väli | Roll |
|---|---|
type | Alati "function" (tulevikus võivad eksisteerida ka muud tüübid) |
function.name | Sinu Pythoni funktsiooni täpne nimi – selle tagastab mudel väljal tool_calls |
function.description | Selge lause, mis aitab mudelil valida õige funktsiooni |
function.parameters | JSON Schema objekt, mis kirjeldab oodatavaid parameetreid |
required | Kohustuslike parameetrite loend |
Toetatud JSON Schema tüübid
Parameetrite kirjeldamiseks kasutatav tüüpide sõnavara on tahtlikult piiratud ja iga tüüp suunab mudelit erinevalt. Eriti enum teeb enamat kui lihtsalt dokumenteerimine: see sulgeb ukse väljamõeldud väärtustele.
# String — vaba tekst või piiratud
{"type": "string", "description": "Tehingu ID"}
# String koos enumiga — piiratud väärtused
{"type": "string", "enum": ["asc", "desc"], "description": "Sorteerimise järjekord"}
# Integer — täisarv
{"type": "integer", "description": "Tagastatavate tulemuste arv"}
# Number — kümnendmurdarv
{"type": "number", "description": "Summa eurodes"}
# Boolean — tõene/väär
{"type": "boolean", "description": "Kaasa arvatud tühistatud tehingud"}
# Array — väärtuste loend
{
"type": "array",
"items": {"type": "string"},
"description": "Tehingute ID-de loend"
}
# Object — pesastatud objekt
{
"type": "object",
"properties": {
"city": {"type": "string"},
"country": {"type": "string"}
},
"description": "Tarneaadress"
}
Tee selge vahet integer ja number vahel: summa eurodes, nagu 125.50, nõuab tüüpi number, samas kui tagastatavate tulemuste arv on integer. Summa deklareerimine kui integer paneb mudeli selle ümardama.
Täielik näide: kaks täiendavat funktsiooni
Siin on realistlik näide kahe maksetega seotud funktsiooniga, mis põhineb ametlikul Mistrali dokumentatsioonil:
tools = [
{
"type": "function",
"function": {
"name": "retrieve_payment_status",
"description": "Retrieves the status of a payment (paid, pending, failed) "
"based on the transaction ID.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "The unique transaction ID (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "retrieve_payment_date",
"description": "Retrieves the date when a payment was made "
"based on the transaction ID.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "The unique transaction ID (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
}
]
Mõlemad funktsioonid eeldavad täpselt sama parameetrit, transaction_id, ometi peab mudel nende vahel valima. See valik tugineb täielikult funktsiooni kirjeldusele. Küsimus „Kas see makse õnnestus?“ viib funktsioonini retrieve_payment_status; küsimus „Millal see toimus?“ viib funktsioonini retrieve_payment_date. Kui oleksid kirjutanud kaks ebamäärast ja omavahel asendatavat kirjeldust, eksiks mudel pooltel juhtudel – ja süüdistaksid mudelit, kuigi viga peitub skeemis.
Kohustuslikud vs valikulised parameetrid
Erinevus kohustuslike ja valikuliste parameetrite vahel määrab, mida mudelil on lubatud välja jätta.
{
"type": "function",
"function": {
"name": "search_transactions",
"description": "Searches for transactions based on various criteria",
"parameters": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["paid", "pending", "failed"],
"description": "Filtreeri makse staatuse järgi"
},
"date_from": {
"type": "string",
"description": "Alguskuupäev formaadis YYYY-MM-DD"
},
"date_to": {
"type": "string",
"description": "Lõppkuupäev formaadis YYYY-MM-DD"
},
"min_amount": {
"type": "number",
"description": "Minimaalne summa eurodes"
}
},
"required": ["status"]
}
}
}
Siin on ainult status kohustuslik; teised parameetrid lisatakse ainult siis, kui kasutaja neid mainib. Võrdle kahte formulatsiooni. Päringu „Näita ebaõnnestunud makseid“ korral genereerib mudel lihtsalt {"status": "failed"}. Päringu „Näita ebaõnnestunud makseid alates märtsist 2026“ korral lisab ta ise date_from ja date_to. Nende kuupäevade kohustuslikuks tegumine oleks rikkunud esimese päringu või, mis veel hullem, sundinud mudelit leiutama kuupäevavahemiku.
Parimad tavad kirjelduste koostamisel
Kirjelduste kvaliteet mõjutab otseselt mudeli täpsust. Allpool toodud vastunäited on õpetlikumad kui ükski abstraktne reegel.
# Halb — liiga ebamäärane
{"description": "Toob andmed"}
# Hea — täpne ja kontekstiga
{"description": "Toob makse staatuse (makstud, ootel, ebaõnnestunud) "
"unikaalse tehingu ID põhjal"}
# Halb — parameetrile kirjeldus puudub
{"transaction_id": {"type": "string"}}
# Hea — kirjeldus koos näitega
{"transaction_id": {
"type": "string",
"description": "Unikaalne tehingu ID (formaadis: T, millele järgneb 4 numbrit, nt T1001)"
}}
Hea kirjeldus ütleb ühes lauses, mida funktsioon teeb, täpsustab iga parameetri oodatavat formaati ja toob näite, kui formaat pole ilmne – T1001 on parem kui „tehingu ID“. Kui võimalikud väärtused on piiratud, ära kirjelda neid proosas: deklareeri need kasutades enum. See on ainus viis muuta need siduvaks.
Peamised punktid
- JSON Schema on leping sinu koodi ja mudeli vahel – see kirjeldab sinu funktsioone, paljastamata koodi ennast
- Igal tööriistal on
name,descriptionja tüübitudparameters - Toetatud tüüpide hulka kuuluvad
string,integer,number,boolean,arrayjaobject - Loend
requirederistab kohustuslikke parameetreid valikulistest - Täpsed kirjeldused koos näidetega parandavad oluliselt mudeli täpsust