Virheenkäsittely ja varasuunnitelmat
Tällä sivulla
Virheenkäsittely ja varasuunnitelmat
Funktion kutsuminen tuo mukanaan haasteen, jota perinteinen koodi ei kohtaa: kun funktiosi epäonnistuu, virheellä on kaksi vastaanottajaa. Sovelluksesi, kuten tavallista, ja malli, joka odottaa tulosta jatkaakseen. Tämän unohtaminen aiheuttaa tuotannossa hämmentävimmän oireen: keskustelu pysähtyy tyysti ilman selitystä, koska poikkeus nieltiin palvelinpuolella ja malli odottaa edelleen vastausta.
Seuraava sääntö rakentaa koko tämän oppitunnin: palauta aina function_call_output, myös epäonnistumisen sattuessa. Malli, joka saa tiedon API:n olevan tavoittamattomissa, voi ehdottaa vaihtoehtoa, pyytää tarkennusta tai selittää tilanteen käyttäjälle. Malli, joka ei saa mitään, ei voi tehdä mitään.
Virheiden palauttaminen mallille
Virheen muodolla on yhtä suuri merkitys kuin sen lähettämisellä. Pelkkä “Error” ei opeta mallille mitään; JSON-objekti, joka erottaa virhetyypin, kertoo onko se ohimenevä vai pysyvä, ja ehdottaa seuraavia askelia, antaa mallille mahdollisuuden päättää jatkotoimista. Tämä on vastoin intuitiota: kirjoitat virheviestejä, jotka on tarkoitettu päättelykoneen luettavaksi, ei ihmisten lokitiedostoja varten.
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)
})
}
Yritykset eksponentiaalisella viiveellä (Exponential Backoff)
Uudelleenyritys on järkevää vain ongelmille, jotka voivat ratketa toisella yrityksellä: verkkokatkot, 429-statuskoodit tai tilapäiset katkokset. Pyynnön uudelleenyritys, joka hylättiin virheellisen todennuksen tai väärien parametrien vuoksi, vain viivästyttää epäonnistumista ja kasvattaa kutsujen määrää. Siksi alla oleva koodi suodattaa virheet eksplisiittisesti – suodatus tekee varsinaisen työn, kun taas viive on kohteliaisuus, jonka olet velkaa etäpalvelulle.
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
})
}
Funktiokohtaiset aikakatkokset
Yksi yhteinen aikakatkaisu kaikille funktioille on aina väärin säädetty: liian lyhyt, ja se tappaa raskaan käsittelyn; liian pitkä, ja se pakottaa käyttäjän odottamaan yksinkertaista välimuistihakua. Perusta jokainen arvo havaittuihin kestoihin normaaleissa olosuhteissa lisäten marginaali – älä pahimpaan mahdolliseen tapaukseen, mikä käytännössä tarkoittaisi aikakatkon puuttumista.
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"
})
}
Varasuunnitelmat funktioiden välillä
Varasuunnitelma on kompromissi, ei refleksi: kuusi tuntia vanhan välimuistidatan tarjoaminen on parempi kuin ei mitään kojetaululle, mutta paljon huonompi kuin ei mitään pankkitilille. Kun heikennät laatua, kerro se – mallille palautetussa tuloksessa, jotta se voi varoittaa käyttäjää sen sijaan, että esittäisi vanhentuneen datan tuoreena.
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"
}
Piirikatkaisija (Circuit Breaker)
Piirikatkaisija hoitaa sen, mitä uudelleenyritys ei pysty: palvelun, joka on alhaalla pitkäksi aikaa. N epäonnistumisen jälkeen se laukeaa ja palauttaa virheen välittömästi edes yrittämättä, ja päästää sitten satunnaisesti testipyynnön läpi tarkistaakseen palautumista. Hyöty on kaksinkertainen – käyttäjäsi eivät enää odota aikakatkoa jokaisessa pyynnössä, ja kamppaileva palvelu ei pysy alhaalla uudelleenyritystesi vuoksi.
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äydellinen robusti silmukka
Koko malli yhdistää viisi edellä mainittua mekanismia. Yksi varotoimi tekee siitä todella turvallisen, ja se on helppo unohtaa: rajoita iteraatioiden määrä. Malli, joka jää silmukkaan kutsumaan funktiota, jonka tuloksesta se ei pidä, on harvinainen tapaus, mutta ilman kattoa se polttaa budjettisi loppuun – ja tällaisen tapauksen huomaat vasta laskusta.
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"
Keskeiset asiat
- Palauta aina
function_call_output, myös virhetilanteessa - Jäsennä virheet JSON-muotoon, jotta malli voi hyödyntää niitä
- Yritä uudelleen vain ohimeneviä virheitä käyttäen eksponentiaalista viivettä
- Toteuta varasuunnitelmat tietolähteiden välillä
- Käytä piirikatkaisijaa suojaamaan vikaantuvia palveluita