Anti-tipare API
Pe această pagină
Greșeli care costă bani în producție
După ce am acoperit bunele practici, este momentul să analizăm și reversul medaliei. Anti-tiparele de mai jos reprezintă cele mai frecvente capcane atunci când utilizați API-ul Chat Completions, iar toate au o trăsătură neplăcută comună: nu apar în timpul dezvoltării. Din zece cereri de test, totul funcționează perfect. În producție însă, acestea explodează, provocând costuri neașteptate, răspunsuri incoerente, latență mare sau, mai rău, scurgeri de date sensibile.
Tratarea unui răspuns trunchiat ca fiind complet
Cea mai frecventă greșeală este ignorarea câmpului finish_reason. Solicitați un contract, primiți un text, îl salvați în baza de date: doar că max_tokens=100 a întrerupt generarea la mijlocul unei clauze, iar nimeni nu observă până când clientul semnează. Remedierea necesită trei linii de cod și ar trebui să devină un reflex.
# RĂU — fără verificare
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Redactează un contract complet."}],
max_tokens=100 # Prea scurt pentru un contract!
)
contract = response.choices[0].message.content # Potențial trunchiat!
# BINE — verificare sistematică
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Redactează un contract complet."}],
max_tokens=4000
)
if response.choices[0].finish_reason == "length":
print("ATENȚIE: Răspuns trunchiat, măriți max_tokens")
else:
contract = response.choices[0].message.content
Lăsarea istoricului conversației să crească fără limite
A doua capcană se declanșează lent. O buclă de chat care trimite întregul istoric al conversației la fiecare tur funcționează perfect pentru primele zece schimburi, costă dublu la al douăzecilea și, în final, depășește fereastra de context la al o sutlea – factura urmând aceeași curbă. Soluția este să păstrați promptul de sistem (non-negociabil) și să rețineți doar ultimele N mesaje.
# RĂU — istoricul crește la infinit
conversation = []
while True:
user_input = input("Dumneavoastră: ")
conversation.append({"role": "user", "content": user_input})
response = client.chat.complete(
model="mistral-large-latest",
messages=conversation # 100 de tururi = mii de tokeni!
)
reply = response.choices[0].message.content
conversation.append({"role": "assistant", "content": reply})
# BINE — fereastră glisantă cu decupare
MAX_MESSAGES = 20
def trim_conversation(messages: list, max_messages: int = MAX_MESSAGES) -> list:
"""Păstrează promptul de sistem + ultimele N mesaje."""
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
Presupunerea că rețeaua răspunde întotdeauna
O apelare API brută presupune că nimic nu va merge prost: fără timeout-uri, fără erori 429, fără erori 500. În producție, toate trei se întâmplă, iar a treia apare în cel mai nepotrivit moment. Rețineți distincția din cod: o eroare 429 justifică o reîncercare cu backoff exponențial, o eroare de server warrantă o secundă de răbdare, dar o eroare de client, cum ar fi 400 sau 401, nu trebuie niciodată reîncercată – cheia dumneavoastră nu va deveni validă la a treia încercare; veți doar întârzia diagnosticarea.
# RĂU — fără gestionarea erorilor
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Salut"}]
)
# Se blochează la timeout, 429, 500...
# BINE — reîncercare cu backoff
from mistralai.client.errors import SDKError
import time
def safe_complete(client, messages, max_retries=3, **kwargs):
"""Apel API cu reîncercare și backoff exponențial."""
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"Limită de rată atinsă, aștept {wait}s...")
time.sleep(wait)
elif e.status_code >= 500:
time.sleep(1)
else:
raise # Eroare de client (400, 401) — nu reîncercați
raise Exception("Eșec după 3 încercări")
Solicitarea modelului să facă ceea ce nu poate
Trei anti-tipare converg aici. Primul este limbajul subiectiv: „scurt“, „multe“, „interesant“ nu se referă la nimic verificabil, iar modelul va decide diferit de la o apelare la alta. Înlocuiți fiecare adjectiv cu un număr sau un criteriu observabil.
# RĂU — subiectiv, nemăsurabil
"Scrie un rezumat scurt." # Scurt = 1 propoziție? 1 paragraf?
"Dă multe exemple." # Multe = 3? 10? 50?
"Răspunde într-un mod interesant." # Interesant după ce criterii?
# BINE — criterii obiective
"Scrie un rezumat de 50 până la 80 de cuvinte."
"Dă exact 5 exemple, câte unul pe linie."
"Începe fiecare răspuns cu o statistică relevantă."
Al doilea este lăsarea modelului să numere. LLM-urile sunt notoriu de slabe la numărat cuvinte, caractere și elemente: solicitarea a „exact 280 de caractere“ va produce un text de 240 sau 310. Numărătoarea aparține aplicației dumneavoastră, nu modelului.
# RĂU — modelul nu poate număra precis
"Scrie exact 280 de caractere pentru un tweet."
# BINE – numărați în aplicație
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Scrie un tweet despre IA în Franța."}],
max_tokens=100
)
tweet = response.choices[0].message.content
if len(tweet) > 280:
tweet = tweet[:277] + "..."
print(f"Tweet ({len(tweet)} caractere): {tweet}")
Al treilea intră în aceeași familie: scalele numerice. „Notează de la 1 la 5“ presupune că modelul are o reprezentare stabilă a diferenței dintre 3 și 4, ceea ce nu este cazul. O scală verbală, în care fiecare pas este definit printr-un criteriu, oferă evaluări mult mai reproductibile.
# RĂU — modelele interpretează prost scalele numerice
"Notează calitatea acestui text de la 1 la 5."
# BINE — scală verbală cu definiții
"""Notează calitatea acestui text conform scalei următoare:
- EXCELENT: Clar, bine structurat, fără erori
- BUN: În general corect, sunt posibile îmbunătățiri minore
- MEDIU: De înțeles, dar lipsește structura sau conține erori
- SLAB: Dificil de înțeles, erori semnificative
- FOARTE SLAB: Incomprehensibil sau în afara subiectului
Răspunde doar cu eticheta cu majuscule."""
Implementarea fără a lăsa urme
Ultimul anti-tipar este cel mai discret: apelarea API-ului, returnarea conținutului și nepăstrarea a nimic. În ziua în care un utilizator semnalează un răspuns aberant, nu aveți nici ID-ul cererii, nici modelul efectiv servit, nici consumul de tokeni. Jurnalizarea structurată per apel costă câțiva milisecunde și face posibilă investigarea.
# RĂU — fără urme
response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
return response.choices[0].message.content
# BINE — jurnalizare structurată
import logging
import json
logger = logging.getLogger("mistral_api")
def logged_complete(client, messages, **kwargs):
"""Apel API cu jurnalizare structurată."""
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
O rutină de depanare
Când un răspuns nu corespunde așteptărilor dumneavoastră, tentația este să rescrieți promptul. În schimb, începeți cu cinci verificări mecanice, în ordine: Este răspunsul complet? A răspuns modelul corect? Câți tokeni au fost consumați? Este răspunsul gol? Este raportul ieșire/intrare plauzibil? Un raport sub 1% pentru un prompt mare semnalează aproape întotdeauna că modelul a refuzat să proceseze cererea, mai degrabă decât să o fi gestionat greșit.
def debug_response(response):
"""Listă de verificare pentru depanarea răspunsurilor neașteptate."""
choice = response.choices[0]
# 1. Este răspunsul complet?
if choice.finish_reason == "length":
print("PROBLEMĂ: Răspuns trunchiat — măriți max_tokens")
# 2. A fost utilizat modelul corect?
print(f"Model: {response.model}")
# 3. Câți tokeni consumați?
print(f"Tokeni de intrare: {response.usage.prompt_tokens}")
print(f"Tokeni de ieșire: {response.usage.completion_tokens}")
# 4. Este răspunsul gol?
if not choice.message.content or not choice.message.content.strip():
print("PROBLEMĂ: Răspuns gol")
# 5. Raport suspect intrare/ieșire?
ratio = response.usage.completion_tokens / max(response.usage.prompt_tokens, 1)
if ratio < 0.01:
print(f"ATENȚIE: Raport ieșire/intrare foarte scăzut ({ratio:.4f})")
Puncte cheie
- Verificați întotdeauna
finish_reasonpentru a detecta trunchierea - Limitați istoricul conversației cu o fereastră glisantă
- Implementați reîncercarea cu backoff exponențial pentru erorile de rețea
- Utilizați criterii obiective și măsurabile în prompturile dumneavoastră
- Nu lăsați niciodată modelul să numere – validați în aplicație
- Jurnalizați fiecare apel API în producție pentru depanare și urmărirea costurilor