Sainigh Feidhmeanna le Scéama JSON
Ar an leathanach seo
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éimse | Ról |
|---|---|
type | I gcónaí "function" (d’fhéadfadh cineálacha eile a bheith ann amach anseo) |
function.name | Ainm beacht do fheidhme Python—seo an rud a thugann an tsamhail ar ais i tool_calls |
function.description | Abairt shoiléir a chuidíonn leis an tsamhail an fheidhm cheart a roghnú |
function.parameters | Oibiacht Scéama JSON a dhéanann cur síos ar na paraiméadair a bhfuiltear ag súil leo |
required | An 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, agusparametersde chineál sonraithe ag gach uirlis - Áirítear
string,integer,number,boolean,array, agusobjectsna cineálacha a dtacaítear leo - Déanann an liosta
requiredidirdhealú idir paraiméadair éigeantach agus cinn roghnacha - Feabhsaíonn cur síos cruinn le samplaí cruinneas na samhla go suntasach