Iddefinixxi Funzjonijiet f'Python
F'din il-paġna
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.partialhuwa ideali biex timla minn qabel parametri bħal konnessjonijiet DB jew DataFramestool_choicejikkontrolla 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)