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

Iddefinixxi Funzjonijiet f'Python

Lezzjoni 4 / 14 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Mit-Teorija għall-Kodiċi
  2. Installa s-SDK ta’ Mistral
  3. Oħloq Funzjonijiet Python
  4. Ikteb Speċifikazzjonijiet JSON
  5. Organizza l-Funzjonijiet f’Dizzjunarju
  6. L-Għażla tool_choice
  7. Punti Ewlenin

Mit-Teorija għall-Kodiċi

Issa li fhimt il-proċess ta’ ħames passi u l-istruttura tal-JSON Schema, wasal iż-żmien tikteb kodiċi Python reali. F’din il-lezzjoni, se toħloq funzjonijiet, tabbozza l-ispeċifikazzjonijiet tagħhom, u tħejji kollox għall-API ta’ Mistral—kull ma jeħtieġ li jeżisti qabel ma tagħmel l-ewwel sejħa tan-netwerk.

Installa s-SDK ta’ Mistral

Ibda billi tinstalla l-pakkett uffiċjali:

pip install mistralai

Sussegwentement, ikkonfigura ċ-ċavetta tal-API tiegħek. L-aħjar prattika timla li qatt ma tħalliha miktuba direttament (hardcode) fil-fajls tas-sors tiegħek. Minflok, aqraha minn varjabbli tal-ambjent biex tkun tista’ timmetti l-kodiċi tiegħek b’mod sikur fil-kontroll tal-verżjonijiet.

export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Oħloq Funzjonijiet Python

Ejja nħarsu lejn eżempju prattiku: sistema ta’ traċċar tal-pagamenti appoġġjata minn DataFrame ta’ Pandas. Dan huwa eżempju klassiku mid-dokumentazzjoni ta’ Mistral, u juri perfettament il-kunċett—hawnhekk, id-DataFrame jieħu r-rwol li database tieħu fil-produzzjoni.

import pandas as pd
import json

# Payment data
data = {
    "transaction_id": ["T1001", "T1002", "T1003", "T1004", "T1005"],
    "customer_id": ["C001", "C002", "C003", "C002", "C001"],
    "payment_amount": [125.50, 89.99, 350.00, 45.00, 210.75],
    "payment_date": ["2026-03-15", "2026-03-16", "2026-03-17", "2026-03-17", "2026-03-18"],
    "payment_status": ["paid", "paid", "pending", "paid", "failed"]
}
df = pd.DataFrame(data)

Li jmiss huwa l-kodiċi li attwalment jaċċessa dawn id-data. Dawn huma funzjonijiet standard ta’ Python; xejn fl-implimentazzjoni tagħhom jissuġġerixxi li LLM se jmexxihom.

def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
    """Retrieves the status of a payment by its ID."""
    if transaction_id in df["transaction_id"].values:
        status = df[df["transaction_id"] == transaction_id]["payment_status"].values[0]
        return json.dumps({"status": status})
    return json.dumps({"error": f"Transaction {transaction_id} not found"})


def retrieve_payment_date(df: pd.DataFrame, transaction_id: str) -> str:
    """Retrieves the date of a payment by its ID."""
    if transaction_id in df["transaction_id"].values:
        date = df[df["transaction_id"] == transaction_id]["payment_date"].values[0]
        return json.dumps({"date": date})
    return json.dumps({"error": f"Transaction {transaction_id} not found"})

Żewġ dettalji ta’ implimentazzjoni jistħoqqilhom attenzjoni. L-ewwel, dawn il-funzjonijiet dejjem jirritornaw stringa JSON, qatt oġġett Python mhux ipproċessat. Dan huwa l-format li l-mudell jistenna bħala riżultat ta’ għodda, allura json.dumps() huwa obbligatorju. It-tieni, huma jittrattaw b’mod espliċitu l-każ fejn transazzjoni ma tinstabx minflok ma jqajmu eċċezzjoni. Dan l-iżball, ifformat bħala JSON, jirritorna lill-mudell eżatt bħal kwalunkwe riżultat ieħor, u jippermettilu jinforma politely lill-utent li t-transazzjoni T9999 ma teżistix. Aktar tard fil-kors se tara għaliex dan ir-rifless huwa essenzjali.

Ikteb Speċifikazzjonijiet JSON

Kull funzjoni teħtieġ speċifikazzjoni biex il-mudell ikun jista’ jifhimha. Hawnhekk tapplika l-istruttura mil-lezzjoni preċedenti għaż-żewġ funzjonijiet ta’ hawn fuq—nota l-korrispondenza stretta bejn il-kampi name u l-ismijiet reali tal-funzjonijiet Python.

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": "Unique transaction identifier (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_date",
            "description": "Retrieves the date a payment was made "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Unique transaction identifier (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

Organizza l-Funzjonijiet f’Dizzjunarju

Il-mudell jirritorna isem funzjoni bħala stringa. Għandek bżonn mod biex timmappja dik l-istringa mal-oġġett callable korrispondenti mingħajr ma tirrikorri għal eval jew kaskata ta’ stqarrijiet if. Dizzjunarju ta’ dispatch (dispatch dictionary) isolvi din il-problema f’tliet linji.

from functools import partial

# Bind the DataFrame to each function
available_functions = {
    "retrieve_payment_status": partial(retrieve_payment_status, df),
    "retrieve_payment_date": partial(retrieve_payment_date, df),
}

functools.partial tindirizza diffikultà speċifika u reali. Il-funzjonijiet tiegħek jistennew żewġ argumenti—id-DataFrame u l-ID—imma l-mudell jipprovdi wieħed biss. Il-mudell ma jaf xejn dwar df, u lanqas għandu jaf. partial timla minn qabel dak l-ewwel parametru darba għal dejjem. Dan l-istess mekkaniżmu japplika għal konnessjonijiet ta’ database, klijenti HTTP, jew tokens ta’ awtentikazzjoni. L-invokazzjoni dinamika mbagħad issir trivjali.

function_name = "retrieve_payment_status"
function_params = {"transaction_id": "T1001"}

result = available_functions[function_name](**function_params)
# → '{"status": "paid"}'

L-Għażla tool_choice

Meta tibgħat dawn l-għodod lill-API, il-parametru tool_choice jiddeċiedi kemm tagħti libertà lill-mudell. Hemm tliet valuri possibbli.

# The model decides whether to use a tool or respond directly (default)
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)

# Force the model to use a tool
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="any"
)

# Prevent the model from using tools
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools,
    tool_choice="none"
)

Il-modalità "auto" hija l-aktar waħda komuni fil-produzzjoni għal raġuni tajba: assistent għat-traċċar tal-pagamenti għandu jkun kapaċi jgħid “hello” mingħajr ma jattiva query tad-database. Il-mudell jirrispondi direttament għal mistoqsijiet ġenerali u juża funzjonijiet biss meta jkun rilevanti. Lezzjoni sħiħa aktar tard fil-kors tkopri każijiet ta’ użu speċifiċi għal any u none.

Punti Ewlenin

  • Il-funzjonijiet iridu jirritornaw stringi JSON—qatt oġġetti Python mhux ipproċessati
  • Uża dizzjunarju ta’ dispatch biex timmappja l-ismijiet tal-funzjonijiet mal-implimentazzjonijiet tagħhom
  • functools.partial huwa ideali biex timla minn qabel parametri bħal konnessjonijiet DB jew DataFrames
  • tool_choice jikkontrolla jekk il-mudell jistax jew iridx juża funzjonijiet (auto, any, none)
  • Dejjem ittratta każijiet ta’ żball fil-funzjonijiet tiegħek (parametri mhux validi, data nieqsa)