Lähe põhisisu juurde
Eesti— Vali keel
Menüü

JSON skeemid ja kirjeldused

Õppetund 2 / 14 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Tööriistade keel: JSON skeem
  2. Tööriista definitsiooni ehitus
  3. Plokk parameters
  4. Parameetrite kirjeldused
  5. Täiustatud parameetrid
  6. Parimate tavade juhised kirjelduste koostamisel
  7. Peamised punktid

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_weather on parem kui fn1
  • 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 — tekstistringid
  • number / integer — arvud
  • boolean — tõene/väär
  • array — loendid
  • object — pesastatud objektid
  • enum — 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, description ja parameters abil
  • Kirjeldus on kutse kvaliteedi mõjutaja number üks – pühenda sellele aega
  • Nimed peavad olema unikaalsed ja snake_case formaadis
  • Kasuta enum võimalike väärtuste piiramiseks
  • Igal parameetril peaks olema oma kirjeldus koos oodatava formaadiga
  • Massiiv required eristab kohustuslikke parameetreid valikulistest