Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

API:n anti-mallit

Oppitunti 12 / 16 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Virheet, jotka maksavat tuotantoympäristössä
  2. Katkenneen vastauksen hyväksyminen valmiiksi
  3. Keskusteluhistorian kasvamisen salliminen ilman rajoja
  4. Olettamus verkon aina vastaavan
  5. Mallin pyytäminen tekemään mahdottomia
  6. Käyttöönotto ilman jälkiä
  7. Vianmääritysrutiini
  8. Keskeiset asiat

Virheet, jotka maksavat tuotantoympäristössä

Kun parhaat käytännöt on käyty läpi, on aika tarkastella kääntöpuolta. Alla olevat anti-mallit ovat yleisimpiä sudenkuoppia Chat Completions API:a käytettäessä, ja niillä on yksi ikävä yhteinen piirre: ne eivät ilmene kehitysvaiheessa. Kymmenestä testipyynnöstä kaikki toimivat moitteettomasti. Ongelmat räjähtävät käsiin vasta tuotannossa, aiheuttaen odottamattomia kustannuksia, epäloogisia vastauksia, suurta viivettä tai pahimmillaan arkaluonteisten tietojen vuotamista.

Katkenneen vastauksen hyväksyminen valmiiksi

Yleisin virhe on finish_reason-kentän ignorointi. Pyydät sopimusta, saat tekstiä takaisin ja tallennat sen tietokantaan – paitsi että max_tokens=100 katkaisi generoinnin kesken lauseen, eikä kukaan huomaa sitä ennen kuin asiakas allekirjoittaa paperit. Korjaus vaatii kolme riviä koodia ja siitä tulee tehdä refleksi.

# HUONO — ei tarkistusta
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Draft a complete contract."}],
    max_tokens=100  # Liian lyhyt sopimukseen!
)
contract = response.choices[0].message.content  # Mahdollisesti katkennut!

# HYVÄ — systemaattinen tarkistus
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

Keskusteluhistorian kasvamisen salliminen ilman rajoja

Toinen ansa laukeaa hitaasti. Keskustelusilmukka, joka lähettää koko keskusteluhistorian jokaisella vuorolla, toimii täydellisesti ensimmäiset kymmenen vaihtoa, maksaa kaksinkertaisesti kahdennessakymmenennessä ja ylittää lopulta konteksti-ikkunan sadannessa – laskun seuraten samaa käyrää. Ratkaisu on pitää järjestelmäkehote (ei neuvoteltavissa) ja säilyttää vain viimeiset N viestiä.

# HUONO — historia kasvaa rajatta
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 vuoroa = tuhansia tokeneita!
    )
    reply = response.choices[0].message.content
    conversation.append({"role": "assistant", "content": reply})

# HYVÄ — liukuva ikkuna karsinnalla
MAX_MESSAGES = 20

def trim_conversation(messages: list, max_messages: int = MAX_MESSAGES) -> list:
    """Säilyttää järjestelmäkehotteen + viimeiset N viestiä."""
    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

Olettamus verkon aina vastaavan

Paljas API-kutsu olettaa, ettei mikään mene pieleen: ei aikakatkaisuja, ei 429-virheitä, ei 500-virheitä. Tuotannossa kaikkia kolmea esiintyy, ja kolmas tapahtuu huonoimpaan mahdolliseen hetkeen. Huomaa ero koodissa: 429 oikeuttaa eksponentiaaliseen odotukseen, palvelinvirhe vaatii sekunnin kärsivällisyyttä, mutta asiakasvirhe kuten 400 tai 401 ei saa koskaan johtaa uudelleenyritykseen – avaimesi ei muutu kelvolliseksi kolmannella yrittämällä; vain viivytät vianmääritystä.

# HUONO — ei virheenkäsittelyä
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Hello"}]
)
# Kaatuu aikakatkaisuun, 429, 500...

# HYVÄ — uudelleenyritys eksponentiaalisella odotuksella
from mistralai.client.errors import SDKError
import time

def safe_complete(client, messages, max_retries=3, **kwargs):
    """API-kutsu uudelleenyrityksellä ja eksponentiaalisella odotuksella."""
    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  # Asiakasvirhe (400, 401) — älä yritä uudelleen
    raise Exception("Failed after 3 attempts")

Mallin pyytäminen tekemään mahdottomia

Tässä kohtaavat kolme anti-mallia. Ensimmäinen on subjektiivinen kieli: “lyhyt”, “monta”, “mielenkiintoinen” eivät viittaa mihinkään varmennettavaan, ja malli päättää asian eri tavalla jokaisella kutsulla. Korvaa jokainen adjektiivi numerolla tai havainnoitavalla kriteerillä.

# HUONO — subjektiivinen, ei mitattavissa
"Write a short summary."           # Lyhyt = 1 lause? 1 kappale?
"Give many examples."              # Monta = 3? 10? 50?
"Answer in an interesting way."    # Mielenkiintoinen millä kriteereillä?

# HYVÄ — objektiiviset kriteerit
"Write a summary of 50 to 80 words."
"Give exactly 5 examples, one per line."
"Start every response with a relevant statistic."

Toinen virhe on laskemisen jättäminen mallin harteille. LLM-mallit ovat tunnetusti huonoja laskemaan sanoja, merkkejä ja kohteita: pyytäminen kirjoittamaan “tasan 280 merkkiä” tuottaa tekstiä, jossa on 240 tai 310 merkkiä. Laskeminen kuuluu sovelluksellesi, ei mallille.

# HUONO — malli ei osaa laskea tarkasti
"Write exactly 280 characters for a tweet."

# HYVÄ — laske sovelluspuolella
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}")

Kolmas kuuluu samaan perheeseen: numeeriset asteikot. “Arvioi asteikolla 1–5” olettaa, että mallilla on vakaa käsitys erosta lukujen 3 ja 4 välillä, mitä sillä ei ole. Sanallinen asteikko, jossa jokainen askel määritellään kriteerillä, tuottaa paljon toistettavampia arvioita.

# HUONO — mallit tulkitsevat numeerisia asteikkoja huonosti
"Rate the quality of this text from 1 to 5."

# HYVÄ — sanallinen asteikko määritelmillä
"""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."""

Käyttöönotto ilman jälkiä

Viimeinen anti-malli on kaikkein huomaamattomin: API:n kutsuminen, sisällön palauttaminen ja minkään tallentamatta jättäminen. Sinä päivänä, kun käyttäjä ilmoittaa poikkeavasta vastauksesta, sinulla ei ole pyyntötunnistetta, ei tietoa käytetystä mallista eikä tietoa tokenien kulutuksesta. Jäsennelty lokitus kutakin kutsua kohden maksaa muutaman millisekunnin ja tekee vianetsinnän mahdolliseksi.

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

# HYVÄ — jäsennelty lokitus
import logging
import json

logger = logging.getLogger("mistral_api")

def logged_complete(client, messages, **kwargs):
    """API-kutsu jäsennellyllä lokituksella."""
    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

Vianmääritysrutiini

Kun vastaus ei täytä odotuksiasi, kiusaus on kirjoittaa kehote uudelleen. Sen sijaan aloita viidestä mekaanisesta tarkistuksesta tässä järjestyksessä: Onko vastaus täydellinen? Vastasiko oikea malli? Kuinka monta tokenia kulutettiin? Onko vastaus tyhjä? Onko tulosteen ja syötteen suhde uskottava? Suhde, joka on alle 1 % suurella syötteellä, kertoo lähes aina, että malli kieltäytyi käsittelemästä pyyntöä sen sijaan, että se olisi käsitellyt sitä väärin.

def debug_response(response):
    """Vianmääritystarkistuslista odottamattomille vastauksille."""
    choice = response.choices[0]

    # 1. Onko vastaus täydellinen?
    if choice.finish_reason == "length":
        print("ISSUE: Response truncated — increase max_tokens")

    # 2. Käytettiinkö oikeaa mallia?
    print(f"Model: {response.model}")

    # 3. Kuinka monta tokenia kulutettiin?
    print(f"Input tokens: {response.usage.prompt_tokens}")
    print(f"Output tokens: {response.usage.completion_tokens}")

    # 4. Onko vastaus tyhjä?
    if not choice.message.content or not choice.message.content.strip():
        print("ISSUE: Empty response")

    # 5. Epäilyttävä syöte/tuloste-suhde?
    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})")

Keskeiset asiat

  • Tarkista aina finish_reason katkeamisen havaitsemiseksi
  • Rajoita keskusteluhistoriaa liukuvalla ikkunalla
  • Toteuta uudelleenyritys eksponentiaalisella odotuksella verkkovirheille
  • Käytä kehotteissasi objektiivisia, mitattavia kriteerejä
  • Älä koskaan anna mallin laskea – validoi sovelluspuolella
  • Lokita jokainen API-kutsu tuotannossa vianmääritystä ja kustannusseurantaa varten