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

Iddefinixxi l-Funzjonijiet b'JSON Schema

Lezzjoni 3 / 14 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Il-kuntratt bejn il-kodiċi tiegħek u l-mudell
  2. L-anatomija ta’ speċifikazzjoni ta’ għodda
  3. Tipi ta’ JSON Schema appoġġjati
  4. Eżempju sħiħ: żewġ funzjonijiet komplementari
  5. Parametri meħtieġa vs opzjonali
  6. L-aħjar prattiki għad-deskrizzjonijiet
  7. Punti Ewlenin

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"]
        }
    }
}
QasamRwol
typeDejjem "function" (tipi oħra jistgħu jeżistu fil-futur)
function.nameL-isem eżatt tal-funzjoni Python tiegħek—dan huwa dak li l-mudell jirritorna f’tool_calls
function.descriptionSentenza ċara li tgħin lill-mudell jagħżel il-funzjoni t-tajba
function.parametersOġġett JSON Schema li jiddeskrivi l-parametri mistennija
requiredIl-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, u parameters ittipjati
  • It-tipi appoġġjati jinkludu string, integer, number, boolean, array, u object
  • Il-lista required tiddistingwi l-parametri obbligatorji minn dawk opzjonali
  • Deskrizzjonijiet preċiżi b’eżempji jtejbu b’mod sinifikanti l-preċiżjoni tal-mudell