JSON schemos ir aprašymai
Šiame puslapyje
Įrankių kalba: JSON schema
Kad „Grok“ galėtų iškviesti tavo funkcijas, jis turi žinoti, ką jos daro ir kokių parametrų tikisi. Būtent tam skirtos JSON schemos. Kiekvienas įrankis aprašomas struktūruotu objektu, kuriame yra trys esminės dalys: pavadinimas, aprašymas ir parametrų schema.
Įrankio apibrėžimo sandara
Štai pilna įrankio struktūra, kokios tikisi „Grok“ API:
{
"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"]
}
}
Panagrinėkime kiekvieną laukelį atskirai:
Laukelis type
Tavo pačių kūriamoms funkcijoms visada nustatyk reikšmę "function". Egzistuoja ir kitų tipų integruotiems įrankiams (pvz., web_search, code_interpreter"), tačiau tavo funkcijoms tai visada bus ”function”`.
Laukelis name
Tai techninis tavo funkcijos pavadinimas. Jis privalo būti:
- Unikalus visų užklausoje esančių įrankių atžvilgiu
- Aprašomasis: naudok
get_weather, o nefn1 - Rašomas snake_case formatu (pagal susitarimą):
search_products,create_ticket - Trumpas, bet aiškus: modelis naudoja šį pavadinimą spręsdamas, kurį įrankį iškviesti
Laukelis description
Tai svarbiausias laukelis kvietimų kokybei. Modelis pirmiausia remiasi aprašymu, kad nuspręstų, kada ir kaip naudoti įrankį. Geras aprašymas:
- Vienu sakiniu paaiškina, ką funkcija daro
- Nurodo, kada ją naudoti (jei tai nėra akivaizdu)
- Prireikus paminimi ribiniai atvejai
Palygink šiuos du aprašymus:
❌ "Weather"
✅ "Get the current weather for a city. Returns temperature, humidity, and conditions."
Antrasis variantas suteikia modeliui pakankamai konteksto, kad jis tiksliai žinotų, kada iškviesti šią funkciją ir ko tikėtis atsakyme.
Blokas parameters
Parametrai turi atitikti JSON Schema formatą. Palaikomi tipai:
string– teksto eilutėsnumber/integer– skaičiaiboolean– true/false reikšmėsarray– sąrašaiobject– įdėtieji objektaienum– leistinų reikšmių sąrašas
Masyvas required išvardija privalomus parametrus. Kiti yra neprivalomi – modelis gali nuspręsti jų nepateikti.
Parametrų aprašymai
Kiekvienas parametras turėtų turėti savo description. Būtent tai leidžia modeliui suprasti, kokią reikšmę perduoti:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Be aprašymo modelis turi spėlioti tikėtiną formatą, o tai dažnai lemia klaidas.
Išplėstiniai parametrai
Enum reikšmėms apriboti
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
enum yra ypač naudingas: jis nurodo modeliui tikslias leistinas reikšmes, taip pašalindamas formato klaidas.
Numatytosios reikšmės
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Modelis supranta, kad šį parametrą gali praleisti, jei tinka numatytoji reikšmė.
Įdėtieji objektai
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Geriausios aprašymų kūrimo praktikos
Aprašymas yra vienintelis kanalas, kuriuo modelis supranta tavo įrankį – čia svarbus kiekvienas žodis. Pirmenybę teik specifiškumui: frazė „Search for products by name or category in the catalog“ modeliui tiksliai nurodo, kada taikyti šį įrankį, tuo tarpu „Search for products“ palieka jį spėlioti. Toliau – formatai: nurodymas „Date in ISO 8601 format (YYYY-MM-DD)“ parametro aprašyme pašalina pusę argumentų klaidų, nes modelis tiesiog atkartoja parodytą formatą. Ribos yra sutarties dalis: „Maximum 50 results per call“ neleidžia modeliui pažadėti naudotojui išsamumo, kurio įrankis negali suteikti. O grąžinamų duomenų aprašymas – „Returns an object with price, availability, and description“ – padeda modeliui planuoti iš anksto: jis žino, ką turės prieš netgi iškviesdamas funkciją.
Svarbiausi punktai
- Kiekvienas įrankis apibrėžiamas naudojant
name,descriptionirparameters - Aprašymas yra svarbiausias veiksnys kvietimų kokybei – skirk jam laiko
- Pavadinimai privalo būti unikalūs ir rašomi snake_case formatu
- Naudok
enum, kad apribotum galimas reikšmes - Kiekvienas parametras turėtų turėti savo aprašymą su numatomu formatu
- Masyvas
requiredatskiria privalomus parametrus nuo neprivalomų