JSON shēmas un apraksti
Šajā lapā
Rīku valoda: JSON shēma
Lai Grok varētu izsaukt tavas funkcijas, tam ir jāzina, ko tās dara un kādus parametrus tās sagaida. Tieši šo uzdevumu pilda JSON shēmas. Katrs rīks tiek aprakstīts ar strukturētu objektu, kas satur trīs būtiskas informācijas daļas: nosaukumu, aprakstu un parametru shēmu.
Rīka definīcijas uzbūve
Lūk, pilnīga rīka struktūra tāda, kādu to sagaida 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"]
}
}
Apskatīsim katru lauku atsevišķi:
Lauks type
Pielāgotām funkcijām vienmēr ir vērtība "function"". Pastāv citi tipi iebūvētiem rīkiem (web_search, code_interpreter), taču tavām pašu funkcijām tas vienmēr būs ”function”`.
Lauks name
Tava funkcijas tehniskais nosaukums. Tam ir jābūt:
- Unikālam starp visiem pieprasījumā esošajiem rīkiem
- Aprakstošam:
get_weather, nevisfn1 - Rakstītam snake_case formātā pēc konvencijas:
search_products,create_ticket - Īsam, bet skaidram: modelis izmanto šo nosaukumu, lai izlemtu, kuru rīku izsaukt
Lauks description
Šis ir vissvarīgākais lauks izsaukumu kvalitātei. Modelis galvenokārt paļaujas uz aprakstu, lai izlemtu, kad un kā izmantot rīku. Labam aprakstam:
- Vienā teikumā jāpaskaidro, ko funkcija dara
- Jānorāda, kad to lietot (ja tas nav acīmredzams)
- Jāmin robežgadījumi, ja nepieciešams
Salīdzini šos divus aprakstus:
❌ "Laikapstākļi"
✅ "Iegūst pašreizējos laikapstākļus konkrētai pilsētai. Atgriež temperatūru, mitrumu un apstākļus."
Otrais variants sniedz modelim pietiekami daudz konteksta, lai tas precīzi zinātu, kad izsaukt šo funkciju un ko tas saņems pretī.
Bloks parameters
Parametri seko JSON shēmas formātam. Atbalstītie tipi ietver:
string— rakstzīmju virknesnumber/integer— skaitļiboolean— patiess/nepatiessarray— sarakstiobject— ligzdoti objektienum— atļauto vērtību saraksts
Masīvs required uzskaita obligātos parametrus. Pārējie ir opcionāli — modelis var izvēlēties tos izlaist.
Parametru apraksti
Katram parametram ir jābūt savam description. Tieši tas ļauj modelim saprast, kāda vērtība jānodod:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Bez apraksta modelim ir jāmin paredzētais formāts, kas noved pie kļūdām.
Izvērsti parametri
Enumerācijas vērtību ierobežošanai
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Enumerācijas (enum) ir īpaši noderīgas: tās norāda modelim precīzas vērtības, ko tas drīkst izmantot, tādējādi novēršot formāta kļūdas.
Noklusējuma vērtības
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Modelis saprot, ka šo parametru var izlaist, ja der noklusējuma vērtība.
Ligzdoti objekti
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Labākā prakse aprakstu veidošanā
Apraksts ir vienīgais kanāls, caur kuru modelis saprot tavu rīku — katram vārdam šeit ir nozīme. Prioritāte ir specifiskumam: „Meklē produktus pēc nosaukuma vai kategorijas katalogā” precīzi norāda modelim, kad šis rīks ir piemērots, turpretī „Meklē produktus” liek tam minēt. Tālāk seko formāti: norādot „Datums ISO 8601 formātā (GGGG-MM-DD)” parametra aprakstā, tu novērsi pusi no argumentu kļūdām, jo modelis atkārtos tev parādīto formātu. Ierobežojumi ir līguma sastāvdaļa: „Maksimums 50 rezultāti vienā izsaukumā” neļauj modelim solīt lietotājam pilnīgumu, ko rīks nenodrošinās. Un visbeidzot, atgriezeniskās vērtības aprakstīšana — „Atgriež objektu ar cenu, pieejamību un aprakstu” — palīdz modelim plānot uz priekšu: tas zina, kas tam būs pieejams, vēl pirms izsaukuma veikšanas.
Galvenās atziņas
- Katrs rīks tiek definēts ar
name,descriptionunparameters - Apraksts ir galvenais faktors izsaukumu kvalitātē — ieguldi tajā laiku
- Nosaukumiem jābūt unikāliem un rakstītiem snake_case formātā
- Izmanto
enum, lai ierobežotu iespējamās vērtības - Katram parametram jābūt savam aprakstam ar paredzēto formātu
- Masīvs
requiredatdala obligātos parametrus no opcionālajiem