Iddefinixxi l-Funzjonijiet b'JSON Schema
F'din il-paġna
Il-kuntratt bejn il-kodiċi tiegħek u l-mudell
Biex il-mudell Mistral isejjaħ il-funzjonijiet tiegħek, irid ikun jaf x’jeżisti u kif jużahom. Dan huwa r-rwol ta’ JSON Schema: format standardizzat li jiddeskrivi kull funzjoni—l-isem tagħha, x’tagħmel, liema parametri tistenna, u liema minnhom huma obbligatorji.
Żomm ħaġa waħda f’moħħok matul din il-lezzjoni: il-mudell qatt ma jara l-kodiċi Python tiegħek. Jara biss din l-ispeċifikazzjoni. Jekk il-funzjoni tiegħek timmaniġġja ID b’ittri żgħar mingħajr problemi iżda l-iskema ma tgħid hekk, il-mudell jinjora dik il-kapaċità. Kemm ikun preċiż u ddokumentat tajjeb l-iskema tiegħek, daqshekk ikunu preċiżi l-argumenti ġġenerati.
L-anatomija ta’ speċifikazzjoni ta’ għodda
Kull għodda mibgħuta lill-API ta’ Mistral issegwi l-istess struttura:
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"]
}
}
}
| Qasam | Rwol |
|---|---|
type | Dejjem "function" (tipi oħra jistgħu jeżistu fil-futur) |
function.name | L-isem eżatt tal-funzjoni Python tiegħek—dan huwa dak li l-mudell jirritorna f’tool_calls |
function.description | Sentenza ċara li tgħin lill-mudell jagħżel il-funzjoni t-tajba |
function.parameters | Oġġett JSON Schema li jiddeskrivi l-parametri mistennija |
required | Il-lista ta’ parametri obbligatorji |
Tipi ta’ JSON Schema appoġġjati
Il-vokabolarju tat-tipi disponibbli biex jiddeskrivi l-parametri huwa ristrett intenzjonalment, u kull tip jiggwida lill-mudell b’mod differenti. enum, b’mod partikolari, jagħmel aktar milli jiddokumenta: jagħlaq il-bieb għal valuri inventati.
# String — test liberu jew ristrett
{"type": "string", "description": "Transaction ID"}
# String b'enum — valuri limitati
{"type": "string", "enum": ["asc", "desc"], "description": "Sort order"}
# Integer — numru sħiħ
{"type": "integer", "description": "Number of results to return"}
# Number — numru deċimali
{"type": "number", "description": "Amount in euros"}
# Boolean — true/false
{"type": "boolean", "description": "Include canceled transactions"}
# Array — lista ta' valuri
{
"type": "array",
"items": {"type": "string"},
"description": "List of transaction IDs"
}
# Object — oġġett imbejjat
{
"type": "object",
"properties": {
"city": {"type": "string"},
"country": {"type": "string"}
},
"description": "Shipping address"
}
Agħmel distinzjoni ċara bejn integer u number: ammont f’euro bħal 125.50 jeħtieġ number, filwaqt li għadd ta’ riżultati li għandhom jiġu rritornati huwa integer. Jekk tiddikjara ammont bħala integer, il-mudell se jħallih tond.
Eżempju sħiħ: żewġ funzjonijiet komplementari
Hawnhekk hemm eżempju realistiku b’żewġ funzjonijiet relatati mal-ħlasijiet, ispirati mid-dokumentazzjoni uffiċjali ta’ 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"]
}
}
}
]
Iż-żewġ funzjonijiet jistennew eżattament l-istess parametru, transaction_id, madankollu l-mudell irid jagħżel bejniethom. Din l-għażla tiddependi kompletament fuq id-deskrizzjoni tal-funzjoni. “Għadda dan il-ħlas?” timmappja ma’ retrieve_payment_status; “Meta sar?” timmappja ma’ retrieve_payment_date. Jekk kellek tikteb żewġ deskrizzjonijiet vagi u interchangeabbli, il-mudell ikun żbaljat nofs il-ħin—u inti tlaħħaq lill-mudell meta l-ħtija tkun fl-iskema.
Parametri meħtieġa vs opzjonali
Id-distinzjoni bejn parametri meħtieġa u opzjonali tiddetermina x’jista’ jħalli barra l-mudell.
{
"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"]
}
}
}
Hawnhekk, biss status huwa meħtieġ; il-parametri l-oħra huma inklużi biss jekk l-utsem isemmiha. Qabbel żewġ formulazzjonijiet. Għal “Uri l-ħlasijiet falluti,” il-mudell jiġġenera sempliċiment {"status": "failed"}. Għal “Uri l-ħlasijiet falluti minn Marzu 2026,” iżid date_from u date_to waħdu. Li tagħmel dawk id-dati meħtieġa kien ikisser l-ewwel mistoqsija, jew agħar, timbotta lill-mudell biex jinventa firxa ta’ dati.
L-aħjar prattiki għad-deskrizzjonijiet
Il-kwalità tad-deskrizzjoni taffettwa direttament il-preċiżjoni tal-mudell. Il-kontroeżempji hawn taħt huma aktar instruttivi minn kwalunkwe regola astratta.
# Ħażin — vag wisq
{"description": "Retrieves data"}
# Tajjeb — preċiż u kuntestwali
{"description": "Retrieves the status of a payment (paid, pending, failed) "
"based on the unique transaction ID"}
# Ħażin — l-ebda deskrizzjoni għall-parametru
{"transaction_id": {"type": "string"}}
# Tajjeb — deskrizzjoni b'eżempju
{"transaction_id": {
"type": "string",
"description": "Unique transaction ID (format: T followed by 4 digits, e.g., T1001)"
}}
Deskrizzjoni tajba tiddikjara f’sentenza waħda x’tagħmel il-funzjoni, tispeċifika l-format mistenni għal kull parametru, u tipprovdi eżempju kull meta dak il-format ma jkunx ovvju—T1001 huwa aħjar minn “transaction ID”. Meta l-valuri possibbli huma limitati, tiddeskrivihomx fil-proża: iddikjarahom b’enum. Din hija l-unika biex tagħmilhom vinkolanti.
Punti Ewlenin
- JSON Schema huwa l-kuntratt bejn il-kodiċi tiegħek u l-mudell—jiddeskrivi l-funzjonijiet tiegħek mingħajr ma jesponi l-kodiċi
- Kull għodda għandha
name,description, uparametersittipjati - It-tipi appoġġjati jinkludu
string,integer,number,boolean,array, uobject - Il-lista
requiredtiddistingwi l-parametri obbligatorji minn dawk opzjonali - Deskrizzjonijiet preċiżi b’eżempji jtejbu b’mod sinifikanti l-preċiżjoni tal-mudell