API antišablonai
Šiame puslapyje
Klaidos, kainuojančios pinigų veiklos metu
Aptarus geriausią praktiką, metas pažvelgti į kitą medalio pusę. Toliau pateikiami antišablonai – tai dažniausiai pasitaikančios spąstos naudojant „Chat Completions“ API. Jie turi vieną nemalonų bruožą: kūrimo metu jie nepasireiškia. Iš dešimties bandomųjų užklausų viskas veikia puikiai. Tačiau veiklos metu jie sukelia problemų: netikėtas išlaidas, nenuoseklius atsakymus, didelę delsą arba, dar blogiau, konfidencialių duomenų nutekėjimą.
Apkarpyto atsakymo laikymas pilnu
Dažniausia klaida – ignoruoti finish_reason. Prašai sutarties, gauni tekstą, įrašai jį į duomenų bazę. Tik štai max_tokens=100 nutraukė generavimą viduryje punkto, ir niekas to nepastebi, kol klientas nepasirašo. Sprendimas užima tris kodo eilutes ir turi tapti refleksu.
# BLOGAI – nėra patikrinimo
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Draft a complete contract."}],
max_tokens=100 # Per trumpa sutarčiai!
)
contract = response.choices[0].message.content # Galimai apkarpymas!
# GERAI – sisteminis patikrinimas
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("WARNING: Response truncated, increase max_tokens")
else:
contract = response.choices[0].message.content
Leisti pokalbio istorijai augti be ribų
Antra spąstų rūšis veikia lėtai. Pokalbio ciklas, siunčiantis visą pokalbio istoriją kiekvienu žingsniu, puikiai veikia pirmuosius dešimt apsikeitimų, dvidešimtuoju kainuoja dvigubai, o šimtuoju viršija konteksto langą – sąskaita auga ta pačia kreive. Sprendimas – palikti sistemos promptą (nekeičiamas) ir išsaugoti tik paskutinius N pranešimus.
# BLOGAI – istorija auga neribotai
conversation = []
while True:
user_input = input("You: ")
conversation.append({"role": "user", "content": user_input})
response = client.chat.complete(
model="mistral-large-latest",
messages=conversation # 100 apsikeitimų = tūkstančiai tokenų!
)
reply = response.choices[0].message.content
conversation.append({"role": "assistant", "content": reply})
# GERAI – slenkantis langas su apipjaustymu
MAX_MESSAGES = 20
def trim_conversation(messages: list, max_messages: int = MAX_MESSAGES) -> list:
"""Išsaugo sistemos promptą ir paskutinius N pranešimų."""
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
Manyti, kad tinklas visada atsako
Paprastas API iškvietimas daro prielaidą, kad niekas nepasirodys: jokių laiko limitų viršijimų, jokių 429, jokių 500 klaidų. Veiklos metu nutinka visi trys atvejai, o trečiasis – pačiu netinkamiausiu momentu. Atkreipk dėmesį į skirtumą kode: 429 klaida pateisina eksponentinį delsos didinimą, serverio klaida reikalauja sekundės kantrybės, tačiau kliento klaida, pvz., 400 ar 401, niekada neturi būti kartojama – tavo raktas netaps galiojančiu trečiuoju bandymu; tik atidėsi diagnostiką.
# BLOGAI – nėra klaidų apdorojimo
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Hello"}]
)
# Sugriūva viršijus laiką, gavus 429, 500...
# GERAI – kartojimas su eksponentine delsa
from mistralai.client.errors import SDKError
import time
def safe_complete(client, messages, max_retries=3, **kwargs):
"""API iškvietimas su kartojimu ir eksponentine delsa."""
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"Rate limit hit, waiting {wait}s...")
time.sleep(wait)
elif e.status_code >= 500:
time.sleep(1)
else:
raise # Kliento klaida (400, 401) – nekartoti
raise Exception("Failed after 3 attempts")
Prašyti modelio daryti tai, ko jis negali
Čia susilieja trys antišablonai. Pirmasis – subjektyvi kalba: „trumpas“, „daug“, „įdomus“ nieko konkrečiai nereiškia, ir modelis kiekvieną kartą nuspręs kitaip. Pakeisk kiekvieną būdvardį skaičiumi arba stebimu kriterijumi.
# BLOGAI – subjektyvu, nematuojama
"Write a short summary." # Trumpas = 1 sakinys? 1 pastraipa?
"Give many examples." # Daug = 3? 10? 50?
"Answer in an interesting way." # Įdomu pagal kokius kriterijus?
# GERAI – objektyvūs kriterijai
"Write a summary of 50 to 80 words."
"Give exactly 5 examples, one per line."
"Start every response with a relevant statistic."
Antrasis – leisti modeliui skaičiuoti. Didieji kalbos modeliai (LLM) yra prastai pritaikyti skaičiuoti žodžius, simbolius ar elementus: prašymas „tiksliai 280 simbolių“ sukurs tekstą iš 240 arba 310 simbolių. Skaičiavimas priklauso tavo programai, o ne modeliui.
# BLOGAI – modelis negali tiksliai skaičiuoti
"Write exactly 280 characters for a tweet."
# GERAI – skaičiuok programos pusėje
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)} chars): {tweet}")
Trečiasis priklauso tai pačiai šeimai: skaitinės skalės. „Įvertink nuo 1 iki 5“ daro prielaidą, kad modelis turi stabilų skirtumo tarp 3 ir 4 supratimą, ko jis neturi. Žodinė skalė, kurioje kiekvienas žingsnis apibrėžtas kriterijumi, duoda daug atkartojamesnius įvertinimus.
# BLOGAI – modeliai prastai interpretuoja skaitines skales
"Rate the quality of this text from 1 to 5."
# GERAI – žodinė skalė su apibrėžimais
"""Rate the quality of this text according to the following scale:
- EXCELLENT: Clear, well-structured, no errors
- GOOD: Generally correct, minor improvements possible
- AVERAGE: Understandable but lacks structure or contains errors
- POOR: Difficult to understand, significant errors
- VERY POOR: Incomprehensible or off-topic
Respond only with the label in uppercase."""
Diegti nepaliekant pėdsakų
Paskutinis antišablonas yra pats nepastebimiausias: iškvieti API, grąžinti turinį ir nieko nesaugoti. Tą dieną, kai vartotojas praneša apie absurdišką atsakymą, neturi nei užklausos ID, nei tikrojo naudoto modelio, nei tokenų sunaudojimo duomenų. Struktūruotas registravimas kiekvienam iškvietimui kainuoja kelias milisekundes ir leidžia atlikti tyrimą.
# BLOGAI – nėra pėdsakų
response = client.chat.complete(
model="mistral-large-latest",
messages=messages
)
return response.choices[0].message.content
# GERAI – struktūruotas registravimas
import logging
import json
logger = logging.getLogger("mistral_api")
def logged_complete(client, messages, **kwargs):
"""API iškvietimas su struktūruotu registravimu."""
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
Derinimo rutina
Kai atsakymas neatitinka lūkesčių, pagunda – perrašyti promptą. Vietoj to, pradėk nuo penkių mechaninių patikrinimų tokia tvarka: ar atsakymas pilnas? Ar atsakė teisingas modelis? Kiek tokenų sunaudota? Ar atsakymas tuščias? Ar išvesties ir įvesties santykis tikėtinas? Santykis, mažesnis nei 1% dideliam promptui, beveik visada rodo, kad modelis atsisakė apdoroti užklausą, o ne ją neteisingai apdorojo.
def debug_response(response):
"""Derinimo kontrolinis sąrašas netikėtiems atsakymams."""
choice = response.choices[0]
# 1. Ar atsakymas pilnas?
if choice.finish_reason == "length":
print("ISSUE: Response truncated — increase max_tokens")
# 2. Ar naudotas teisingas modelis?
print(f"Model: {response.model}")
# 3. Kiek tokenų sunaudota?
print(f"Input tokens: {response.usage.prompt_tokens}")
print(f"Output tokens: {response.usage.completion_tokens}")
# 4. Ar atsakymas tuščias?
if not choice.message.content or not choice.message.content.strip():
print("ISSUE: Empty response")
# 5. Įtartinas įvesties/išvesties santykis?
ratio = response.usage.completion_tokens / max(response.usage.prompt_tokens, 1)
if ratio < 0.01:
print(f"WARNING: Very low output/input ratio ({ratio:.4f})")
Svarbiausi punktai
- Visada tikrink
finish_reason, kad aptiktum apkarpymą - Apribok pokalbio istoriją naudodamas slenkantį langą
- Įgyvendink kartojimą su eksponentine delsa tinklo klaidoms
- Naudok objektyvius, išmatuojamus kriterijus savo promptuose
- Niekada neleisk modeliui skaičiuoti – patikrink programos pusėje
- Registruok kiekvieną API iškvietimą veiklos metu derinimui ir išlaidų stebėsenai