Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Veahandlus ja varuplaanid

Õppetund 4 / 20 Arendajatele
Sellel lehel
  1. Veahandlus ja varuplaanid
  2. Vigade tagastamine mudelile
  3. Kordamine eksponentsiaalse tagasipöördumisega
  4. Funktsioonipõhised ajalõpud
  5. Varuplaan funktsioonide vahel
  6. Vooluahela katkestaja (Circuit Breaker)
  7. Täielik robustne tsükkel
  8. Peamised punktid

Veahandlus ja varuplaanid

Funktsioonide kutsumine toob kaasa väljakutse, millega klassikaline kood ei tegele: kui sinu funktsioon nurjub, on veal kaks saajat. Sinu rakendus, nagu tavaliselt, ja mudel, mis ootab tulemust jätkamiseks. Selle unustamine tekitab tootmiskeskkonnas kõige segasema sümptomi: vestlus peatub järsult ilma selgituseta, sest erind neelati serveripoolselt ja mudel ootab endiselt.

Reegel, mis struktureerib kogu seda õppetundi, on järgmine: tagasta alati function_call_output, isegi tõrke korral. Mudel, kellele teatatakse, et API pole kättesaadav, saab pakkuda alternatiivi, küsida täpsustust või selgitada olukorda kasutajale. Mudel, kes ei saa midagi, ei saa midagi teha.

Vigade tagastamine mudelile

Vea vorming on sama oluline kui selle saatmine. Paljas „Viga“ ei õpeta mudelile midagi; JSON-objekt, mis eristab vea tüüpi, kas see on ajutine või püsiv, ja järgmised sammud, võimaldab mudelil otsustada. See on vastuoluline: kirjutad veateateid, mis on mõeldud põhjendava masina lugemiseks, mitte inimestele logimiseks.

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)
            })
        }

Kordamine eksponentsiaalse tagasipöördumisega

Kordamine on mõttekas ainult nende probleemide puhul, mis võivad teisel katsel laheneda: võrgukatkestused, olekukoodid 429 või ajutised tõrked. Kehtetu autentimise või valede parameetrite tõttu tagasi lükatud päringu kordamine ainult viivitab ebaõnnestumist ja korrutab kõnesid. Seetõttu filtreerib allolev kood vigu sõnaselgelt – filtreerimine teeb töö ära, samas kui tagasipöördumine on viisakus, mida võlad kaugteenusele.

import time
import random

def execute_with_retry(func, args, max_retries=3, base_delay=1.0):
    """Retry with exponential backoff and 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:
            # Data error: do not retry
            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
            })
        }

Funktsioonipõhised ajalõpud

Üks kõigile funktsioonidele mõeldud ajalõpp on alati valesti seadistatud: liiga lühike ja see tapab mahuka töötlemise; liiga pikk ja see paneb kasutaja ootama lihtsat vahemälupäringut. Põhinda iga väärtus tavatingimustes täheldatud kestustel, lisades varu – mitte halvimal ettekujutataval juhul, mis tähendaks sisuliselt ajalõpu puudumist.

import signal
from functools import wraps

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

def with_timeout(func, timeout_seconds):
    """Executes a function with a 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 by 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"
            })
        }

Varuplaan funktsioonide vahel

Varuplaan on kompromiss, mitte refleks: kuuetunnise vanusega vahemälus olevate andmete pakkumine on armatuurlaua jaoks parem kui mitte midagi, kuid pangakonto saldo jaoks palju halvem. Kui kvaliteeti langetad, ütle seda – mudelile tagastatavas tulemuses, et see saaks kasutajat hoiatada, selle asemel et esitada aegunud andmeid värsketena.

async def search_product(term: str) -> dict:
    """Search with fallback: primary API -> cache -> local database."""
    # Attempt 1: Catalog API
    try:
        return await api_catalog.search(term)
    except Exception:
        pass

    # Attempt 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

    # Attempt 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"
    }

Vooluahela katkestaja (Circuit Breaker)

Vooluahela katkestaja lahendab seda, mida kordamine ei suuda: teenus, mis on pikaks ajaks maas. Pärast N ebaõnnestumist lülitub see välja ja tagastab vea kohe, isegi proovimata, ning lubab seejärel aeg-ajalt läbi testpäringu, et kontrollida taastumist. Kasu on kahekordne – sinu kasutajad ei oota iga päringu puhul ajalõppu ja hädas olevat teenust ei hoia sinu kordamised maas.

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"

# One circuit breaker per external service
breakers = {
    "weather_api": CircuitBreaker(failure_threshold=3, open_duration=30),
    "catalog_api": CircuitBreaker(failure_threshold=5, open_duration=60),
}

Täielik robustne tsükkel

Täielik muster ühendab ülaltoodud viis mehhanismi. Üks ettevaatusabinõu teeb selle tõeliselt ohutuks ja seda on lihtne mööda vaadata: piira iteratsioonide arvu. Mudel, mis kutsub korduvalt funktsiooni, mille tulemusega ta rahul ei ole, on haruldane, kuid ilma ülempiirita kulutab see sinu eelarve lõpuni – ja sellise intsidenti avastad alles arvelt.

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"

Peamised punktid

  • Tagasta alati function_call_output, isegi vea korral
  • Struktureeri vead JSON-ina, et mudel saaks neid kasutada
  • Korda ainult ajutisi vigu eksponentsiaalse tagasipöördumisega
  • Rakenda varuplaane andmeallikate vahel
  • Kasuta vooluahela katkestajat ebaõnnestuvate teenuste kaitsmiseks