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

Immaniġġjar tal-iżbalji u fallbacks

Lezzjoni 4 / 20 Zviluppatur
F'din il-paġna
  1. Immaniġġjar tal-iżbalji u fallbacks
  2. Ir-ritorn tal-iżbalji lill-mudell
  3. Erġa’ pprova b’backoff esponenzjali
  4. Timeouts għal kull funzjoni
  5. Fallback bejn il-funzjonijiet
  6. Circuit breaker
  7. Ċiklu robust sħiħ
  8. Punti Ewlenin

Immaniġġjar tal-iżbalji u fallbacks

Is-sejħa tal-funzjonijiet tintroduċi sfida li l-kodiċi klassiku ma jiffaċċjax: meta l-funzjoni tiegħek tonqos, hemm żewġ riċevituri għal dak l-iżball. L-applikazzjoni tiegħek, bħas-soltu—u l-mudell, li qed jistenna riżultat biex ikompli. Li tinse dan joħloq l-aktar sintomu konfuż fil-produzzjoni: konversazzjoni li tieqaf għal kollox mingħajr spjegazzjoni, għax eċċezzjoni ntilgħet fuq in-naħa tas-server u l-mudell għadu qed jistenna.

Ir-regola li ssegwi tistruttura din il-lezzjoni kollha: irritorna dejjem function_call_output, anke meta jkun hemm falliment. Mudell infurmat li API mhix disponibbli jista’ jipproponi alternattiva, jitlob kjarifika, jew jispjega s-sitwazzjoni lill-utent. Mudell li ma jirċievi xejn ma jista’ jagħmel xejn.

Ir-ritorn tal-iżbalji lill-mudell

Il-format tal-iżball huwa importanti daqs kemm tibgħatu. “Error” sempliċi ma jgħallem xejn lill-mudell; oġġett JSON li jiddistingwi t-tip ta’ żball, jekk huwiex transitorju jew permanenti, u l-passi li jmiss, jippermetti lill-mudell jiddeċiedi. Dan huwa kontra l-intuwizzjoni: qed tikteb messaġġi ta’ żball maħsuba biex jiġu moqrija minn magna tar-raġunament, mhux irreġistrati għall-bnedmin.

import json
from openai import OpenAI

client = OpenAI()

def execute_function(name: str, arguments: str, call_id: str) -> dict:
    try:
        args = json.loads(arguments)
        result = dispatcher[name](**args)
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps(result)
        }
    except KeyError:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": "unknown_function",
                "message": f"The function '{name}' does not exist"
            })
        }
    except json.JSONDecodeError:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": "invalid_arguments",
                "message": "The JSON arguments are malformed"
            })
        }
    except Exception as e:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": "internal_error",
                "message": str(e)
            })
        }

Erġa’ pprova b’backoff esponenzjali

Li terġa’ tipprova jagħmel sens biss għal kwistjonijiet li jistgħu jsolvu fit-tieni tentattiv: qtugħ fin-network, kodiċijiet ta’ status 429, jew interruzzjonijiet temporanji. Li terġa’ tipprova talba miċħuda minħabba awtentikazzjoni invalida jew parametri żbaljati biss iddewwem il-falliment waqt li timmultiplika s-sejħat. Għalhekk il-kodiċi hawn taħt jiffiltra b’mod espliċitu l-iżbalji—il-filtrar jagħmel ix-xogħol, filwaqt li l-backoff huwa biss il-korteżija li għandek lejn is-servizz remot.

import time
import random

def execute_with_retry(func, args, max_retries=3, base_delay=1.0):
    """Erġa' pprova b'backoff esponenzjali u jitter."""
    for attempt in range(max_retries + 1):
        try:
            return func(**args)
        except (ConnectionError, TimeoutError) as e:
            if attempt == max_retries:
                raise
            delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
            time.sleep(delay)
        except ValueError:
            # Żball fid-data: terġax tipprova
            raise

def execute_function_robust(name, arguments, call_id):
    args = json.loads(arguments)
    try:
        result = execute_with_retry(dispatcher[name], args)
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps(result)
        }
    except Exception as e:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": type(e).__name__,
                "message": str(e),
                "retries_performed": 3
            })
        }

Timeouts għal kull funzjoni

Timeout wieħed għall-funzjonijiet kollha huwa dejjem ikkonfigurat ħażin: qasir wisq, u joqtol l-ipproċessar tqil; twil wisq, u jġiegħel lill-utent jistenna fuq tfittxija sempliċi fil-cache. Ibbaża kull valur fuq id-durati osservati f’kundizzjonijiet normali, b’marġni—mhux fuq l-agħar każ immaġinabbli, li effettivament ikun ifisser li m’għandek l-ebda timeout.

import signal
from functools import wraps

TIMEOUTS = {
    "search_client": 5,
    "generate_report": 30,
    "send_email": 10,
}

def with_timeout(func, timeout_seconds):
    """Jesegwixxi funzjoni b'timeout."""
    import concurrent.futures
    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
        future = executor.submit(func)
        try:
            return future.result(timeout=timeout_seconds)
        except concurrent.futures.TimeoutError:
            raise TimeoutError(
                f"Function interrupted after {timeout_seconds}s"
            )

def execute_with_timeout(name, arguments, call_id):
    args = json.loads(arguments)
    timeout = TIMEOUTS.get(name, 10)  # 10s b'mod default

    try:
        result = with_timeout(
            lambda: dispatcher[name](**args),
            timeout
        )
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps(result)
        }
    except TimeoutError as e:
        return {
            "type": "function_call_output",
            "call_id": call_id,
            "output": json.dumps({
                "error": "timeout",
                "message": str(e),
                "suggestion": "Retry with more specific criteria"
            })
        }

Fallback bejn il-funzjonijiet

Il-fallback huwa kompromess, mhux rifless: li sservi data cached ta’ sitt sigħat ilu huwa aħjar minn xejn għal dashboard, u ferm agħar minn xejn għal bilanċ bankarju. Meta tnaqqas il-kwalità, għid hekk—fir-riżultat ritornat lill-mudell, sabiex ikun jista’ jwissija lill-utent minflok ma jippreżenta data antika bħala ġdida.

async def search_product(term: str) -> dict:
    """Fittex b'fallback: API primarja -> cache -> database lokali."""
    # Tentattiv 1: Catalog API
    try:
        return await api_catalog.search(term)
    except Exception:
        pass

    # Tentattiv 2: Redis cache
    try:
        cached = await redis_client.get(f"product:{term}")
        if cached:
            result = json.loads(cached)
            result["_source"] = "cache"
            result["_warning"] = "Data may be outdated"
            return result
    except Exception:
        pass

    # Tentattiv 3: Local SQLite database
    try:
        row = db.execute(
            "SELECT * FROM products WHERE name LIKE ?",
            (f"%{term}%",)
        ).fetchone()
        if row:
            return {
                "name": row["name"],
                "price": row["price"],
                "_source": "local_db",
                "_warning": "Data from last synchronization"
            }
    except Exception:
        pass

    return {
        "error": "unavailable",
        "message": "No data source accessible for this search"
    }

Circuit breaker

Iċ-circuit breaker jimmaniġġja dak li r-ritentattiv ma jistax: servizz li huwa ‘l isfel għal żmien twil. Wara N fallimenti, dan jitfi u jirritorna żball immedjatament, mingħajr anke ma jipprova, imbagħad okkażjonalment jippermetti talba ta’ test tgħaddi biex jiċċekkja għall-irkupru. Il-gwadann huwa doppju—l-utenti tiegħek jieqfu jistennew għal timeout fuq kull talba, u s-servizz li qed jissielet ma jinżammx ‘l isfel mir-ritentattivi tiegħek.

from datetime import datetime, timedelta

class CircuitBreaker:
    def __init__(self, failure_threshold=5, open_duration=60):
        self.threshold = failure_threshold
        self.duration = open_duration
        self.failures = 0
        self.last_failure = None
        self.state = "closed"  # closed, open, half-open

    def can_execute(self) -> bool:
        if self.state == "closed":
            return True
        if self.state == "open":
            if datetime.now() - self.last_failure > timedelta(seconds=self.duration):
                self.state = "half-open"
                return True
            return False
        return True  # half-open: allow one test attempt

    def record_success(self):
        self.failures = 0
        self.state = "closed"

    def record_failure(self):
        self.failures += 1
        self.last_failure = datetime.now()
        if self.failures >= self.threshold:
            self.state = "open"

# Circuit breaker wieħed għal kull servizz estern
breakers = {
    "weather_api": CircuitBreaker(failure_threshold=3, open_duration=30),
    "catalog_api": CircuitBreaker(failure_threshold=5, open_duration=60),
}

Ċiklu robust sħiħ

Il-mudell sħiħ jiġbor flimkien il-ħames mekkaniżmi ta’ hawn fuq. Prekawzjoni waħda tagħmlu verament sikur, u hija faċli li titlef: illimita n-numru ta’ iterazzjonijiet. Mudell li jagħmel ċiklu jsejjaħ funzjoni li r-riżultat tagħha ma jħobbx huwa rari, iżda mingħajr limitu massimu se jaħraq il-baġit tiegħek sakemm jintemm—u dan huwa t-tip ta’ inċident li tiskopri fuq il-kont.

def robust_loop(prompt, tools, max_turns=10):
    messages = prompt
    for turn in range(max_turns):
        response = client.responses.create(
            model="gpt-5.6-terra",
            input=messages,
            tools=tools
        )

        calls = [i for i in response.output if i.type == "function_call"]
        if not calls:
            return response.output_text

        results = []
        for call in calls:
            result = execute_function_robust(
                call.name, call.arguments, call.call_id
            )
            results.append(result)

        messages = response.output + results

    return "Workflow interrupted: turn limit reached"

Punti Ewlenin

  • Irritorna dejjem function_call_output, anke fuq żball
  • Istruttura l-iżbalji bħala JSON sabiex il-mudell ikun jista’ jużahom
  • Erġa’ pprova biss żbalji transitorji b’backoff esponenzjali
  • Implimenta fallbacks bejn sorsi tad-data
  • Uża circuit breaker biex tipproteġi servizzi li qed ifallu