Sheme JSON in opisi
Na tej strani
Jezik orodij: shema JSON
Da lahko Grok kliče tvoje funkcije, mora vedeti, kaj počnejo in katere parametre pričakujejo. To je vloga shem JSON. Vsako orodje je opisano s strukturiranim objektom, ki vsebuje tri ključne dele informacij: ime, opis in shemo parametrov.
Anatomija definicije orodja
Tukaj je popolna struktura orodja, kot jo pričakuje API Grok:
{
"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"]
}
}
Razčlenimo vsako polje:
Polje type
Za funkcije po meri je to vedno "function". Obstajajo tudi druge vrste za vgrajena orodja (web_search, code_interpreter), toda za tvoje lastne funkcije je to neizogibno "function".
Polje name
Tehnično ime tvoje funkcije. Biti mora:
- Edinstveno med vsemi orodji v zahtevi
- Opisno:
get_weathernamestofn1 - V zapisu snake_case po dogovoru:
search_products,create_ticket - Kratko, a eksplicitno: model uporabi to ime za odločitev, katero orodje bo poklical
Polje description
To je najpomembnejše polje za kakovost klica. Model se pri odločanju, kdaj in kako uporabiti orodje, primarno zanaša na opis. Dober opis:
- V enem stavku razloži, kaj funkcija počne
- Določi, kdaj jo uporabiti (če ni očitno)
- Po potrebi omeni robne primere
Primerjaj ta dva opisa:
❌ "Weather"
✅ "Get the current weather for a city. Returns temperature, humidity, and conditions."
Drugi opis modelu zagotovi dovolj konteksta, da točno ve, kdaj poklicati to funkcijo in kaj bo dobil v zameno.
Blok parameters
Parametri sledijo formatu JSON Schema. Podprte vrste vključujejo:
string— znakovni nizinumber/integer— številaboolean– true/falsearray— seznamiobject— gnezdeni objektienum— seznam dovoljenih vrednosti
Polje required našteje obvezne parametre. Ostali so neobvezni – model se lahko odloči, da jih izpusti.
Opisi parametrov
Vsak parameter mora imeti svoj description. To modelu omogoča, da razume, katero vrednost naj posreduje:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Brez opisa mora model ugibati pričakovani format, kar vodi do napak.
Napredni parametri
Enums za omejevanje vrednosti
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Enums so še posebej uporabni: modelu sporočijo točne vrednosti, ki jih lahko uporabi, s čimer odpravijo napake v formatu.
Privzete vrednosti
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Model razume, da lahko ta parameter izpusti, če mu privzeta vrednost ustreza.
Gnezdeni objekti
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Najboljše prakse za opise
Opis je edini kanal, prek katerega model razume tvoje orodje – vsaka beseda tu šteje. Najprej specifičnost: „Iskanje izdelkov po imenu ali kategoriji v katalogu” modelu točno pove, kdaj se to orodje uporablja, medtem ko „Iskanje izdelkov” pušča prostor za ugibanje. Nato formati: navedba „Datum v formatu ISO 8601 (LLLL-MM-DD)” v opisu parametra odpravi polovico napak pri argumentih, saj model replicira format, ki mu ga pokažeš. Omejitve so del pogodbe: „Največ 50 rezultatov na klic” prepreči, da bi modelu obljubil uporabniku popolnost, ki je orodje ne more zagotoviti. In opis vračene vrednosti – „Vrne objekt s ceno, razpoložljivostjo in opisom” – pomaga modelu pri načrtovanju vnaprej: ve, kaj bo imel na voljo, še preden pokliče funkcijo.
Ključne ugotovitve
- Vsako orodje je definirano z
name,descriptioninparameters - Opis je dejavnik št. 1 za kakovost klica – vanj vloži čas
- Imena morajo biti edinstvena in v zapisu snake_case
- Uporabi
enumza omejitev možnih vrednosti - Vsak parameter mora imeti svoj opis s pričakovanim formatom
- Polje
requiredloči obvezne parametre od neobveznih