Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Scéimí agus Cur síosanna JSON

Ceacht 2 as 14 Nuashonraithe 29 Iúil 2026 Forbróir
Ar an leathanach seo
  1. Teanga na nUirlisí: Scéim JSON
  2. Anatamaí Sainmhínithe Uirlise
  3. Cur síosanna ar Pharaiméadair
  4. Paraiméadair Chasta
  5. Dea-Chleachtais le haghaidh Cur síosanna
  6. Príomhphointí

Teanga na nUirlisí: Scéim JSON

Chun go bhféadfadh Grok do fheidhmeanna a ghlaowh, ní mór dó a bheith ar an eolas faoi cad a dhéanann siad agus cé na paraiméadair a bhfuil súil leo. Sin ról na scéimeanna JSON. Déantar cur síos ar gach uirlis le réad struchtúrtha ina bhfuil trí phíosa eolais riachtanacha: ainm, cur síos, agus scéim paraiméadar.

Anatamaí Sainmhínithe Uirlise

Seo struchtúr iomlán uirlise mar a bhfuil súil leis ón API 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"]
  }
}

Déanaimis anailís ar gach réimse:

An Réimse type

Bíonn sé seo "function" i gcónaí do fheidhmeanna saincheaptha. Tá cineálacha eile ann d’uirlisí ionsuite (web_search, code_interpreter), ach do d’fheidhmeanna féin, is "function" atá ann i gcónaí.

An Réimse name

Is é seo ainm teicniúil do fheidhme. Caithfidh sé a bheith:

  • Uathúil i measc na n-uirlisí go léir sa hiarratas
  • Cur síosach: get_weather seachas fn1
  • I snake_case de réir gnáthais: search_products, create_ticket
  • Gairid ach soiléir: úsáideann an tsamhail an t-ainm seo chun cinneadh a dhéanamh cén uirlis a ghlaofar

An Réimse description

Seo an réimse is tábhachtaí le haghaidh cáilíocht na nglaonna. Braitheann an tsamhail go príomha ar an gcur síos chun cinneadh a dhéanamh cathain agus conas uirlis a úsáid. Is éard atá i gcur síos maith:

  • Míniú ar cad a dhéanann an fheidhm in aon abairt amháin
  • Sonrú cathain a úsáidfear é (mura bhfuil sé follasach)
  • Lua ar cásanna imeallacha más gá

Déan comparáid idir an dá chur síos seo:

❌ "Aimsir"
✅ "Faigh an aimsir reatha do chathair. Tugann sé ar ais an teocht, an taise, agus na coinníollacha."

Tugann an dara ceann comhthéacs leordhóthanach don tsamhail chun a fhios go beacht cathain a ghlaofar an fheidhm seo agus cad a gheobhaidh sí ar ais.

An Bloc parameters

Leanann paraiméadair formáid Scéim JSON. I measc na gcineálacha a dtacaítear leo tá:

  • string — teaghráin charachtair
  • number / integer — uimhreacha
  • boolean — fíor/bréagach
  • array — liostaí
  • object — réada neadaithe
  • enum — liosta de luachanna ceadaithe

Liostaíonn an eagair required na paraiméadair éigeantacha. Tá cinn eile roghnach — féadfaidh an tsamhail roghnú iad a fhágáil ar lár.

Cur síosanna ar Pharaiméadair

Ba chóir description a bheith ag gach paraiméadar. Is é seo a ligeann don tsamhail tuiscint a fháil ar cén luach a chur ar fáil:

{
  "date": {
    "type": "string",
    "description": "Date in YYYY-MM-DD format. If omitted, uses today's date."
  }
}

Gan cur síos, caithfidh an tsamhail buille faoi thuairim a dhéanamh faoin bhformáid a bhfuil súil léi — rud a fhágann go dtarlaíonn earráidí.

Paraiméadair Chasta

Enum chun Luachanna a Shrianadh

{
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high", "critical"],
    "description": "Ticket priority level"
  }
}

Tá enum an-úsáideach: insíonn siad don tsamhail na luachanna cruinne is féidir léi a úsáid, rud a chuireann deireadh le hearráidí formáide.

Luachanna Réamhshocraithe

{
  "limit": {
    "type": "integer",
    "default": 10,
    "description": "Maximum number of results to return"
  }
}

Tuigeann an tsamhail gur féidir léi an paraiméadar seo a fhágáil ar lár má oireann an luach réamhshocraithe.

Réada Neadaite

{
  "address": {
    "type": "object",
    "properties": {
      "street": { "type": "string" },
      "city": { "type": "string" },
      "zip": { "type": "string" }
    },
    "required": ["city"]
  }
}

Dea-Chleachtais le haghaidh Cur síosanna

Is é an cur síos an t-aon chainéal trína dtuigeann an tsamhail do uirlis — oibríonn gach focal ann. Tosaigh le sonrachas: insíonn “Cuardaigh táirgí de réir ainm nó catagóire sa chatalóg” don tsamhail go beacht cathain a bhaineann an uirlis seo leis, ach fágann “Cuardaigh táirgí” faoi bhuille faoi thuairim í. Ansin, formáidí: cuireann “Dáta i bhformáid ISO 8601 (BBBB-MM-LL)” i gcur síos paraiméadair deireadh le leath d’earráidí argóintí, toisc go ndéanann an tsamhail athsheinm ar an bhformáid a thaispeánann tú di. Is cuid den chonradh iad teorainneacha: coscaíonn “Uasmhéid 50 toradh in aghaidh an ghlao” ar an tsamhail gealltanas iomláine a thabhairt don úsáideoir nach soláthróidh an uirlis. Agus cabhraíonn cur síos ar an toradh — “Tugann sé ar ais réad le praghas, infhaighteacht, agus cur síos” — leis an tsamhail pleanáil chun tosaigh: tá a fhios aici cad a bheidh ar fáil aici sula nglaofar fiú.

Príomhphointí

  • Sainmhínítear gach uirlis le name, description, agus parameters
  • Is é an cur síos an fachtóir is tábhachtaí i gcáilíocht an ghlao — caith am air
  • Caithfidh ainmneacha a bheith uathúil agus i snake_case
  • Úsáid enum chun na luachanna féideartha a shrianadh
  • Ba chóir cur síos a bheith ag gach paraiméadar leis an bhformáid a bhfuil súil léi
  • Déanann an eagair required idirdhealú idir paraiméadair éigeantacha agus cinn roghnacha