Skemi JSON u Deskrizzjonijiet
F'din il-paġna
Il-Lingwa tal-Għodod: Skema JSON
Biex Grok isejjaħ il-funzjonijiet tiegħek, irid ikun jaf x’jagħmlu u liema parametri jistennew. Dan huwa r-rwol tal-iskemi JSON. Kull għodda hija deskritta minn oġġett strutturat li fih tliet biċċiet essenzjali ta’ informazzjoni: isem, deskrizzjoni, u skema tal-parametri.
Anatomija ta’ Definizzjoni ta’ Għodda
Hawnhekk hija l-istruttura sħiħa ta’ għodda kif mistennija mill-API ta’ 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"]
}
}
Ejja nanalizzaw kull qasam:
Il-Qasam type
Dejjem "function" għal funzjonijiet personalizzati. Tipi oħra jeżistu għal għodod integrati (web_search, code_interpreter), iżda għall-funzjonijiet tiegħek stess, huwa dejjem "function".
Il-Qasam name
L-isem tekniku tal-funzjoni tiegħek. Irid ikun:
- Uniku fost l-għodod kollha fit-talba
- Deskrittiv:
get_weatherminflokfn1 - F’snake_case bħala konvenzjoni:
search_products,create_ticket - Qasir iżda espliċitu: il-mudell juża dan l-isem biex jiddeċiedi liema għodda sejjaħ
Il-Qasam description
Dan huwa l-qasam l-aktar importanti għall-kwalità tas-sejħa. Il-mudell jiddependi primarjament fuq id-deskrizzjoni biex jiddeċiedi meta u kif juża għodda. Deskrizzjoni tajba:
- Tispjega x’tagħmel il-funzjoni f’sentenza waħda
- Tispeċifika meta tużaha (jekk mhux ovvju)
- Tsemmi każijiet limitu jekk meħtieġ
Qabbel dawn iż-żewġ deskrizzjonijiet:
❌ "Weather"
✅ "Get the current weather for a city. Returns temperature, humidity, and conditions."
It-tieni tagħti lill-mudell biżżejjed kuntest biex ikun jaf eżattament meta jsejjaħ din il-funzjoni u x’se jirċievi lura.
Il-Blokk parameters
Il-parametri jsegwu l-format JSON Schema. It-tipi appoġġjati jinkludu:
string— sekwenzi ta’ karattrinumber/integer— numriboolean— vera/falzaarray— listiobject— oġġetti mbejjnaenum— lista ta’ valuri permessi
L-array required jelenka l-parametri mandatorji. L-oħrajn huma opzjonali — il-mudell jista’ jagħżel li jħallihom barra.
Deskrizzjonijiet tal-Parametri
Kull parametru għandu jkollu d-description tiegħu stess. Dan huwa dak li jippermetti lill-mudell jifhem liema valur jgħaddi:
{
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
}
}
Mingħajr deskrizzjoni, il-mudell irid jissuspetta l-format mistenni — li jwassal għal żbalji.
Parametri Avvanzati
Enums biex Tillimita l-Valuri
{
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "critical"],
"description": "Ticket priority level"
}
}
L-enums huma partikolarment utli: jgħidu lill-mudell l-eżatt valuri li jista’ juża, u jeliminaw żbalji tal-format.
Valuri Default
{
"limit": {
"type": "integer",
"default": 10,
"description": "Maximum number of results to return"
}
}
Il-mudell jifhem li jista’ jħalli barra dan il-parametru jekk il-valur default jaħdem.
Oġġetti Mbejjna
{
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string" }
},
"required": ["city"]
}
}
L-Aħjar Prattiki għad-Deskrizzjonijiet
Id-deskrizzjoni hija l-uniku kanal li permezz tiegħu l-mudell jifhem l-għodda tiegħek — kull kelma taħdem hemmhekk. L-ewwel, l-ispeċifiċità: “Fittex prodotti bl-isem jew bil-kategorija fil-katalgu” tgħid lill-mudell eżattament meta tapplika din l-għodda, filwaqt li “Fittex prodotti” iħallih jissuspetta. Imbagħad, il-formats: li tispeċifika “Data fil-format ISO 8601 (YYYY-MM-DD)” fid-deskrizzjoni ta’ parametru telimina nofs l-iżbalji tal-argumenti, għax il-mudell jirreplika l-format li turih. Il-limiti huma parti mill-kuntratt: “Massimu ta’ 50 riżultat għal kull sejħa” jipprevjeni lill-mudell milli jwiegħed lill-utent kompletezza li l-għodda ma tipprovdix. U li tiddeskrivi r-ritorn — “Jirritorna oġġett bi prezz, disponibbiltà u deskrizzjoni” — jgħin lill-mudell jippjana minn qabel: ikun jaf x’se jkollu għad-dispożizzjoni qabel ma jsejjaħ.
Punti Ewlenin
- Kull għodda hija definita minn
name,description, uparameters - Id-deskrizzjoni hija l-fattur numru 1 fil-kwalità tas-sejħa — invest ħin fiha
- L-ismijiet iridu jkunu uniċi u f’snake_case
- Uża
enumbiex tillimita l-valuri possibbli - Kull parametru għandu jkollu d-deskrizzjoni tiegħu stess bil-format mistenni
- L-array
requiredjiddistingwi l-parametri mandatorji minn dawk opzjonali