Anti-vzorci API-ja
Na tej strani
Napake, ki v proizvodnji stanejo denarja
Ko smo obravnavali najboljše prakse, je čas, da pogledamo drugo stran medalje. Spodnji anti-vzorci so najpogostejše pasti pri uporabi API-ja Chat Completions in imajo eno neprijetno lastnost: med razvojem se ne pokažejo. Od desetih testnih zahtev vse deluje brezhibno. Šele v proizvodnji eksplodirajo in povzročijo nepričakovane stroške, nesmiselne odgovore, visoko zakasnitev ali, kar je še huje, uhajanje občutljivih podatkov.
Obravnava okrnjenega odgovora kot popolnega
Najpogostejša napaka je ignoriranje finish_reason. Zahtevaš pogodbo, dobiš nekaj besedila, ga shraniš v bazo podatkov: razen če max_tokens=100 ni prekinilo generiranja sredi določila in tega nihče ne opazi, dokler stranka ne podpiše. Popravek zahteva tri vrstice kode in mora postati refleks.
# SLABO — brez preverjanja
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Draft a complete contract."}],
max_tokens=100 # Premalo za pogodbo!
)
contract = response.choices[0].message.content # Potencialno okrnjeno!
# DOBRO — sistematično preverjanje
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("OPOZORILO: Odgovor je okrnjen, povečajte max_tokens")
else:
contract = response.choices[0].message.content
Puščanje zgodovine pogovora, da raste brez omejitev
Druga past se sproži počasi. Zanka za klepet, ki pri vsakem koraku pošlje celotno zgodovino pogovora, popolnoma deluje prvih deset izmenjav, do dvajsete stane dvakrat toliko, do stote pa preseže okno konteksta – račun sledi isti krivulji. Rešitev je ohraniti sistemski poziv (nepogrešljiv) in obdržati le zadnjih N sporočil.
# SLABO — zgodovina raste v nedogled
conversation = []
while True:
user_input = input("Ti: ")
conversation.append({"role": "user", "content": user_input})
response = client.chat.complete(
model="mistral-large-latest",
messages=conversation # 100 krogov = tisoči žetonov!
)
reply = response.choices[0].message.content
conversation.append({"role": "assistant", "content": reply})
# DOBRO – drseče okno z obrezovanjem
MAX_MESSAGES = 20
def trim_conversation(messages: list, max_messages: int = MAX_MESSAGES) -> list:
"""Ohrani sistemski poziv in zadnjih N sporočil."""
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
Predpostavka, da omrežje vedno odgovori
Gol klic API-ja predpostavlja, da se ne bo zgodilo nič narobe: brez časovnih omejitev, brez napak 429, brez napak 500. V proizvodnji se zgodijo vse tri, tretja pa ravno ob najslabšem možnem trenutku. Upoštevaj razliko v kodi: za 429 je upravičeno eksponentno odlašanje, napaka strežnika zahteva sekundo potrpežljivosti, napaka odjemalca, kot sta 400 ali 401, pa se nikoli ne sme ponoviti – tvoj ključ ne bo postal veljaven ob tretjem poskusu; le odložil boš diagnozo.
# SLABO — brez obravnave napak
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Hello"}]
)
# Sesuje se ob časovni omejitvi, 429, 500...
# DOBRO — ponovni poskus z odlašanjem
from mistralai.client.errors import SDKError
import time
def safe_complete(client, messages, max_retries=3, **kwargs):
"""Klic API-ja s ponovnim poskusom in eksponentnim odlašanjem."""
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"Dosežena omejitev hitrosti, čakanje {wait}s...")
time.sleep(wait)
elif e.status_code >= 500:
time.sleep(1)
else:
raise # Napaka odjemalca (400, 401) — ne ponavljaj
raise Exception("Neuspešno po 3 poskusih")
Zahtevanje, naj model naredi tisto, česar ne zmore
Tu se združijo trije anti-vzorci. Prvi je subjektiven jezik: “kratek”, “mnogo”, “zanimiv” se ne nanašajo na nič preverljivega in model se bo odločil drugače od klica do klica. Vsak pridevnik zamenjaj s številko ali opazljivim merilom.
# SLABO — subjektivno, nemerljivo
"Napiši kratek povzetek." # Kratek = 1 stavek? 1 odstavek?
"Navedi mnogo primerov." # Mnogo = 3? 10? 50?
"Odgovori na zanimiv način." # Zanimiv po kakšnih merilih?
# DOBRO — objektivna merila
"Napiši povzetek v 50 do 80 besedah."
"Navedi točno 5 primerov, enega na vrstico."
"Vsak odgovor začni z ustrezno statistiko."
Drugi je prepuščanje štetja modelu. LLM so znano slabi pri štetju besed, znakov in elementov: zahteva po “točno 280 znakih” bo proizvedla besedilo z 240 ali 310 znaki. Štetje spada v tvojo aplikacijo, ne v model.
# SLABO — model ne more natančno šteti
"Napiši točno 280 znakov za tvit."
# DOBRO — štej na strani aplikacije
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"Tvit ({len(tweet)} znakov): {tweet}")
Tretji spada v isto družino: numerične lestvice. “Oceni od 1 do 5” predpostavlja, da ima model stabilno predstavitev razlike med 3 in 4, česar nima. Besedna lestvica, kjer je vsak korak opredeljen z merilom, daje veliko bolj ponovljive ocene.
# SLABO — modeli slabo interpretirajo numerične lestvice
"Oceni kakovost tega besedila od 1 do 5."
# DOBRO — besedna lestvica z definicijami
"""Oceni kakovost tega besedila glede na naslednjo lestvico:
- ODLIČNO: Jasno, dobro strukturirano, brez napak
- DOBRO: Na splošno pravilno, možne manjše izboljšave
- POVPREČNO: Razumljivo, a manjka struktura ali vsebuje napake
- SLABO: Težko razumljivo, velike napake
- ZELO SLABO: Nerazumljivo ali izven teme
Odgovori samo z oznako v velikih tiskanih črkah."""
Namestitev brez sledi
Zadnji anti-vzorec je najbolj diskreten: klic API-ja, vrnitev vsebine in nehranjenje ničesar. Ko uporabnik poroča o nenormalnem odgovoru, nimaš niti ID-ja zahteve, niti dejanskega uporabljenega modela, niti porabe žetonov. Strukturirano beleženje na klic stane nekaj milisekund in omogoči preiskavo.
# SLABO — brez sledi
response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
return response.choices[0].message.content
# DOBRO — strukturirano beleženje
import logging
import json
logger = logging.getLogger("mistral_api")
def logged_complete(client, messages, **kwargs):
"""Klic API-ja s strukturiranim beleženjem."""
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
Postopek odpravljanja napak
Ko odgovor ne izpolni tvojih pričakovanj, je skušnava, da bi prepisal poziv. Namesto tega začni s petimi mehanskimi preverjanji, po vrsti: Ali je odgovor popoln? Je odgovoril pravi model? Koliko žetonov je bilo porabljenih? Ali je odgovor prazen? Ali je razmerje med izhodom in vhodom verjetno? Razmerje pod 1 % pri velikem pozivu skoraj vedno signalizira, da je model zavrnil obdelavo zahteve, namesto da bi jo napačno obdelal.
def debug_response(response):
"""Kontrolni seznam za odpravljanje napak pri nepričakovanih odgovorih."""
choice = response.choices[0]
# 1. Ali je odgovor popoln?
if choice.finish_reason == "length":
print("TEŽAVA: Odgovor je okrnjen — povečajte max_tokens")
# 2. Ali je bil uporabljen pravi model?
print(f"Model: {response.model}")
# 3. Koliko žetonov je bilo porabljenih?
print(f"Vhodni žetoni: {response.usage.prompt_tokens}")
print(f"Izhodni žetoni: {response.usage.completion_tokens}")
# 4. Ali je odgovor prazen?
if not choice.message.content or not choice.message.content.strip():
print("TEŽAVA: Prazen odgovor")
# 5. Sumljivo razmerje vhod/izhod?
ratio = response.usage.completion_tokens / max(response.usage.prompt_tokens, 1)
if ratio < 0.01:
print(f"OPOZORILO: Zelo nizko razmerje izhod/vhod ({ratio:.4f})")
Ključne ugotovitve
- Vedno preveri
finish_reason, da zaznaš okrnitev - Omeji zgodovino pogovora z drsečim oknom
- Implementiraj ponovne poskuse z eksponentnim odlašanjem za omrežne napake
- V svojih pozivih uporabi objektivna, merljiva merila
- Nikoli ne puščaj štetja modelu – validiraj na strani aplikacije
- V proizvodnji beleži vsak klic API-ja zaradi odpravljanja napak in sledenja stroškov