Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Skemi JSON u Deskrizzjonijiet

Lezzjoni 2 / 14 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Il-Lingwa tal-Għodod: Skema JSON
  2. Anatomija ta’ Definizzjoni ta’ Għodda
  3. Deskrizzjonijiet tal-Parametri
  4. Parametri Avvanzati
  5. L-Aħjar Prattiki għad-Deskrizzjonijiet
  6. Punti Ewlenin

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_weather minflok fn1
  • 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’ karattri
  • number / integer — numri
  • boolean — vera/falza
  • array — listi
  • object — oġġetti mbejjna
  • enum — 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, u parameters
  • 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 enum biex tillimita l-valuri possibbli
  • Kull parametru għandu jkollu d-deskrizzjoni tiegħu stess bil-format mistenni
  • L-array required jiddistingwi l-parametri mandatorji minn dawk opzjonali