JSON-sémák és leírások
Ezen az oldalon
Az eszközök nyelve: JSON-séma
Ahhoz, hogy a Grok meghívja a függvényeidet, tudnia kell, mit csinálnak és milyen paramétereket várnak. Ezt a feladatot látják el a JSON-sémák. Minden eszközt egy strukturált objektum ír le, amely három alapvető információt tartalmaz: egy nevet, egy leírást és egy paramétersémát.
Egy eszközdefiníció felépítése
Íme egy eszköz teljes szerkezete, ahogy azt a Grok API elvárja:
{
"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"]
}
}
Nézzük meg részletesen az egyes mezőket:
A type mező
Egyedi függvények esetén mindig "function". Léteznek más típusok a beépített eszközökhöz (pl. web_search, code_interpreter), de a saját függvényeidnél ez kivétel nélkül "function" lesz.
A name mező
A függvényed technikai neve. Ennek meg kell felelnie az alábbi követelményeknek:
- Egyedi legyen az összes, a kérésben szereplő eszköz között
- Leíró jellegű: használj
get_weathernevet afn1helyett - snake_case konvenció szerint íródjon:
search_products,create_ticket - Rövid, de egyértelmű: a modell ezt a nevet használja annak eldöntésére, melyik eszközt hívja meg
A description mező
Ez a legfontosabb mező a hívások minősége szempontjából. A modell elsősorban a leírás alapján dönti el, mikor és hogyan használjon egy eszközt. Egy jó leírás:
- Egy mondatban elmagyarázza, mit csinál a függvény
- Megadja, mikor kell használni (ha ez nem egyértelmű)
- Szükség esetén említi a szélsőséges eseteket is
Hasonlítsd össze ezt a két leírást:
❌ "Időjárás"
✅ "Lekéri az aktuális időjárást egy város számára. Visszaadja a hőmérsékletet, a páratartalmat és az időjárási viszonyokat."
A második lehetőség elegendő kontextust ad a modellnek, hogy pontosan tudja, mikor hívja meg ezt a függvényt, és mit kap cserébe.
A parameters blokk
A paraméterek a JSON-séma formátumot követik. A támogatott típusok közé tartoznak:
string— karakterláncoknumber/integer— számokboolean— igaz/hamis értékekarray— listákobject— beágyazott objektumokenum— engedélyezett értékek listája
A required tömb felsorolja a kötelező paramétereket. A többi paraméter opcionális – a modell dönthet úgy, hogy kihagyja őket.
Paraméterleírások
Minden paraméternek rendelkeznie kell a saját description mezőjével. Ez teszi lehetővé, hogy a modell megértse, milyen értéket kell átadnia:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Leírás hiányában a modellnek találgatnia kell a várt formátumot, ami hibákhoz vezet.
Haladó paraméterek
Enumok az értékek korlátozására
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Az enumok különösen hasznosak: megmondják a modellnek a pontosan használható értékeket, ezzel kiküszöbölve a formátumi hibákat.
Alapértelmezett értékek
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
A modell megérti, hogy kihagyhatja ezt a paramétert, ha az alapértelmezett érték megfelel.
Beágyazott objektumok
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Legjobb gyakorlatok a leírásokhoz
A leírás az egyetlen csatorna, amelyen keresztül a modell megérti az eszközödet – itt minden szónak súlya van. Először is a specifikusság: a „Termékek keresése név vagy kategória alapján a katalógusban“ pontosan megmondja a modellnek, mikor alkalmazza ezt az eszközt, míg a „Termékek keresése“ bizonytalanságot hagy. Másodszor a formátumok: ha a paraméterleírásban megadod, hogy „Dátum ISO 8601 formátumban (ÉÉÉÉ-HH-NN)“, azzal a hibák felét megszünteted, mert a modell lemásolja a mutatott formátumot. A korlátok is a szerződés részét képezik: a „Hívásonként maximum 50 találat“ megakadályozza, hogy a modell olyan teljességet ígérjen a felhasználónak, amit az eszköz nem tud nyújtani. Végül pedig a visszatérési érték leírása – „Visszaad egy objektumot az árral, elérhetőséggel és leírással“ – segít a modellnek előre tervezni: tudja, mi lesz a rendelkezésére álló adat, még mielőtt meghívná az eszközt.
Főbb megállapítások
- Minden eszközt egy
name, egydescriptionés egyparametersdefiniál - A leírás a hívások minőségének legfontosabb tényezője – fordíts rá időt
- A neveknek egyedinek és snake_case formátumúnak kell lenniük
- Használj
enum-ot a lehetséges értékek korlátozására - Minden paraméter rendelkezzen saját leírással a várt formátum megadásával
- A
requiredtömb választja el a kötelező paramétereket az opcionálisaktól