Lähe põhisisu juurde
Eesti— Vali keel
Menüü

API vastumustrid

Õppetund 12 / 16 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Vead, mis tootmises raha maksavad
  2. Lühendatud vastuse käsitlemine terviklikuna
  3. Vestlusajaloo piiramata kasvamine
  4. Eeldus, et võrk vastab alati
  5. Mudelilt küsimine teha seda, mida ta ei saa
  6. Kasutuselevõtt ilma jäljeta
  7. Silumisrutiin
  8. Peamised punktid

Vead, mis tootmises raha maksavad

Pärast parimate tavade käsitlemist on aeg vaadata medalit teist külge. Allpool toodud vastumustrid on Chat Completions API kasutamisel kõige levinumad lõksud ja neil on üks ebameeldiv omadus: need ei avaldu arendusetapis. Kümnest testpäringust töötab kõik suurepäraselt. Tootmises aga need plahvatavad, põhjustades ootamatuid kulusid, ebajärjekindlaid vastuseid, suurt latentsust või, mis veel hullem, tundlike andmete leketeid.

Lühendatud vastuse käsitlemine terviklikuna

Kõige levinum viga on finish_reason eiramine. Küsid lepingut, saad mingi teksti tagasi, salvestad selle andmebaasi: välja arvatud see, et max_tokens=100 katkestas genereerimise keset lõiku ja keegi ei märka seda enne, kui klient on alla kirjutanud. Parandus võtab kolm koodirida ja peaks muutuma refleksiks.

# HALB — kontroll puudub
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Draft a complete contract."}],
    max_tokens=100  # Lepingule liiga lühike!
)
contract = response.choices[0].message.content  # Võimalik, et lühendatud!

# HEA — süstemaatiline kontroll
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("HOIATUS: Vastus lühendatud, suurenda max_tokens")
else:
    contract = response.choices[0].message.content

Vestlusajaloo piiramata kasvamine

Teine lõks käivitub aeglaselt. Vestlutsükkel, mis saadab igal sammul kogu vestlusajaloo, töötab esimese kümne vahetuse jooksul veatult, maksab kahekordselt kahekümnendaks ja ületab sajandaks kontekstiakna – arve järgib sama kõverat. Lahendus on hoida süsteemne sisendkäsk (mitte läbiräägitav) ja säilitada ainult viimased N sõnumit.

# HALB — ajaloo kasv on piiramatu
conversation = []
while True:
    user_input = input("Sina: ")
    conversation.append({"role": "user", "content": user_input})
    response = client.chat.complete(
        model="mistral-large-latest",
        messages=conversation  # 100 vahetust = tuhanded tokenid!
    )
    reply = response.choices[0].message.content
    conversation.append({"role": "assistant", "content": reply})

# HEA – libisev aken kärpimisega
MAX_MESSAGES = 20

def trim_conversation(messages: list, max_messages: int = MAX_MESSAGES) -> list:
    """Säilitab süsteemse sisendkäsu + viimased N sõnumit."""
    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

Eeldus, et võrk vastab alati

Paljas API väljakutse eeldab, et midagi ei lähe valesti: ei ajalõppe, ei 429 veakoode, ei 500 vigu. Tootmises juhtuvad kõik kolm ja kolmas neist kõige ebasobivamal hetkel. Pane tähele erinevust koodis: 429 õigustab eksponentsiaalset tagasipöördumist, serveriviga väärib sekundit kannatlikkust, kuid kliendiviga nagu 400 või 401 ei tohi kunagi uuesti proovida – sinu võti ei muutu kolmandal katsel kehtivaks; sa ainult lükkad diagnoosi edasi.

# HALB — veakäsitlus puudub
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Hello"}]
)
# Kukkub kokku ajalõpu, 429, 500 korral...

# HEA — kordusproov eksponentsiaalse tagasipöördumisega
from mistralai.client.errors import SDKError
import time

def safe_complete(client, messages, max_retries=3, **kwargs):
    """API väljakutse kordusproovi ja eksponentsiaalse tagasipöördumisega."""
    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"Kiiruse piirang tabatud, ootan {wait}s...")
                time.sleep(wait)
            elif e.status_code >= 500:
                time.sleep(1)
            else:
                raise  # Kliendiviga (400, 401) — ära korda
    raise Exception("Ebaõnnestus pärast 3 katset")

Mudelilt küsimine teha seda, mida ta ei saa

Siin koondub kolm vastumustrit. Esimene on subjektiivne keel: „lühike“, „palju“, „huvitav“ ei viita millelegi kontrollitavale ja mudel otsustab iga väljakutse korral erinevalt. Asenda iga omadussõna numbri või vaadeldava kriteeriumiga.

# HALB — subjektiivne, mitte mõõdetav
"Kirjuta lühike kokkuvõte."           # Lühike = 1 lause? 1 lõik?
"Too palju näiteid."              # Palju = 3? 10? 50?
"Vasta huvitaval viisil."    # Huvitav milliste kriteeriumide alusel?

# HEA — objektiivsed kriteeriumid
"Kirjuta 50–80 sõna pikk kokkuvõte."
"Too täpselt 5 näidet, igaüks uuel real."
"Alusta iga vastust asjakohase statistikaga."

Teine on lugemise usaldamine mudelile. LLM-id on kurikuulsalt halvad sõnade, märkide ja üksuste lugemisel: „täpselt 280 märgi“ küsimine toodab teksti, mis on 240 või 310 märki pikk. Lugemine kuulub sinu rakendusse, mitte mudelisse.

# HALB — mudel ei suuda täpselt lugeda
"Kirjuta säutsu jaoks täpselt 280 märki."

# HEA — loe rakenduse poolel
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"Säuts ({len(tweet)} märki): {tweet}")

Kolmas kuulub samasse perekonda: numbrilised skaalad. „Hinda 1–5“ eeldab, et mudelil on stabiilne ettekujutus lõhest 3 ja 4 vahel, mida tal pole. Verbaalne skaala, kus iga aste on defineeritud kriteeriumiga, annab palju reprodutseeritavamaid hinnanguid.

# HALB — mudelid tõlgendavad numbrilisi skaalasid halvasti
"Hinda selle teksti kvaliteeti 1–5."

# HEA — definitsioonidega verbaalne skaala
"""Hinda selle teksti kvaliteeti vastavalt järgmisele skaalale:
- SUUREPÄRANE: Selge, hästi struktureeritud, vigu pole
- HEA: Üldiselt korrektne, väikesed parandused võimalikud
- KESKMINE: Arusaadav, kuid puudub struktuur või sisaldab vigu
- HALB: Raskesti arusaadav, olulised vead
- VÄGA HALB: Arusaamatu või teemast väljas

Vasta ainult sildiga SUURTÄHTEDES."""

Kasutuselevõtt ilma jäljeta

Viimane vastumuster on kõige diskreetsem: API kutsumine, sisu tagastamine ja mitte millegi säilitamine. Päeval, kui kasutaja teatab aberrantsest vastusest, pole sul ei päringu ID-d, ei tegelikku serveeritud mudelit ega tokenite tarbimist. Struktureeritud logimine iga väljakutse kohta maksab mõni millisekund ja võimaldab uurimist.

# HALB — jälgi pole
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages
)
return response.choices[0].message.content

# HEA — struktureeritud logimine
import logging
import json

logger = logging.getLogger("mistral_api")

def logged_complete(client, messages, **kwargs):
    """API väljakutse struktureeritud logimisega."""
    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

Silumisrutiin

Kui vastus ei vasta sinu ootustele, on kiusatus sisendkäsk ümber kirjutada. Selle asemel alusta viiest mehaanilisest kontrollist järjekorras: kas vastus on täielik? Kas vastas õige mudel? Mitu tokenit tarbiti? Kas vastus on tühi? Kas väljundi/sisendi suhe on usutav? Suure sisendkäsu korral alla 1% olev suhe annab peaaegu alati märku, et mudel keeldus päringut töötlemast, mitte ei käsitlenud seda valesti.

def debug_response(response):
    """Ootamatute vastuste silumise kontrollnimekiri."""
    choice = response.choices[0]

    # 1. Kas vastus on täielik?
    if choice.finish_reason == "length":
        print("PROBLEEM: Vastus lühendatud — suurenda max_tokens")

    # 2. Kas kasutati õiget mudelit?
    print(f"Mudel: {response.model}")

    # 3. Mitu tokenit tarbiti?
    print(f"Sisendtokenid: {response.usage.prompt_tokens}")
    print(f"Väljundtokenid: {response.usage.completion_tokens}")

    # 4. Kas vastus on tühi?
    if not choice.message.content or not choice.message.content.strip():
        print("PROBLEEM: Tühi vastus")

    # 5. Kahtlane sisendi/väljundi suhe?
    ratio = response.usage.completion_tokens / max(response.usage.prompt_tokens, 1)
    if ratio < 0.01:
        print(f"HOIATUS: Väga madal väljundi/sisendi suhe ({ratio:.4f})")

Peamised punktid

  • Alati kontrolli finish_reason, et tuvastada lühendamine
  • Piira vestlusajalugu libiseva aknaga
  • Rakenda võrguvigade jaoks kordusproov eksponentsiaalse tagasipöördumisega
  • Kasuta oma sisendkäskudes objektiivseid, mõõdetavaid kriteeriume
  • Ära kunagi lase mudelil lugeda – valideeri rakenduse poolel
  • Logi iga API väljakutse tootmises silumise ja kulude jälgimise jaoks