API anti-minták
Ezen az oldalon
Hibák, amelyek pénzbe kerülnek éles környezetben
Miután átvettük a bevált gyakorlatokat, ideje a másik oldalra nézni. Az alábbi anti-minták a Chat Completions API használata során előforduló leggyakoribb csapdák, és van egy közös, kellemetlen tulajdonságuk: fejlesztés közben nem bukkannak fel. Tíz tesztelési kérésből minden tökéletesen működik. Éles környezetben azonban robbannak be, váratlan költségeket, összefüggéstelen válaszokat, nagy késleltetést, vagy ami még rosszabb – érzékeny adatok szivárgását okozva.
Csonka válasz teljesként kezelése
A leggyakoribb hiba a finish_reason figyelmen kívül hagyása. Kérsz egy szerződést, kapsz vissza némi szöveget, elmented az adatbázisba: kivéve, ha a max_tokens=100 félbevágta a generálást egy bekezdés közepén, és senki nem veszi észre, amíg az ügyfél alá nem írja. A javítás három sor kódot igényel, és reflexszé kell válnia.
# ROSSZ — nincs ellenőrzés
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Draft a complete contract."}],
max_tokens=100 # Túl rövid egy szerződéshez!
)
contract = response.choices[0].message.content # Potenciálisan csonka!
# JÓ — szisztematikus ellenőrzés
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Draft a complete contract."}],
max_tokens=4000
)
if response.choices[0].finish_reason == "length":
print("FIGYELMEZTETÉS: A válasz csonka, növeld a max_tokens értékét")
else:
contract = response.choices[0].message.content
A beszélgetési előzmények korlátlan növekedése
A második csapda lassan indul be. Egy olyan chat-ciklus, amely minden lépésben elküldi a teljes beszélgetési előzményt, az első tíz váltásnál még tökéletesen működik, a huszadiknál már kétszer annyiba kerül, a századiknál pedig túllépi a kontextusablakot – a számla ugyanígy ível felfelé. A megoldás: tartsd meg a rendszer-üzenetet (ez nem tárgyalható), és csak az utolsó N üzenetet őrizd meg.
# ROSSZ — az előzmények végtelenül nőnek
conversation = []
while True:
user_input = input("Te: ")
conversation.append({"role": "user", "content": user_input})
response = client.chat.complete(
model="mistral-large-latest",
messages=conversation # 100 váltás = több ezer token!
)
reply = response.choices[0].message.content
conversation.append({"role": "assistant", "content": reply})
# JÓ — csúszó ablak trimminggel
MAX_MESSAGES = 20
def trim_conversation(messages: list, max_messages: int = MAX_MESSAGES) -> list:
"""Megőrzi a rendszer-üzenetet és az utolsó N üzenetet."""
system = [m for m in messages if m["role"] == "system"]
history = [m for m in messages if m["role"] != "system"]
if len(history) > max_messages:
history = history[-max_messages:]
return system + history
A hálózat mindig válaszol feltételezése
Egy puszta API-hívás azt feltételezi, hogy semmi sem romlik el: nincs időtúllépés, nincs 429-es hiba, nincs 500-as hiba. Éles környezetben mindhárom előfordul, és a harmadik a legrosszabb pillanatban történik. Figyeld a különbséget a kódban: a 429-es hiba exponenciális visszalépést indokol, egy szerverhiba egy másodperc türelmet érdemel, de egy klienshiba, mint a 400 vagy 401, soha nem próbálható újra – a kulcsod nem lesz érvényes a harmadik próbálkozásra; csak elhalasztod a hibakeresést.
# ROSSZ — nincs hibakezelés
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Hello"}]
)
# Összeomlik időtúllépés, 429, 500 esetén...
# JÓ — újrapróbálkozás exponenciális visszalépéssel
from mistralai.client.errors import SDKError
import time
def safe_complete(client, messages, max_retries=3, **kwargs):
"""API-hívás újrapróbálkozással és exponenciális visszalépéssel."""
for attempt in range(max_retries):
try:
return client.chat.complete(messages=messages, **kwargs)
except SDKError as e:
if e.status_code == 429:
wait = 2 ** attempt
print(f"Szabályozási limit elérve, várakozás {wait}s...")
time.sleep(wait)
elif e.status_code >= 500:
time.sleep(1)
else:
raise # Klienshiba (400, 401) — ne próbáld újra
raise Exception("Sikertelen 3 próbálkozás után")
Olyan feladat kérése, amit a modell nem tud elvégezni
Három anti-minta fut itt össze. Az első a szubjektív nyelvhasználat: a „rövid“, „sok“, „érdekes“ kifejezések semmi ellenőrizhetőre nem utalnak, és a modell hívásról hívásra másképp dönt. Minden melléknevet cserélj le számra vagy megfigyelhető kritériumra.
# ROSSZ — szubjektív, nem mérhető
"Írj egy rövid összefoglalót." # Rövid = 1 mondat? 1 bekezdés?
"Adj sok példát." # Sok = 3? 10? 50?
"Válaszolj érdekes módon." # Milyen kritérium alapján érdekes?
# JÓ — objektív kritériumok
"Írj egy 50 és 80 szó közötti összefoglalót."
"Adj pontosan 5 példát, soronként egyet."
"Minden választ kezdj egy releváns statisztikával."
A második hiba, ha a modellel számoltatsz. Az LLM-ek notoriously rosszak szavak, karakterek és elemek számolásában: ha „pontosan 280 karaktert“ kérsz, 240 vagy 310 karakteres szöveget fogsz kapni. A számolás a te alkalmazásod feladata, nem a modellé.
# ROSSZ — a modell nem tud pontosan számolni
"Írj pontosan 280 karaktert egy tweethez."
# JÓ — számolás az alkalmazás oldalán
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Write a tweet about AI in France."}],
max_tokens=100
)
tweet = response.choices[0].message.content
if len(tweet) > 280:
tweet = tweet[:277] + "..."
print(f"Tweet ({len(tweet)} karakter): {tweet}")
A harmadik hiba ugyanebbe a családba tartozik: numerikus skálák. Az „Értékeld 1 és 5 között“ feltételezés arra épül, hogy a modellnek stabil reprezentációja van a 3 és 4 közötti távolságról, pedig nincs. Egy verbális skála, ahol minden lépést egy kritérium definiál, sokkal reprodukálhatóbb értékelést eredményez.
# ROSSZ — a modellek rosszul értelmezik a numerikus skálákat
"Értékeld ennek a szövegnek a minőségét 1 és 5 között."
# JÓ — verbális skála definíciókkal
"""Értékeld ennek a szövegnek a minőségét az alábbi skála alapján:
- KIVÁLÓ: Világos, jól strukturált, hibátlan
- JÓ: Általában helyes, kisebb javítások lehetségesek
- ÁTLAGOS: Érthető, de hiányzik a struktúra vagy tartalmaz hibákat
- GYENGE: Nehezen érthető, jelentős hibák
- NAGYON GYENGE: Érthetetlen vagy témán kívüli
Csak a címkével válaszolj nagybetűvel."""
Nyom nélkül történő telepítés
Az utolsó anti-minta a legdiszkrétebb: API-hívás, tartalom visszaadása, és semmi megőrzése. Amikor egy felhasználó rendellenes válaszról számol be, nincs meg a kérés azonosítója, nincs meg a ténylegesen kiszolgált modell, és nincs meg a tokenfogyasztás sem. A hívásonkénti strukturált naplózás néhány milliszekundumba kerül, és lehetővé teszi a kivizsgálást.
# ROSSZ — nincs nyom
response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
return response.choices[0].message.content
# JÓ — strukturált naplózás
import logging
import json
logger = logging.getLogger("mistral_api")
def logged_complete(client, messages, **kwargs):
"""API-hívás strukturált naplózással."""
response = client.chat.complete(messages=messages, **kwargs)
logger.info(json.dumps({
"request_id": response.id,
"model": response.model,
"prompt_tokens": response.usage.prompt_tokens,
"completion_tokens": response.usage.completion_tokens,
"finish_reason": response.choices[0].finish_reason
}))
return response
Hibakeresési rutin
Amikor egy válasz nem felel meg az elvárásaidnak, a kísértés nagy, hogy átírd a promptot. Ehelyett kezdj öt mechanikus ellenőrzéssel, sorrendben: Teljes a válasz? A megfelelő modell válaszolt? Hány tokent fogyasztott? Üres a válasz? Reális a kimenet/bemenet arány? Egy nagy prompt esetén az 1% alatti arány szinte mindig azt jelzi, hogy a modell megtagadta a kérés feldolgozását, nem pedig rosszul kezelte azt.
def debug_response(response):
"""Hibakeresési ellenőrzőlista váratlan válaszokhoz."""
choice = response.choices[0]
# 1. Teljes a válasz?
if choice.finish_reason == "length":
print("HIBA: A válasz csonka — növeld a max_tokens értékét")
# 2. A megfelelő modellt használtuk?
print(f"Modell: {response.model}")
# 3. Hány tokent fogyasztott?
print(f"Bemeneti tokenek: {response.usage.prompt_tokens}")
print(f"Kimeneti tokenek: {response.usage.completion_tokens}")
# 4. Üres a válasz?
if not choice.message.content or not choice.message.content.strip():
print("HIBA: Üres válasz")
# 5. Gyanús bemenet/kimenet arány?
ratio = response.usage.completion_tokens / max(response.usage.prompt_tokens, 1)
if ratio < 0.01:
print(f"FIGYELMEZTETÉS: Nagyon alacsony kimenet/bemenet arány ({ratio:.4f})")
Főbb megállapítások
- Mindig ellenőrizd a
finish_reasonértéket a csonkolás észleléséhez - Korlátozd a beszélgetési előzményeket csúszó ablakkal
- Implementálj újrapróbálkozást exponenciális visszalépéssel hálózati hibák esetén
- Használj objektív, mérhető kritériumokat a promptjaidban
- Soha ne bízd a számolást a modellre – validálj az alkalmazás oldalán
- Naplózz minden API-hívást éles környezetben a hibakeresés és a költségek nyomon követése érdekében