JSON-skeemat ja kuvaukset
Tällä sivulla
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— merkkijonotnumber/integer— luvutboolean— tosi/epätosiarray— listatobject— sisäkkäiset objektitenum— 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- japarameters-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