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

Ġestjoni tal-Iżbalji

Lezzjoni 10 / 14 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. L-Iżbalji Huma Inevitabbli
  2. Qatt Ma Tħabi Żball mill-Mudell
  3. Eżekuttur Li Ma Jħalli Xejn Jgħaddi
  4. Iddistingwi bejn Fallimenti Transitorji u Permanenti
  5. L-API tal-Mistral Tista’ Tfalli Hija wkoll
  6. Ara X’Qed Jiġri Verament
  7. Punti Ewlenin

L-Iżbalji Huma Inevitabbli

Fil-produzzjoni, il-funzjonijiet ifallu. L-APIs esterni jaqgħu, l-IDs ma jeżistux, il-parametri mhumiex validi, u l-ħinijiet ta’ stennija (timeouts) jiskadu. Il-mistoqsija mhix “se jfalli?” iżda “kif nittrattaw il-falliment b’mod grazzjuż?” Tracker tal-pagamenti li jikkraċċja għax utent kiteb T9999 minflok T1001 mhuwiex sistema ta’ produzzjoni; hija demo.

L-aħbar tajba hija li għandek riżorsa hawnhekk li l-arkitetturi klassiċi ma għandhomx: il-mudell Mistral jista’ jifhem il-messaġġi ta’ żball li tibgħatlu lura u jadatta r-risposta tiegħu skont dan. Fejn backend tradizzjonali jrid ifassal messaġġ tal-UI għal kull kodiċi ta’ żball, inti tista’ tħalli lill-mudell jittraduċi l-falliment f’sentenza utli għall-utent. Għandek biss tagħtih l-informazzjoni.

Qatt Ma Tħabi Żball mill-Mudell

Din hija r-regola tad-deheb ta’ din il-lezzjoni. Irritorna żball fil-messaġġ tool eżattament kif tagħmel għal riżultat normali: bħala JSON strutturat. Ir-rifless oppost—li taqbad l-eċċezzjoni u tirritorna stringa vojta jew null—iġiegħel lill-mudell jemmen li l-funzjoni rnexxiet iżda sempliċiment ma kellha xejn x’tgħid. Dan jipproduċi l-aktar risposti konfużi possibbli.

def retrieve_payment_status(df, transaction_id: str) -> str:
    """Retrieves status with full error handling."""
    try:
        if transaction_id not in df["transaction_id"].values:
            return json.dumps({
                "error": "transaction_not_found",
                "message": f"Transaction {transaction_id} does not exist in the database."
            })

        status = df[df["transaction_id"] == transaction_id]["payment_status"].values[0]
        return json.dumps({"status": status, "transaction_id": transaction_id})

    except Exception as e:
        return json.dumps({
            "error": "internal_error",
            "message": f"Error retrieving data: {str(e)}"
        })

Żewġ oqsma huma biżżejjed: kodiċi tal-magna f’error u spjegazzjoni li tista’ tinftiehem mill-bniedem f’message. Il-kodiċi jippermetti lis-sistema ta’ monitoraġġ tiegħek tgħodd l-okkorrenzi; l-ispjegazzjoni tippermetti lill-mudell jifformula risposta utli. Ara x’jiġri b’transazzjoni li ma teżistix.

# User requests a non-existent transaction
messages = [{"role": "user", "content": "Status of payment T9999?"}]

# Model calls retrieve_payment_status(transaction_id="T9999")
# Your function returns: {"error": "transaction_not_found", ...}

# Model formulates:
# → "I couldn't find a transaction with ID T9999.
#     Could you check the number and try again?"

Ħadd ma kiteb dik is-sentenza. Din toriġina mill-kodiċi ta’ żball, u saħansitra tissuġġerixxi azzjoni korrettiva lill-utent.

Eżekuttur Li Ma Jħalli Xejn Jgħaddi

Li tipproteġi funzjoni mhix biżżejjed: is-saff li qed jiddispaċċja s-tool_calls għandu l-modalitajiet ta’ falliment tiegħu stess, indipendenti mil-loġika tan-negozju tiegħek. Il-mudell jista’ jalluċina isem ta’ funzjoni li ma teżistix fid-dizzjunarju tiegħek. Jista’ jipproduċi argumenti JSON malformattati—każ rari iżda reali ma’ skemi kumplessi. Jista’ wkoll jipprovdi JSON validu li ċ-ċwievet tiegħu ma jaqblux mas-sinjalura tal-Python, u jikkawża TypeError waqt **function_params. Kull wieħed minn dawn it-tliet każijiet jistħoqqilu l-kodiċi ta’ żball tiegħu stess għax kull wieħed jeħtieġ tiswija differenti min-naħa tiegħek.

def execute_tool_call(tool_call, available_functions):
    """Executes a tool_call with full error handling."""
    function_name = tool_call.function.name

    # Check if function exists
    if function_name not in available_functions:
        return {
            "role": "tool",
            "name": function_name,
            "content": json.dumps({
                "error": "function_not_found",
                "message": f"Function {function_name} is not available."
            }),
            "tool_call_id": tool_call.id
        }

    # Parse arguments
    try:
        function_params = json.loads(tool_call.function.arguments)
    except json.JSONDecodeError as e:
        return {
            "role": "tool",
            "name": function_name,
            "content": json.dumps({
                "error": "invalid_arguments",
                "message": f"Invalid JSON arguments: {str(e)}"
            }),
            "tool_call_id": tool_call.id
        }

    # Execute function
    try:
        result = available_functions[function_name](**function_params)
        return {
            "role": "tool",
            "name": function_name,
            "content": result,
            "tool_call_id": tool_call.id
        }
    except TypeError as e:
        return {
            "role": "tool",
            "name": function_name,
            "content": json.dumps({
                "error": "invalid_params",
                "message": f"Incompatible parameters: {str(e)}"
            }),
            "tool_call_id": tool_call.id
        }
    except Exception as e:
        return {
            "role": "tool",
            "name": function_name,
            "content": json.dumps({
                "error": "execution_error",
                "message": f"Execution error: {str(e)}"
            }),
            "tool_call_id": tool_call.id
        }

Innota li kull fergħa, inklużi l-fergħat ta’ falliment, tirritorna messaġġ tool sħiħ bl-tool_call_id tiegħu. Dan huwa essenzjali: l-API tiċħad storja fejn tool_call jibqa’ mingħajr tweġiba, u falliment sieket ikkawża żball ta’ validazzjoni fid-dawra li jmiss, ‘il bogħod mill-kawża reali.

Iddistingwi bejn Fallimenti Transitorji u Permanenti

Mhux l-iżbalji kollha huma ugwali. Transazzjoni nieqsa se tibqa’ nieqsa fit-tieni tentattiv; it-tentattiv mill-ġdid biss iħassar il-ħin. Madankollu, timeout tan-network jew servizz saturat għal mument spiss isolvi ruħu. Għal din it-tieni kategorija, tentattiv mill-ġdid b’backoff esponenzjali—sekonda, imbagħad tnejn, imbagħad erbgħa—jagħti lis-servizz il-ħin biex jirkupra mingħajr ma tħabbtu bi talbiet. Wara li tneħħi t-tentattivi, terġa’ lura għall-imġiba tas-soltu: JSON ta’ żball maħsub għall-mudell.

import time

def execute_with_retry(func, params, max_retries=3, base_delay=1.0):
    """Executes a function with exponential retry."""
    for attempt in range(max_retries):
        try:
            result = func(**params)
            return result
        except ConnectionError as e:
            if attempt < max_retries - 1:
                delay = base_delay * (2 ** attempt)
                time.sleep(delay)
            else:
                return json.dumps({
                    "error": "service_unavailable",
                    "message": f"Service unavailable after {max_retries} attempts.",
                    "details": str(e)
                })

L-API tal-Mistral Tista’ Tfalli Hija wkoll

Kollox hawn fuq jikkonċerna l-funzjonijiet tiegħek. Is-sejħa lejn l-API tal-Mistral innifisha hija punt ta’ falliment distint, immaniġġjat separatament: hawnhekk, m’hemm l-ebda mudell biex jispjega l-problema, peress li l-mudell huwa preċiżament dak li ma jintlaħaqx. HTTPValidationError ġeneralment jissinjala żball fl-istruttura tal-messaġġ jew tal-għodod tiegħek, li trid tiswih fil-kodiċi; eċċezzjonijiet oħra jirrelataw man-network jew mas-servizz u jiġu ttrattati bl-istess loġika ta’ tentattiv mill-ġdid bħal hawn fuq.

from mistralai.client import Mistral
from mistralai.client.errors import HTTPValidationError

def safe_chat_complete(client, model, messages, tools):
    """Mistral API call with error handling."""
    try:
        return client.chat.complete(
            model=model,
            messages=messages,
            tools=tools
        )
    except HTTPValidationError as e:
        print(f"Validation error: {e}")
        return None
    except Exception as e:
        print(f"API error: {e}")
        return None

Ara X’Qed Jiġri Verament

Sistema ta’ sejħa ta’ funzjonijiet hija diffiċli biex tiġi ddiġustjata wara l-fatt jekk ma tkunx taf liema funzjoni nsejħet, b’liema argumenti, u x’irritornat. Il-logging mhuwiex lussu; hija l-mod kif se tiskopri li deskrizzjoni ambigwa timbotta lill-mudell biex iħawwad bejn żewġ funzjonijiet, jew li wieħed minn kull ħames utenti sistematikament jikkawża transaction_not_found. Irreġistra s-sejħa qabel l-eżekuzzjoni, imbagħad il-verdett, u ddistingwi l-livell info mil-livell error sabiex l-allerti tiegħek ikunu jistgħu jiffiltraw b’mod effettiv.

import logging

logger = logging.getLogger("function_calling")

def execute_and_log(tool_call, available_functions):
    """Executes and logs the result."""
    function_name = tool_call.function.name
    function_params = json.loads(tool_call.function.arguments)

    logger.info(f"Call: {function_name}({function_params})")

    result = execute_tool_call(tool_call, available_functions)
    content = json.loads(result["content"])

    if "error" in content:
        logger.error(f"Failure {function_name}: {content['error']} - {content['message']}")
    else:
        logger.info(f"Success {function_name}: {content}")

    return result

Punti Ewlenin

  • Dejjem irritorna l-iżbalji lill-mudell fil-messaġġ tool—huwa jaf kif jinterpretahom
  • Uża kodiċijiet ta’ żball strutturati (transaction_not_found, invalid_arguments, eċċ.)
  • Implimenta tentattiv mill-ġdid b’backoff għal żbalji transitorji
  • Ipproċessa l-iżbalji fil-funzjonijiet tiegħek u l-iżbalji fl-API tal-Mistral separatament
  • Irreġistra kull sejħa u kull żball għall-monitoraġġ tal-produzzjoni