Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

JSON-skeemat ja kuvaukset

Oppitunti 2 / 14 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Työkalujen kieli: JSON-skeema
  2. Työkalumäärityksen anatomia
  3. Parametrien kuvaukset
  4. Edistyneet parametrit
  5. Parhaat käytännöt kuvauksissa
  6. Keskeiset asiat

Työkalujen kieli: JSON-skeema

Jotta Grok pystyy kutsumaan funktioitasi, sen on tiedettävä mitä ne tekevät ja mitä parametreja ne odottavat. Tässä tulee JSON-skeemojen rooli. Jokainen työkalu kuvataan strukturoidulla objektilla, joka sisältää kolme olennaista osaa: nimen, kuvauksen ja parametriskeeman.

Työkalumäärityksen anatomia

Tässä on työkalun täydellinen rakenne sellaisena kuin Grok API sen odottaa:

{
  "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"]
  }
}

Purkaaankin jokainen kenttä erikseen:

type-kenttä

Aseta tämä aina arvoksi "function", kun kyse on omista funktioistasi. Muut tyypit (kuten web_search tai code_interpreter) on varattu sisäänrakennetuille työkaluille, mutta omille funktioillesi arvo on aina "function".

name-kenttä

Tämä on funktiosi tekninen nimi. Sen tulee olla:

  • Yksilöllinen suhteessa kaikkiin pyynnössä oleviin työkaluihin
  • Kuvaava: käytä nimeä get_weather äläkä fn1
  • snake_case-muodossa sopimuksen mukaan: search_products, create_ticket
  • Lyhyt mutta selkeä: malli käyttää tätä nimeä päättäessään, mitä työkalua se kutsuu

description-kenttä

Tämä on tärkein kenttä kutsujen laadun kannalta. Malli luottaa ensisijaisesti kuvaukseen päättäessään, milloin ja miten työkalua käytetään. Hyvä kuvaus:

  • Selittää mitä funktio tekee yhdellä lauseella
  • Määrittää, milloin sitä tulee käyttää (jos se ei ole itsestään selvää)
  • Mainitsee tarvittaessa erikoistapaukset

Vertaa näitä kahta kuvausta:

❌ "Sää"
✅ "Hae nykyinen sää tietylle kaupungille. Palauttaa lämpötilan, kosteuden ja sääolosuhteet."

Jälkimmäinen antaa mallille tarpeeksi kontekstia ymmärtääkseen tarkalleen, milloin funktiota tulee kutsua ja mitä se saa vastaukseksi.

parameters-lohko

Parametrit noudattavat JSON Schema -formaattia. Tuettuja tyyppejä ovat:

  • string — merkkijonot
  • number / integer — luvut
  • boolean — tosi/epätosi
  • array — listat
  • object — sisäkkäiset objektit
  • enum — lista sallituista arvoista

required-taulukko luettelee pakolliset parametrit. Muut ovat valinnaisia – malli voi päättää jättää ne pois.

Parametrien kuvaukset

Jokaisella parametrilla tulee olla oma description. Tämä on se, mikä mahdollistaa mallin ymmärtää, minkä arvon se syöttää:

{
  "date": {
    "type": "string",
    "description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
  }
}

Ilman kuvausta mallin on arvattava odotettu formaatti, mikä johtaa virheisiin.

Edistyneet parametrit

Enum-arvot rajoittavat vaihtoehtoja

{
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high", "critical"],
    "description": "Ticket priority level"
  }
}

Enum-arvot ovat erityisen hyödyllisiä: ne kertovat mallille tarkat arvot, joita se voi käyttää, mikä eliminoi formaattivirheet.

Oletusarvot

{
  "limit": {
    "type": "integer",
    "default": 10,
    "description": "Maximum number of results to return"
  }
}

Malli ymmärtää, että se voi jättää tämän parametrin pois, jos oletusarvo käy.

Sisäkkäiset objektit

{
  "address": {
    "type": "object",
    "properties": {
      "street": { "type": "string" },
      "city": { "type": "string" },
      "zip": { "type": "string" }
    },
    "required": ["city"]
  }
}

Parhaat käytännöt kuvauksissa

Kuvaus on ainoa kanava, jonka kautta malli ymmärtää työkalusi – jokainen sana painaa siinä. Tarkkuus ensin: “Etsi tuotteita nimellä tai kategoriasta luettelosta” kertoo mallille tarkalleen, milloin työkalua sovelletaan, kun taas “Etsi tuotteita” jättää sen arvailun varaan. Formaatit seuraavaksi: määrittämällä parametrin kuvaukseen “Päivämäärä ISO 8601 -formaatissa (VVVV-KK-PP)” eliminoit puolet argumenttivirheistä, koska malli toistaa näyttämäsi formaatin. Rajat ovat osa sopimusta: “Enintään 50 tulosta per kutsu” estää mallia lupaamasta käyttäjälle täydellisyyttä, jota työkalu ei tarjoa. Ja paluuarvon kuvaaminen – “Palauttaa objektin, jossa on hinta, saatavuus ja kuvaus” – auttaa mallia suunnittelemaan etukäteen: se tietää, mitä sillä on käytössään ennen kutsun tekemistäkin.

Keskeiset asiat

  • Jokainen työkalu määritellään name-, description- ja parameters-kentillä
  • Kuvaus on tärkein tekijä kutsujen laadussa – käytä siihen aikaa
  • Nimien tulee olla yksilöllisiä ja snake_case-muodossa
  • Käytä enum-arvoja rajoittaaksesi mahdollisia arvoja
  • Jokaisella parametrilla tulee olla oma kuvauksensa, jossa on odotettu formaatti
  • required-taulukko erottaa pakolliset parametrit valinnaisista