Schemele JSON și descrierile
Pe această pagină
Limbajul instrumentelor: Schema JSON
Pentru ca Grok să vă poată apela funcțiile, trebuie să știe ce fac acestea și ce parametri așteaptă. Acesta este rolul schemelor JSON. Fiecare instrument este descris printr-un obiect structurat care conține trei elemente esențiale: un nume, o descriere și o schemă de parametri.
Anatomia unei definiții de instrument
Iată structura completă a unui instrument așa cum o așteaptă API-ul 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"]
}
}
Să analizăm fiecare câmp:
Câmpul type
Este întotdeauna "function" pentru funcțiile personalizate. Există alte tipuri pentru instrumentele integrate (web_search, code_interpreter), dar pentru propriile dumneavoastră funcții, valoarea este invariabil "function".
Câmpul name
Numele tehnic al funcției dumneavoastră. Acesta trebuie să fie:
- Unic printre toate instrumentele din cerere
- Descriptiv:
get_weatherîn loc defn1 - În format snake_case conform convenției:
search_products,create_ticket - Scurt, dar explicit: modelul folosește acest nume pentru a decide ce instrument să apeleze
Câmpul description
Acesta este cel mai important câmp pentru calitatea apelurilor. Modelul se bazează în primul rând pe descriere pentru a decide când și cum să utilizeze un instrument. O descriere bună:
- Explică ce face funcția într-o singură propoziție
- Specifică când să o utilizați (dacă nu este evident)
- Menționează cazurile limită, dacă este necesar
Comparați aceste două descrieri:
❌ "Weather"
✅ "Get the current weather for a city. Returns temperature, humidity, and conditions."
A doua variantă oferă modelului suficient context pentru a ști exact când să apeleze această funcție și ce va primi în schimb.
Blocul parameters
Parametrii urmează formatul JSON Schema. Tipurile suportate includ:
string— șiruri de caracterenumber/integer— numereboolean— adevărat/falsarray— listeobject— obiecte imbricateenum— listă de valori permise
Array-ul required listează parametrii obligatorii. Ceilalți sunt opționali — modelul poate alege să îi omită.
Descrierile parametrilor
Fiecare parametru ar trebui să aibă propria sa description. Acest lucru permite modelului să înțeleagă ce valoare să transmită:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Fără o descriere, modelul trebuie să ghicească formatul așteptat, ceea ce duce la erori.
Parametri avansați
Enumerări pentru constrângerea valorilor
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
Enumerările sunt deosebit de utile: ele indică modelului valorile exacte pe care le poate utiliza, eliminând erorile de format.
Valori implicite
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Modelul înțelege că poate omite acest parametru dacă valoarea implicită este adecvată.
Obiecte imbricate
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
Cele mai bune practici pentru descrieri
Descrierea este singurul canal prin care modelul înțelege instrumentul dumneavoastră — fiecare cuvânt contează. Prioritizați specificitatea: „Caută produse după nume sau categorie în catalog“ îi spune modelului exact când se aplică acest instrument, în timp ce „Caută produse“ îl lasă să ghicească. Urmează formatele: specificarea „Dată în format ISO 8601 (YYYY-MM-DD)“ într-o descriere de parametru elimină jumătate din erorile de argumente, deoarece modelul replică formatul pe care i-l arătați. Limitele fac parte din contract: „Maximum 50 de rezultate per apel“ împiedică modelul să promită utilizatorului o exhaustivitate pe care instrumentul nu o poate oferi. Iar descrierea returnării — „Returnează un obiect cu preț, disponibilitate și descriere“ — ajută modelul să planifice dinainte: știe ce va avea la dispoziție chiar înainte de a face apelul.
Puncte cheie
- Fiecare instrument este definit printr-un
name, odescriptionșiparameters - Descrierea este factorul nr. 1 pentru calitatea apelurilor — investiți timp în ea
- Numele trebuie să fie unice și în format snake_case
- Utilizați
enumpentru a constrânge valorile posibile - Fiecare parametru ar trebui să aibă propria descriere cu formatul așteptat
- Array-ul
requireddistinge parametrii obligatorii de cei opționali