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

Käytännöt tuotantoympäristöön

Oppitunti 16 / 16 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Konseptista tuotantoon
  2. Todennus ja malliversioinnit
  3. Asiakasohjelma, joka hallitsee häiriötilanteet
  4. Seuraa kustannuksia reaaliajassa
  5. Validoi molemmissa päissä
  6. Hallitse konteksti-ikkunaa
  7. Mitä otit mukaan tästä kurssista
  8. Keskeiset asiat
  9. Testaa tietämyksesi

Konseptista tuotantoon

Hallitset nyt kaikki Chat Completions -rajapinnan parametrit. Haastavin osuus on vielä edessä: kuilu toimivan muistikirjan ja palvelun välillä, jota muut käyttävät ilman väliintuloasi. Tämä viimeinen oppitunti tiivistää koko kurssin toimintakelpoiseksi tuotantotarkistuslistaksi ja osoittaa suunnan jatkokursseille.

Todennus ja malliversioinnit

Ennen ensimmäistä liiketoimintalogiikan riviä on tehtävä kaksi päätöstä. Ensimmäinen koskee API-avainta: sen tulee olla ympäristömuuttujassa, ei koskaan koodissa, ja käynnistyksen aikainen varmistus on parempi kuin None, joka etenee kolme tasoa alaspäin aiheuttaen käsittämättömän virheilmoituksen. Suunnittele myös kierto: luo uusi avain, ota se käyttöön ja peruuta vanha – tässä järjestyksessä, jos haluat välttää palvelun katkokset.

import os

# AINA: API-avain ympäristömuuttujassa
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY not defined"

# EI KOSKAAN: kovakoodattu avain koodissa
# api_key = "sk-abc123..."  # KIELLETTY tuotannossa

# AINA: säännöllinen avainten kierto
# Luo uusi avain, ota se käyttöön, peruuta sitten vanha

Toinen päätös koskee mallitunnistetta. Kehitysvaiheessa -latest antaa parannuksia ilman vaivaa. Tuotannossa sama alias tarkoittaa, että tarjoajan puolella tapahtuva versiopäivitys voi muuttaa sovelluksesi toimintaa ilman varoitusta, keskellä tiistai-aamua, ilman commit-historiaan kirjattua selitystä. Lukitse versio.

# KEHITYS — uusin versio
model = "mistral-large-latest"

# TUOTANTO — kiinteä versio toistettavuuden vuoksi
model = "mistral-large-2512"

# Miksi? "latest"-muutos voi muuttaa sovelluksesi toimintaa
# ilman varoitusta.

Asiakasohjelma, joka hallitsee häiriötilanteet

Tuotantointegraation ydin ei ole API-kutsu itse, vaan kaikki sen ympärillä. Alla oleva luokka niputtaa kolme vastuuta yhteen tukikohtaan: uudelleenyritys eksponentiaalisella viiveellä 429-virheille, lyhyt tauko palvelinvirheillä ja asiakasvirheiden välitön eskalointi, joita mikään uudelleenyritys ei korjaa. Se myös normalisoi vastauksen vakaaksi sanakirjaksi – sisältö, finish_reason, käyttö, malli, ID – jotta loput koodistasi eivät enää riipu SDK:n palauttaman objektin tarkasta rakenteesta. Pelkkä logger.warning typistyksistä oikeuttaa kapseloinnin: se on ainoa tapa huomata, että max_tokens-asetus on liian tiukka, ennen kuin käyttäjät valittavat siitä.

from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import time
import logging

logger = logging.getLogger(__name__)

class MistralClient:
    """Tuotantoasiakas uudelleenyrityksillä, aikakatkaisulla ja lokituksella."""

    def __init__(self, api_key: str, max_retries: int = 3):
        self.client = Mistral(api_key=api_key)
        self.max_retries = max_retries

    def complete(self, messages: list, **kwargs) -> dict:
        for attempt in range(self.max_retries):
            try:
                response = self.client.chat.complete(
                    messages=messages,
                    **kwargs
                )

                result = {
                    "content": response.choices[0].message.content,
                    "finish_reason": response.choices[0].finish_reason,
                    "usage": {
                        "prompt": response.usage.prompt_tokens,
                        "completion": response.usage.completion_tokens,
                        "total": response.usage.total_tokens,
                    },
                    "model": response.model,
                    "id": response.id,
                }

                # Hälytys, jos vastaus typistyi
                if result["finish_reason"] == "length":
                    logger.warning(f"Response truncated — req_id={response.id}")

                return result

            except SDKError as e:
                if e.status_code == 429:
                    wait = 2 ** attempt
                    logger.warning(f"Rate limit, retry {attempt+1}/{self.max_retries} in {wait}s")
                    time.sleep(wait)
                elif e.status_code >= 500:
                    logger.error(f"Server error {e.status_code}, retry {attempt+1}")
                    time.sleep(1)
                else:
                    logger.error(f"Client error {e.status_code}: {e.message}")
                    raise

        raise Exception(f"Failed after {self.max_retries} attempts")

Seuraa kustannuksia reaaliajassa

Kulutuksen havaitseminen kuukausilaskulta on ylellisyyttä, jota harvat tiimit voivat sallia. Alla oleva seuranta kirjoittaa yhden JSONL-rivin kutakin kutsua kohti – aikaleima, malli, syöte- ja tulostetokenit, finish_reason, pyyntötunniste – ja ylläpitää istunnon kokonaissummaa, jonka voit kysyä milloin tahansa. JSONL-muoto ei ole yksityiskohta: se aggregoituu minkä tahansa analytiikkatyökalun kanssa ilman jäsentämisvaihetta, ja pyyntötunnisteen olemassaolo mahdollistaa kustannuspoikkeaman sidomisen tiettyyn kutsuun.

import json
from datetime import datetime, timezone

class CostTracker:
    """API-kustannusten reaaliaikainen seuranta."""

    def __init__(self, log_path: str = "api_costs.jsonl"):
        self.log_path = log_path
        self.session_tokens = {"prompt": 0, "completion": 0}

    def log(self, response_data: dict):
        usage = response_data["usage"]
        self.session_tokens["prompt"] += usage["prompt"]
        self.session_tokens["completion"] += usage["completion"]

        entry = {
            "ts": datetime.now(timezone.utc).isoformat(),
            "model": response_data["model"],
            "prompt_tokens": usage["prompt"],
            "completion_tokens": usage["completion"],
            "finish_reason": response_data["finish_reason"],
            "id": response_data["id"],
        }

        with open(self.log_path, "a") as f:
            f.write(json.dumps(entry) + "\n")

    def report(self) -> str:
        total = self.session_tokens["prompt"] + self.session_tokens["completion"]
        return (
            f"Session — Prompt: {self.session_tokens['prompt']:,} | "
            f"Completion: {self.session_tokens['completion']:,} | "
            f"Total: {total:,} tokens"
        )

Validoi molemmissa päissä

Vankka sovellus ei luota siihen, mitä menee sisään eikä siihen, mitä tulee ulos. Syötteessä hylkää tyhjät viestit, rajoita pituus 10 000 merkkiin estääksesi epäonnisen kopioi-liitä -operaation kasvattamasta laskuasi, ja poista ohjausmerkit, jotka häiritsevät tokenisointia. Tulosteessa älä hylkää mitään, mutta nosta varoituksia: mahdollisesti typistynyt vastaus, epänormaalisti lyhyt vastaus (alle 5 merkkiä), epänormaalisti pitkä vastaus (yli 50 000). Nämä kolme signaalia catches valtaosan hiljaisista virheistä.

def validate_input(user_message: str) -> str:
    """Validoi ja siivoa käyttäjän syöte."""
    if not user_message or not user_message.strip():
        raise ValueError("Empty message")

    if len(user_message) > 10_000:
        raise ValueError("Message too long (max 10,000 characters)")

    # Siivoa ohjausmerkit
    cleaned = "".join(c for c in user_message if c.isprintable() or c in "\n\t")
    return cleaned.strip()

def validate_output(content: str, finish_reason: str) -> dict:
    """Validoi API:n tuloste."""
    warnings = []

    if finish_reason == "length":
        warnings.append("Response potentially truncated")

    if not content or len(content.strip()) < 5:
        warnings.append("Abnormally short response")

    if len(content) > 50_000:
        warnings.append("Abnormally long response")

    return {"content": content, "warnings": warnings, "valid": len(warnings) == 0}

Hallitse konteksti-ikkunaa

Viimeinen ongelma: pitkien keskustelujen hidas ajelehtiminen. Alla oleva funktio arvioi volyymin yhdeksi tokeniksi neljää merkkiä kohti ranskankielessä – karkea approksimaatio, mutta riittävä suojaksi – ja päästää pyynnöt läpi niin kauan kuin ne pysyvät alle 80 % rajasta. Sen yli se säilyttää järjestelmäkehotteen ja poistaa vanhimpia viestejä, kunnes määrä laskee alle 70 %. Tämä kuilu kahden kynnyksen välillä on tahallinen: leikkaaminen vain laukaisukynnykseen työntäisi funktion takaisin punaiselle seuraavassa viestissä.

def manage_context(messages: list, max_tokens: int = 100_000) -> list:
    """Pidä viestit mallin tokenrajoituksen sisällä."""
    # Arvio: 1 token ~ 4 merkkiä ranskaksi
    total_chars = sum(len(m["content"]) for m in messages)
    estimated_tokens = total_chars // 4

    if estimated_tokens < max_tokens * 0.8:
        return messages  # Kaikki mahtuu

    # Säilytä järjestelmä + ensimmäinen ja viimeinen viesti
    system = [m for m in messages if m["role"] == "system"]
    history = [m for m in messages if m["role"] != "system"]

    # Poista vanhimpia viestejä
    while estimated_tokens > max_tokens * 0.7 and len(history) > 2:
        removed = history.pop(0)
        estimated_tokens -= len(removed["content"]) // 4

    return system + history

Mitä otit mukaan tästä kurssista

Matka eteni neljässä vaiheessa. Ensinnäkin perusteet: päätepiste, roolit, perusparametrit ja vastauksen rakenne. Seuraavaksi streamaus, jossa SSE-protokolla, sen Python-toteutus, lopetussekvenssit ja lujittaminen safe_prompt- ja guardrail-toiminnoilla. Kehotteet veivät kolmannen vaiheen – tuotantojärjestelmäkehotteet, few-shot, XML- ja Markdown-jäsennys, anti-mallit. Edistyneet parametrit päättivät kierroksen: lämpötila ja Top P yksityiskohtaisesti, läsnäolo- ja taajuussakot, N täydennystä ja tämä tuotantotarkistuslista.

Alla oleva konfiguraatio tiivistää nämä valinnat puolustettavaksi lähtökohdaksi ensimmäiseen tuotantoonottoon: kiinteä versio, käyttötarkoitukseen sopiva tokenkatto, matala lämpötila faktuaalista johdonmukaisuutta varten, top_p koskemattomana lämpötilan säädön vuoksi, neutraalit sakot ellei erityistarve perustele niitä, ja safe_prompt käytössä.

# Tyypillinen konfiguraatio tuotantosovellukselle
PRODUCTION_CONFIG = {
    "model": "mistral-large-2512",      # Kiinteä versio
    "max_tokens": 2000,                  # Sopii käyttötarkoitukseen
    "temperature": 0.3,                  # Johdonmukainen ja faktuaalinen
    "top_p": 1.0,                        # Koskematon, jos lämpötilaa säädetään
    "presence_penalty": 0.0,             # Oletus, ellei erityistarvetta
    "frequency_penalty": 0.0,            # Oletus, ellei erityistarvetta
    "safe_prompt": True,                 # Turvallisuus käytössä
}

Päästäksesi pidemmälle Mistral API:n kanssa, Corsen Academyssä seuraa neljä täydentävää kurssia:

  • Upotukset ja RAG – Semanttinen haku mistral-embed:llä ja vektoritietokannoilla
  • Funktio-kutsut – Yhdistä malli työkaluihisi ja ulkoisiin rajapintoihin
  • Hienosäätö – Mukauta malli omaan toimialaasi
  • Tuotanto ja arviointi – Mittarit, automatisoidut arvioinnit, kustannusten optimointi

Keskeiset asiat

  • Käytä versioituja malleja tuotannossa, ei koskaan -latest
  • Toteuta uudelleenyritys + viive + lokitus jo ensimmäisestä käyttöönotosta
  • Validoi jokaisen API-kutsun sekä syötteet ETTÄ tulosteet
  • Seuraa kustannuksia reaaliajassa token-seurannalla
  • Hallitse konteksti-ikkunaa pitkissä keskusteluissa
  • Ota safe_prompt käyttöön vähimmäisturvaverkkona
  • Testaa kehotteesi reunatapauksilla ennen jokaista tuotantoon julkaisua

Testaa tietämyksesi

Eikö chat/completions-päätepisteessä ole enää salaisuuksia? Varmistetaan asia.

1. Mitkä roolit jäsentelevät viestiluetteloa?

Vastaus: system (kehys), user (pyynnöt), assistant (mallin vastaukset) – koko historia alkaa alusta jokaisella kutsulla, sillä API on tilaton.

2. Mitä löydät vastauksen usage-kentästä?

Vastaus: Syötteessä ja tulosteessa kulutetut tokenit – laskutuksen perusta ja mittari, jota tulee seurata mitoituksen ja kustannusten vuoksi.

3. Miten SSE-streamaus toimii?

Vastaus: Vastaus saapuu Server-Sent Events -muodossa, osana osalta: näytät sen saapuessa ja yhdistät osat saadaksesi lopullisen viestin.

4. Mihin lopetussekvenssejä käytetään?

Vastaus: Katkaisemaan generointi heti, kun annettu merkkijono ilmestyy: hallitse pituutta, pysähdy erottimeen, takaa siistit muodot.

5. Lämpötila, Top P, sakot: mikä käyttö tuotannossa?

Vastaus: Lämpötila/Top P asettavat determinismin tehtäväkohtaisesti; läsnäolo-/taajuussakot rajoittavat toistoa – asetukset, jotka tulee lukita käyttötapausta kohti ja dokumentoida kehotteidesi yhteyteen.

Roolit, käyttö, streamaus, lopetukset, viritys: perusteet pitävät – yllä olevat tuotantokäytännöt järjestävät ne oikein.