JSON skeemid ja kirjeldused
Sellel lehel
Tööriistade keel: JSON skeem
Selleks, et Grok suudaks sinu funktsioone käivitada, peab ta teadma, mida need teevad ja milliseid parameetreid need ootavad. Selles seisnebki JSON skeemide roll. Iga tööriista kirjeldab struktureeritud objekt, mis sisaldab kolme olulist elementi: nimi, kirjeldus ja parameetrite skeem.
Tööriista definitsiooni ehitus
Siin on tööriista täielik struktuur nii, nagu Grok API seda eeldab:
{
"type": "function",
"name": "get_weather",
"description": "Get the current weather for a given city",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "The city name (e.g., Paris, Lyon)"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"default": "celsius"
}
},
"required": ["city"]
}
}
Vaatame iga välja lähemalt:
Väli type
Kohandatud funktsioonide puhul on see alati "function". Sisseehitatud tööriistade jaoks on olemas ka muud tüübid (nt web_search, code_interpreter), kuid sinu enda funktsioonide puhul on see alati "function".
Väli name
Sinu funktsiooni tehniline nimi. See peab olema:
- Unikaalne kõigi päringus olevate tööriistade seas
- Kirjeldav:
get_weatheron parem kuifn1 - snake_case formaadis (konventsioon):
search_products,create_ticket - Lühike, kuid selge: mudel kasutab seda nime otsustamaks, millist tööriista kutsuda
Väli description
See on kutse kvaliteedi seisukohalt kõige olulisem väli. Mudel tugineb otsuse tegemisel, millal ja kuidas tööriista kasutada, peamiselt just kirjeldusele. Hea kirjeldus:
- Selgitab ühe lausega, mida funktsioon teeb
- Täpsustab, millal seda kasutada (kui see pole ilmne)
- Mainib vajadusel erijuhte
Võrdle neid kahte kirjeldust:
❌ "Ilm"
✅ "Hangi linna praegune ilm. Tagastab temperatuuri, niiskuse ja ilmastikutingimused."
Teine variant annab mudelile piisavalt konteksti, et ta teaks täpselt, millal seda funktsiooni kutsuda ja mida vastuseks oodata.
Plokk parameters
Parameetrid järgivad JSON skeemi formaati. Toetatud tüübid on:
string— tekstistringidnumber/integer— arvudboolean— tõene/väärarray— loendidobject— pesastatud objektidenum— lubatud väärtuste loend
Massiiv required loetleb kohustuslikud parameetrid. Teised on valikulised – mudel võib otsustada need välja jätta.
Parameetrite kirjeldused
Igal parameetril peaks olema oma description. Just see võimaldab mudelil aru saada, millist väärtust edastada:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Ilma kirjelduseta peab mudel eeldatava formaadi ära arvama, mis viib vigadeni.
Täiustatud parameetrid
Enumid väärtuste piiramiseks
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Enumid on eriti kasulikud: need ütlevad mudelile täpsed väärtused, mida ta kasutada võib, välistades formaadivead.
Vaikimisi väärtused
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Mudel mõistab, et ta võib selle parameetri vahele jätta, kui vaikimisi väärtus sobib.
Pesastatud objektid
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Parimate tavade juhised kirjelduste koostamisel
Kirjeldus on ainus kanal, mille kaudu mudel sinu tööriista mõistab – iga sõna loeb. Esikohal on täpsus: „Otsi tooteid nime või kategooria järgi kataloogist“ ütleb mudelile täpselt, millal seda tööriista rakendada, samas kui „Otsi tooteid“ jätab ta arvama. Järgmisena tulevad formaadid: parameetri kirjelduses „Kuupäev ISO 8601 formaadis (AAAA-KK-PP)“ välistab poole argumentide vigadest, sest mudel kordab sinu näidatud formaati. Piirangud on osa lepingust: „Maksimaalselt 50 tulemust päringu kohta“ hoiab ära olukorra, kus mudel lubab kasutajale täielikkust, mida tööriist pakkuda ei saa. Ja tagastatava väärtuse kirjeldamine – „Tagastab objekti, mis sisaldab hinda, saadavust ja kirjeldust“ – aitab mudelil ette planeerida: ta teab, mis tal käepärast on, enne kui ta üldse kutse sooritab.
Peamised punktid
- Iga tööriist on defineeritud
name,descriptionjaparametersabil - Kirjeldus on kutse kvaliteedi mõjutaja number üks – pühenda sellele aega
- Nimed peavad olema unikaalsed ja snake_case formaadis
- Kasuta
enumvõimalike väärtuste piiramiseks - Igal parameetril peaks olema oma kirjeldus koos oodatava formaadiga
- Massiiv
requirederistab kohustuslikke parameetreid valikulistest