Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Najboljše prakse za proizvodnjo

Lekcija 16 od 16 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Od dokaza koncepta do uvedbe v proizvodnjo
  2. Avtentikacija in različice modelov
  3. Odjemalec, ki obvladuje incidente
  4. Spremljaj stroške sproti
  5. Preverjaj na obeh koncih
  6. Obvladuj okno konteksta
  7. Kaj odnašaš s tega tečaja
  8. Ključne ugotovitve
  9. Preveri svoje znanje

Od dokaza koncepta do uvedbe v proizvodnjo

Zdaj obvladaš vsak parameter API-ja Chat Completions. Najtežji del šele sledi: premostiti razliko med delujočim zvezkom in storitvijo, ki jo drugi uporabljajo brez tvojega posredovanja. Ta zadnja lekcija združuje celoten tečaj v akcijski kontrolni seznam za proizvodnjo in kaže pot do nadaljevalnih tečajev.

Avtentikacija in različice modelov

Pred prvo vrstico poslovne logike moraš sprejeti dve odločitvi. Prva se nanaša na ključ API: ta mora živeti v okoljski spremenljivki, nikoli v kodi, trditev ob zagonu pa je boljša od vrednosti None, ki se prenese tri ravni globlje v nerazumljivo sporočilo o napaki. Načrtuj tudi rotacijo – če želiš preprečiti izpad storitve, najprej ustvari nov ključ, ga uvedi in šele nato prekliči starega, in to v tem vrstnem redu.

import os

# VEDNO: Ključ API v okoljski spremenljivki
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY not defined"

# NIKOLI: Ključ v kodiranju v kodi
# api_key = "sk-abc123..."  # PREPOVEDANO v proizvodnji

# VEDNO: Redna rotacija ključev
# Ustvari nov ključ, ga uvedi, nato prekliči starega

Druga odločitev zadeva identifikator modela. Med razvojem ti -latest prinaša izboljšave brez truda. V proizvodnji pa ista sopomenka pomeni, da lahko sprememba različice na strani ponudnika spremeni obnašanje tvoje aplikacije brez opozorila, recimo v torek zjutraj, brez sledi potrditve (commit), ki bi to pojasnila. Pripni različico.

# RAZVOJ — najnovejša različica
model = "mistral-large-latest"

# PROIZVODNJA — fiksna različica za ponovljivost
model = "mistral-large-2512"

# Zakaj? Sprememba "latest" lahko spremeni obnašanje tvoje aplikacije
# brez opozorila.

Odjemalec, ki obvladuje incidente

Srce proizvodne integracije ni klic API-ja, temveč vse, kar ga obdaja. Spodnji razred združuje tri odgovornosti v eno kritično točko: ponovni poskus z eksponentnim zamikom pri kodah 429, kratek premor pri napakah strežnika in takojšnje eskaliranje napak odjemalca, ki jih noben ponovni poskus ne bo popravil. Prav tako normalizira odgovor v stabilen slovar – vsebina, finish_reason, uporaba, model, ID – tako da preostanek tvoje kode ni več odvisen od točne oblike predmeta, ki ga vrne SDK. Sam logger.warning pri obrezovanjih upravičuje encapsulacijo: to je edini način, da odkriješ, da je nastavitev max_tokens prestroga, preden to prijavijo uporabniki.

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

logger = logging.getLogger(__name__)

class MistralClient:
    """Proizvodni odjemalec s ponovnimi poskusi, časovnim limitom in beleženjem."""

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

                # Opozorilo, če je odgovor obrezan
                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")

Spremljaj stroške sproti

Odkrivanje porabe na mesečnem računu je razkošje, ki si ga le redke ekipe lahko privoščijo. Spodnji sledilnik zapiše eno vrstico JSONL na klic – časovni žig, model, vhodni in izhodni žetoni, finish_reason, ID zahteve – in vzdržuje seštevek seje, ki ga lahko kadarkoli poizveš. Format JSONL ni podrobnost: združuje se s katerim koli analitičnim orodjem brez koraka razčlenjevanja, prisotnost ID-ja zahteve pa ti omogoča, da anomalijo stroškov povežeš s specifičnim klicem.

import json
from datetime import datetime, timezone

class CostTracker:
    """Spremljanje stroškov API-ja v realnem času."""

    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"
        )

Preverjaj na obeh koncih

Zanesljiva aplikacija ne zaupa niti temu, kar gre noter, niti temu, kar pride ven. Pri vhodu zavrzni prazna sporočila, omeji dolžino na 10.000 znakov, da preprečiš, da bi nesrečno kopiranje-lepljenje napihnilo tvoj račun, in odstrani nadzorne znake, ki motijo tokenizacijo. Pri izhodu ne zavračaj ničesar, ampak sproži opozorila: potencialno obrezan odgovor, nenormalno kratek odgovor pod petimi znaki, nenormalno dolg odgovor nad 50.000. Ti trije signali zajamejo veliko večino tihih napak.

def validate_input(user_message: str) -> str:
    """Preveri in očisti uporabniški vnos."""
    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)")

    # Očisti nadzorne znake
    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:
    """Preveri izhod API-ja."""
    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}

Obvladuj okno konteksta

Še zadnja težava: počasen drs dolgih pogovorov. Spodnja funkcija oceni volumen na en žeton na štiri znake v francoščini – groba ocena, a zadostna kot varovalka – in dovoli zahteve, dokler ostanejo pod 80 % omejitve. Onkraj tega ohrani sistemski poziv in odstrani najstarejša sporočila, dokler ne padejo nazaj pod 70 %. Ta razmik med obema pragovoma je nameren: če bi rezali le do sprožilnega praga, bi funkcija ob naslednjem sporočilu spet drsela v rdeče.

def manage_context(messages: list, max_tokens: int = 100_000) -> list:
    """Ohrani sporočila znotraj omejitve žetonov modela."""
    # Ocena: 1 žeton ~ 4 znake v francoščini
    total_chars = sum(len(m["content"]) for m in messages)
    estimated_tokens = total_chars // 4

    if estimated_tokens < max_tokens * 0.8:
        return messages  # Vse se prilega

    # Ohrani sistem + prvo in zadnje sporočilo
    system = [m for m in messages if m["role"] == "system"]
    history = [m for m in messages if m["role"] != "system"]

    # Odstrani najstarejša sporočila
    while estimated_tokens > max_tokens * 0.7 and len(history) > 2:
        removed = history.pop(0)
        estimated_tokens -= len(removed["content"]) // 4

    return system + history

Kaj odnašaš s tega tečaja

Pot je sledila štirim korakom. Najprej osnove: končna točka, vloge, osnovni parametri in struktura odgovora. Nato pretakanje (streaming) s protokolom SSE, njegovo implementacijo v Pythonu, zaporedji za ustavitev in utrditvijo prek safe_prompt in varoval. Oblikovanje pozivov je zavzelo tretjo fazo – proizvodni sistemski pozivi, nekaj primerov (few-shot), strukturiranje z XML in Markdownom, slabe prakse. Napredni parametri so zaključili krog: temperatura in Top P v podrobnostih, kazni za prisotnost in pogostost, N zaključkov in ta proizvodni kontrolni seznam.

Spodnja konfiguracija povzema te izbire v zagonsko točko, ki jo je mogoče braniti za prvo uvedbo v proizvodnjo: fiksna različica, zgornja meja žetonov, prilagojena primeru uporabe, nizka temperatura za dejansko doslednost, top_p nespremenjen, saj je temperatura prilagojena, nevtralne kazni, razen če specifična potreba upravičuje drugače, in omogočen safe_prompt.

# Tipična konfiguracija za proizvodno aplikacijo
PRODUCTION_CONFIG = {
    "model": "mistral-large-2512",      # Fiksna različica
    "max_tokens": 2000,                  # Prilagojeno primeru uporabe
    "temperature": 0.3,                  # Dosledno in dejansko
    "top_p": 1.0,                        # Nespremenjeno, če je temperatura prilagojena
    "presence_penalty": 0.0,             # Privzeto, razen če je specifična potreba
    "frequency_penalty": 0.0,            # Privzeto, razen če je specifična potreba
    "safe_prompt": True,                 # Varnost omogočena
}

Če želiš iti dlje z API-jem Mistral, na Corsen Academy sledijo štirje dopolnilni tečaji:

  • Vdelave in RAG – Semantično iskanje z mistral-embed in vektorskimi bazami podatkov
  • Klicanje funkcij – Poveži model s svojimi orodji in zunanjimi API-ji
  • Nadrojeno uglaševanje (Fine-tuning) – Prilagodi model svojemu specifičnemu področju
  • Proizvodnja in evalvacija – Metrike, avtomatizirane evalvacije, optimizacija stroškov

Ključne ugotovitve

  • V proizvodnji uporabi različice modelov, nikoli -latest
  • Od prve uvedbe implementiraj ponovne poskuse + eksponentni zamik + beleženje
  • Preveri vhode IN izhode vsakega klica API-ja
  • Stroške spremljaj v realnem času s sledilnikom žetonov
  • Obvladuj okno konteksta za dolge pogovore
  • Omogoči safe_prompt kot minimalno varnostno mrežo
  • Pred vsako izdajo v proizvodnjo preizkusi svoje pozive z robnimi primeri

Preveri svoje znanje

Na končni točki chat/completions ni več skrivnosti? Preverimo.

1. Katere vloge strukturirajo seznam sporočil?

Odgovor: system (okvir), user (zahteve), assistant (odgovori modela) – celotna zgodovina se ob vsakem klicu znova začne, saj je API brez stanja.

2. Kaj najdeš v polju usage odgovora?

Odgovor: Žetone, porabljene pri vhodu in izhodu – osnova za obračun in metrika, ki jo je treba spremljati zaradi dimenzioniranja in stroškov.

3. Kako deluje pretakanje SSE?

Odgovor: Odgovor prispe kot dogodki, poslani s strežnika (Server-Sent Events), delček za delčkom: prikazuješ jih sproti in združiš, da dobiš končno sporočilo.

4. Čemu služijo zaporedja za ustavitev?

Odgovor: Da prekinejo generiranje, takoj ko se pojavi dani niz: nadzor dolžine, ustavitev pri ločilu, zagotovitev čistih formatov.

5. Temperatura, Top P, kazni: kakšna uporaba v proizvodnji?

Odgovor: Temperatura/Top P nastavita determinizem glede na nalogo; kazni za prisotnost/pogostost omejita ponavljanje – nastavitve, ki jih je treba določiti za vsak primer uporabe in dokumentirati skupaj s pozivi.

Vloge, uporaba, pretakanje, ustavitve, uglaševanje: osnove držijo – zgornje najboljše prakse za proizvodnjo jih postavijo v red.