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

Parimad tavad tootmises

Õppetund 16 / 16 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. Tõestuskontseptsioonist kasutuselevõtuni
  2. Autentimine ja mudeli versioonimine
  3. Klient, mis haldab intsidente
  4. Jälgi kulusid reaalajas
  5. Valideeri mõlemas otsas
  6. Hoia kontekstiakent
  7. Mida sa sellest kursusest kaasa võtad
  8. Peamised punktid
  9. Testi oma teadmisi

Tõestuskontseptsioonist kasutuselevõtuni

Nüüd valdad sa Chat Completions API kõiki parameetreid. Kõige keerulisem osa on alles ees: ületada lõhe toimiva märkmiku ja teenuse vahel, mida teised kasutavad ilma sinu sekkumiseta. See viimane tund koondab kogu kursuse teostatavaks tootmise kontrollnimekirjaks ja osutab seejärel edasistele kursustele.

Autentimine ja mudeli versioonimine

Enne esimest äriloogika rida tuleb teha kaks otsust. Esimene puudutab API võtit: see peab asuma keskkonnamuutujas, mitte kunagi koodis, ning käivitamise kinnitus on parem kui None, mis levib kolm kihti allapoole arusaamatu veateateni. Planeeri ka võtmete rotatsiooni – kui soovid vältida teenuse seisakut, loo uus võti, võta see kasutusele ja alles seejärel tühistada vana, just selles järjekorras.

import os

# ALATI: API võti keskkonnamuutujas
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY pole defineeritud"

# MITTE KUNAGI: kodeeritud võti koodis
# api_key = "sk-abc123..."  # TOOTMISES KEELATUD

# ALATI: regulaarne võtmete rotatsioon
# Loo uus võti, võta see kasutusele, seejärel tühistada vana

Teine otsus puudutab mudeli identifikaatorit. Arenduses annab -latest sulle täiustusi ilma vaevata. Tootmises tähendab sama alias seda, et teenusepakkuja poolne versioonimuutus võib muuta sinu rakenduse käitumist hoiatuseta, teisipäeva hommikul, ilma ühegi commit’i jäljeta, mis seda selgitaks. Lukusta versioon.

# ARENDUS — uusim versioon
model = "mistral-large-latest"

# TOOTMINE — fikseeritud versioon reprodutseeritavuse jaoks
model = "mistral-large-2512"

# Miks? "latest" muutus võib muuta sinu rakenduse käitumist
# ilma hoiatuseta.

Klient, mis haldab intsidente

Tootmisintegratsiooni süda ei ole API väljakutse, vaid kõik, mis seda ümbritseb. Allpool olev klass koondab kolm vastutust ühte kitsaskohta: korduskatsed eksponentsiaalse taganemisega 429 vigade korral, lühike paus serverivigade korral ja kliendivigade viivitamatu eskaleerimine, mida ükski korduskatse ei paranda. Samuti normaliseerib see vastuse stabiilseks sõnastikuks – sisu, finish_reason, kasutus, mudel, ID – nii et ülejäänud kood ei sõltu enam SDK poolt tagastatud objekti täpsest kujust. Juba ainuüksi logger.warning kärpimiste kohta õigustab kapseldamist: see on ainus viis avastada, et max_tokens säte on liiga range, enne kui kasutajad sellest teatavad.

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

logger = logging.getLogger(__name__)

class MistralClient:
    """Tootmisklient korduskatsete, aegumise ja logimisega."""

    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,
                }

                # Hoiata, kui vastus on kärbitud
                if result["finish_reason"] == "length":
                    logger.warning(f"Vastus kärbitud — req_id={response.id}")

                return result

            except SDKError as e:
                if e.status_code == 429:
                    wait = 2 ** attempt
                    logger.warning(f"Kiiruse piirang, korduskatse {attempt+1}/{self.max_retries} {wait}s pärast")
                    time.sleep(wait)
                elif e.status_code >= 500:
                    logger.error(f"Serveri viga {e.status_code}, korduskatse {attempt+1}")
                    time.sleep(1)
                else:
                    logger.error(f"Kliendi viga {e.status_code}: {e.message}")
                    raise

        raise Exception(f"Ebaõnnestus pärast {self.max_retries} katset")

Jälgi kulusid reaalajas

Oma tarbimise avastamine igakuises arves on luksus, mida vähesed meeskonnad endale lubada saavad. Allpool olev jälgija kirjutab iga väljakutse kohta ühe JSONL rea – ajatempel, mudel, sisend- ja väljundtokenid, finish_reason, päringu ID – ja haldab sessiooni kogusummat, mida saad igal ajal pärida. JSONL formaat ei ole detail: see agregeerub mis tahes analüütikatööriistaga ilma parsimisetapita ja päringu ID olemasolu võimaldab seostada kulude anomaalia konkreetse väljakutsega.

import json
from datetime import datetime, timezone

class CostTracker:
    """Reaalajas API kulude jälgimine."""

    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"Sessioon — Prompt: {self.session_tokens['prompt']:,} | "
            f"Lõpetus: {self.session_tokens['completion']:,} | "
            f"Kokku: {total:,} tokenit"
        )

Valideeri mõlemas otsas

Tugev rakendus ei usalda ei seda, mis siseneb, ega seda, mis väljub. Sisendi puhul lükka tagasi tühjad sõnumid, piira pikkus 10 000 märgiga, et vältida õnnetu kopeeri-kleebi toimingu põhjustatud arve paisumist, ja eemalda juhtmärgid, mis häirivad tokeniseerimist. Väljundi puhul ära lükka midagi tagasi, kuid tekita hoiatusi: potentsiaalselt kärbitud vastus, ebanormaalselt lühike vastus (alla viie märgi), ebanormaalselt pikk vastus (üle 50 000). Need kolm signaali püüavad kinni valdava osa vaiksetest tõrgetest.

def validate_input(user_message: str) -> str:
    """Valideeri ja puhasta kasutaja sisend."""
    if not user_message or not user_message.strip():
        raise ValueError("Tühi sõnum")

    if len(user_message) > 10_000:
        raise ValueError("Sõnum liiga pikk (maks 10 000 märki)")

    # Puhasta juhtmärgid
    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:
    """Valideeri API väljund."""
    warnings = []

    if finish_reason == "length":
        warnings.append("Vastus potentsiaalselt kärbitud")

    if not content or len(content.strip()) < 5:
        warnings.append("Ebanormaalselt lühike vastus")

    if len(content) > 50_000:
        warnings.append("Ebanormaalselt pikk vastus")

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

Hoia kontekstiakent

Viimane probleem: pikkade vestluste aeglane triiv. Allpool olev funktsioon hindab mahtu ühe tokenina iga nelja prantsuse keele märgi kohta – ligikaudne hinnang, kuid piisav kaitseraudmena – ja lubab päringutel läbida, kuni need jäävad alla 80% piirangust. Üle selle säilitab see süsteemi vihje ja eemaldab vanimad sõnumid, kuni langus on alla 70%. See kahe lävendi vaheline vahe on tahtlik: kärpimine ainult käivitamise lävendini suruks funktsiooni järgmise sõnumiga taas punasesse tsooni.

def manage_context(messages: list, max_tokens: int = 100_000) -> list:
    """Hoia sõnumid mudeli tokenipiirangutes."""
    # Hinnang: 1 token ~ 4 märki prantsuse keeles
    total_chars = sum(len(m["content"]) for m in messages)
    estimated_tokens = total_chars // 4

    if estimated_tokens < max_tokens * 0.8:
        return messages  # Kõik mahub ära

    # Säilita süsteem + esimene ja viimane sõnum
    system = [m for m in messages if m["role"] == "system"]
    history = [m for m in messages if m["role"] != "system"]

    # Eemalda vanimad sõnumid
    while estimated_tokens > max_tokens * 0.7 and len(history) > 2:
        removed = history.pop(0)
        estimated_tokens -= len(removed["content"]) // 4

    return system + history

Mida sa sellest kursusest kaasa võtad

Teekond läbis neli sammu. Esiteks, põhitõed: lõpp-punkt, rollid, põhiparameetrid ja vastuse struktuur. Järgmiseks, voogedastus, koos SSE protokolliga, selle Pythoni implementatsiooniga, stoppjärjestustega ja kõvendamisega safe_prompt ja kaitseraudade kaudu. Sõnastamine hõivas kolmanda faasi – tootmise süsteemi vihjed, few-shot, XML ja Markdown struktureerimine, anti-mustrid. Täiustatud parameetrid sulgesid ringi: temperatuur ja Top P detailselt, olemasolu ja sageduse trahvid, N lõpetust ja see tootmise kontrollnimekiri.

Allpool olev konfiguratsioon destilleerib need valikud kaitstavaks lähtepunktiks esimesele tootmise kasutuselevõtule: fikseeritud versioon, kasutusjuhtumile sobiv tokeni lagi, madal temperatuur faktilise järjepidevuse jaoks, top_p puutumata, kuna temperatuuri kohandatakse, neutraalsed trahvid, kui konkreetne vajadus neid ei õigusta, ja safe_prompt lubatud.

# Tüüpiline konfiguratsioon tootmisrakendusele
PRODUCTION_CONFIG = {
    "model": "mistral-large-2512",      # Fikseeritud versioon
    "max_tokens": 2000,                  # Sobib kasutusjuhtumile
    "temperature": 0.3,                  # Järjepidev ja faktiline
    "top_p": 1.0,                        # Puutumata, kui temperatuuri kohandatakse
    "presence_penalty": 0.0,             # Vaikimisi, kui pole konkreetset vajadust
    "frequency_penalty": 0.0,            # Vaikimisi, kui pole konkreetset vajadust
    "safe_prompt": True,                 # Ohutus lubatud
}

Mistral API-ga veelgi sügavamale minekuks järgnevad Corsen Academy’s neli täiendavat kursust:

  • Manused ja RAG – Semantiline otsing mistral-embed ja vektorandmebaasidega
  • Funktsioonide kutsumine – Ühenda mudel oma tööriistade ja väliste API-dega
  • Peenhäälestus – Kohanda mudel oma konkreetsele domeenile
  • Tootmine ja hindamine – Mõõdikud, automatiseeritud hindamised, kulude optimeerimine

Peamised punktid

  • Kasuta tootmises versioonitud mudeleid, mitte kunagi -latest
  • Rakenda korduskatsed + taganemine + logimine alates esimesest kasutuselevõtust
  • Valideeri iga API väljakutse nii sisendeid KUI KA väljundeid
  • Jälgi kulusid reaalajas tokenite jälgijaga
  • Halda kontekstiakent pikkade vestluste jaoks
  • Luba safe_prompt minimaalse ohutusvõrguna
  • Testi oma sõnastusi ääreluhtudega enne iga tootmise väljalaset

Testi oma teadmisi

Chat/completions lõpp-punktis pole enam saladusi? Veendume selles.

1. Millised rollid struktureerivad sõnumite loendit?

Vastus: system (raamistik), user (päringud), assistant (mudeli vastused) – kogu ajalugu algab iga väljakutsega uuesti, kuna API on olekuta.

2. Mida leiad vastuse välja `usage`?

Vastus: Sisendis ja väljundis tarbitud tokenid – arveldamise alus ja mõõdik, mida jälgida suuruse ja kulude jaoks.

3. Kuidas SSE voogedastus toimib?

Vastus: Vastus saabub Server-Sent Events’ina, fragment haaval: kuvad seda saabumise järgi ja liidad kokku, et saada lõplik sõnum.

4. Milleks on stoppjärjestused?

Vastus: Generatsiooni katkestamiseks niipea, kui antud string ilmub: kontrolli pikkust, peatu eraldaja juures, garanteeri puhtad formaadid.

5. Temperatuur, Top P, trahvid: milline kasutus tootmises?

Vastus: Temperatuur/Top P määravad determinismi ülesande kohta; olemasolu/sageduse trahvid piiravad kordamist – seaded, mis tuleb fikseerida kasutusjuhtumi põhjal ja dokumenteerida koos oma sõnastustega.

Rollid, kasutus, voogedastus, stopid, häälestus: põhitõed kehtivad – ülaltoodud tootmise parimad tavad panevad need õigesse järjekorda.