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

Sainigh Feidhmeanna le Scéama JSON

Ceacht 3 as 14 Nuashonraithe 29 Iúil 2026 Forbróir
Ar an leathanach seo
  1. An conradh idir do chód agus an tsamhail
  2. Anatamaíocht shonraíochta uirlise
  3. Cineálacha Scéama JSON a dtacaítear leo
  4. Sampla iomlán: dhá fheidhm chomhlántacha
  5. Paraiméadair éigeantach vs roghnach
  6. Dea-chleachtais le haghaidh cur síos
  7. Príomhphointí

An conradh idir do chód agus an tsamhail

Chun go n-éireoidh leis an tsamhail Mistral do fheidhmeanna a ghlaowh, ní mór di a bheith ar an eolas faoi cad atá ann agus conas iad a úsáid. Is é seo ról Scéama JSON: formáid chaighdeánaithe a dhéanann cur síos ar gach feidhm—ainm na feidhme, cad a dhéanann sí, cé na paraiméadair a bhfuiltear ag súil leo, agus cé acu díobh sin atá éigeantach.

Coinnigh rud amháin i gcuimhne i rith an cheachta seo: ní fheiceann an tsamhail do chód Python riamh. Ní fheiceann sí ach an tsainmhíniú seo. Má láimhseálann do fheidhm aitheantóirí inlitreacha beaga go réidh ach nach luaitear é sin sa scéama, déanfaidh an tsamhail neamhaird ar an gcumas sin. Dá bheacht agus dá dea-dhoiciméadaithe is ea do scéama, is ea is cruinne a bheidh na hargóintí a ghintear.

Anatamaíocht shonraíochta uirlise

Leanann gach uirlis a sheoltar chuig API Mistral an struchtúr céanna:

tool = {
    "type": "function",
    "function": {
        "name": "function_name",
        "description": "Clear description of what the function does",
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Parameter description"
                },
                "param2": {
                    "type": "integer",
                    "description": "Parameter description"
                }
            },
            "required": ["param1"]
        }
    }
}
RéimseRól
typeI gcónaí "function" (d’fhéadfadh cineálacha eile a bheith ann amach anseo)
function.nameAinm beacht do fheidhme Python—seo an rud a thugann an tsamhail ar ais i tool_calls
function.descriptionAbairt shoiléir a chuidíonn leis an tsamhail an fheidhm cheart a roghnú
function.parametersOibiacht Scéama JSON a dhéanann cur síos ar na paraiméadair a bhfuiltear ag súil leo
requiredAn liosta paraiméadar éigeantach

Cineálacha Scéama JSON a dtacaítear leo

Tá an foclóir cineálacha atá ar fáil chun paraiméadair a chur síos teoranta d’aon ghnó, agus treoraíonn gach cineál an tsamhail ar bhealach difriúil. Déanann enum, go háirithe, níos mó ná doiciméadú: dúnann sé an doras ar luachanna cumtha.

# String — téacs saor nó srianta
{"type": "string", "description": "Transaction ID"}

# String with enum — luachanna teoranta
{"type": "string", "enum": ["asc", "desc"], "description": "Sort order"}

# Integer — slánuimhir
{"type": "integer", "description": "Number of results to return"}

# Number — uimhir dheachúlach
{"type": "number", "description": "Amount in euros"}

# Boolean — fíor/bréagach
{"type": "boolean", "description": "Include canceled transactions"}

# Array — liosta luachanna
{
    "type": "array",
    "items": {"type": "string"},
    "description": "List of transaction IDs"
}

# Object — oibiacht neadaithe
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Shipping address"
}

Déan idirdhealú soiléir idir integer agus number: éilíonn méid in euro cosúil le 125.50 number, ach is integer é líon na dtorthaí le tabhairt ar ais. Má shainíonn tú méid mar integer, cuirfidh an tsamhail slánú air.

Sampla iomlán: dhá fheidhm chomhlántacha

Seo sampla réadúil le dhá fheidhm a bhaineann le híocaíochtaí, faoi inspioráid ó dhoiciméadú oifigiúil Mistral:

tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Retrieves the status of a payment (paid, pending, failed) "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_date",
            "description": "Retrieves the date when a payment was made "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

Bíonn an paraiméadar céanna, transaction_id, ag teastáil ón dá fheidhm, ach caithfidh an tsamhail roghnú eatarthu. Braitheann an roghnú seo go hiomlán ar chur síos na feidhme. Mapáiltear “An ndearna an íocaíocht seo?” go retrieve_payment_status; mapáiltear “Cathain a rinneadh é?” go retrieve_payment_date. Dá mba rud é gur scríobh tú dhá chur síos doiléir, inmhalartaithe, bheadh an tsamhail mícheart leath na huaire—agus chuirfeá an locht ar an tsamhail nuair is sa scéama atá an fhadhb.

Paraiméadair éigeantach vs roghnach

Cinneann an idirdhealú idir paraiméadair éigeantach agus roghnach cad atá ceadaithe don tsamhail a fhágáil ar lár.

{
    "type": "function",
    "function": {
        "name": "search_transactions",
        "description": "Searches for transactions based on various criteria",
        "parameters": {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string",
                    "enum": ["paid", "pending", "failed"],
                    "description": "Filter by payment status"
                },
                "date_from": {
                    "type": "string",
                    "description": "Start date in YYYY-MM-DD format"
                },
                "date_to": {
                    "type": "string",
                    "description": "End date in YYYY-MM-DD format"
                },
                "min_amount": {
                    "type": "number",
                    "description": "Minimum amount in euros"
                }
            },
            "required": ["status"]
        }
    }
}

Anseo, níl ach status éigeantach; ní chuirtear na paraiméadair eile san áireamh ach má luaíonn an t-úsáideoir iad. Déan comparáid idir dhá fhoirmliú. Maidir le “Taispeáin na híocaíochtaí teipthe dom”, gineann an tsamhail {"status": "failed"} go simplí. Maidir le “Taispeáin na híocaíochtaí teipthe ó Mhárta 2026”, cuireann sí date_from agus date_to léi féin. Dá mba éigeantach na dátaí sin, bhrisfeadh sé an chéad cheist, nó níos measa, bhrúfadh sé an tsamhail chun raon dátaí a chumadh.

Dea-chleachtais le haghaidh cur síos

Bíonn tionchar díreach ag cáilíocht an chur síos ar chruinneas na samhla. Tá na frithshamplaí thíos níos oideachasaí ná aon riail theibí.

# Bad — too vague
{"description": "Retrieves data"}

# Good — precise and contextual
{"description": "Retrieves the status of a payment (paid, pending, failed) "
                "based on the unique transaction ID"}

# Bad — no description for the parameter
{"transaction_id": {"type": "string"}}

# Good — description with example
{"transaction_id": {
    "type": "string",
    "description": "Unique transaction ID (format: T followed by 4 digits, e.g., T1001)"
}}

Luann cur síos maith in abairt amháin cad a dhéanann an fheidhm, sonraíonn sé an fhormáid a bhfuiltear ag súil léi do gach paraiméadar, agus soláthraíonn sé sampla nuair nach bhfuil an fhormáid sin follasach—is fearr T1001 ná “aitheantóir idirbhirt”. Nuair atá luachanna féideartha teoranta, ná déan cur síos orthu i bprós: dearbhaigh iad le enum. Sin an t-aon bhealach chun iad a dhéanamh ceangailteach.

Príomhphointí

  • Is é Scéama JSON an conradh idir do chód agus an tsamhail—déanann sé cur síos ar do fheidhmeanna gan an cód a nochtadh
  • Tá name, description, agus parameters de chineál sonraithe ag gach uirlis
  • Áirítear string, integer, number, boolean, array, agus object sna cineálacha a dtacaítear leo
  • Déanann an liosta required idirdhealú idir paraiméadair éigeantach agus cinn roghnacha
  • Feabhsaíonn cur síos cruinn le samplaí cruinneas na samhla go suntasach