Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

JSON-sémák és leírások

2. lecke 14 közül Frissítve 2026. július 29. Fejlesztő
Ezen az oldalon
  1. Az eszközök nyelve: JSON-séma
  2. Egy eszközdefiníció felépítése
  3. Paraméterleírások
  4. Haladó paraméterek
  5. Legjobb gyakorlatok a leírásokhoz
  6. Főbb megállapítások

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_weather nevet a fn1 helyett
  • 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áncok
  • number / integer — számok
  • boolean — igaz/hamis értékek
  • array — listák
  • object — beágyazott objektumok
  • enum — 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, egy description és egy parameters definiá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 required tömb választja el a kötelező paramétereket az opcionálisaktól