Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Gyakorlati bevált módszerek éles környezetben

16. lecke 16 közül Frissítve 2026. november 2. Fejlesztő
Ezen az oldalon
  1. A koncepcióbizonyítéktól az élesítésig
  2. Hitelesítés és modellverzió-kezelés
  3. Egy incidenseket kezelő kliens
  4. Költségek nyomon követése valós időben
  5. Ellenőrzés mindkét végponton
  6. A kontextusablak kordában tartása
  7. Amit ebből a kurzusból magaddal viszel
  8. Főbb megállapítások
  9. Teszteld a tudásod!

A koncepcióbizonyítéktól az élesítésig

Mostanra már a Chat Completions API minden paraméterét ismered. A legnehezebb rész még hátravan: hogyan hidalod át a szakadékot egy működő jegyzetfüzet és egy olyan szolgáltatás között, amelyet mások a te közbeavatkozásod nélkül használnak. Ez az utolsó lecke a teljes tananyagot egy cselekvőképes élesítési ellenőrzőlistába sűríti, majd utat mutat a folytatáshoz szükséges további kurzusok felé.

Hitelesítés és modellverzió-kezelés

Két döntést kell meghoznod még az üzleti logika első sora előtt. Az első az API-kulcsra vonatkozik: ez egy környezeti változóban él, soha nem a kódban, és egy indítási ellenőrzés (assertion) sokkal jobb, mint egy None érték, amely három réteggel lejjebb terjed, és egy érthetetlen hibaüzenetet eredményez. Tervezd meg a kulcscserét is: ha el akarod kerülni a szolgáltatás leállását, akkor ebben a sorrendben járd el: hozd létre az új kulcsot, telepítsd, majd vond vissza a régit.

import os

# MINDIG: API-kulcs környezeti változóban
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY not defined"

# SOHA: kódba égetett kulcs
# api_key = "sk-abc123..."  # ÉLES KÖRNYEZETBEN TILOS

# MINDIG: rendszeres kulcscsere
# Hozz létre egy új kulcsot, telepítsd, majd vond vissza a régit

A második döntés a modellazonosítóra vonatkozik. Fejlesztés közben a -latest végződés erőfeszítés nélkül biztosítja a fejlesztéseket. Éles környezetben azonban ugyanez az alias azt jelenti, hogy a szolgáltató oldali verzióváltás figyelmeztetés nélkül megváltoztathatja az alkalmazásod viselkedését – akár egy keddi reggelen, commit napló nélkül, ami magyarázatot adna rá. Rögzítsd a verziót!

# FEJLESZTÉS — legfrissebb verzió
model = "mistral-large-latest"

# ÉLES KÖRNYEZET — rögzített verzió a reprodukálhatóság érdekében
model = "mistral-large-2512"

# Miért? A "latest" változás figyelmeztetés nélkül
# megváltoztathatja az alkalmazásod viselkedését.

Egy incidenseket kezelő kliens

Egy éles integráció szíve nem maga az API-hívás, hanem minden, ami körülveszi azt. Az alábbi osztály három felelősséget egyesít egyetlen szűk keresztmetszetben: exponenciális visszalépéssel (exponential backoff) történő újrapróbálkozás 429-es hibák esetén, rövid szüneteltetés szerverhibáknál, valamint a kliensoldali hibák azonnali továbbítása, amelyeken az újrapróbálkozás sem segít. Emellett stabil szótárba normalizálja a választ – tartalom, finish_reason, felhasználás, modell, ID –, így a kód többi része nem függ többé az SDK által visszaadott objektum pontos szerkezetétől. Önmagában a csonkításokról szóló logger.warning hívások is igazolják ezt a kapszulázást: ez az egyetlen módja annak, hogy felfedezd, ha a max_tokens beállítás túl szoros, mielőtt a felhasználók jelentenék a problémát.

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

logger = logging.getLogger(__name__)

class MistralClient:
    """Éles környezeti kliens újrapróbálkozással, időtúllépéssel és naplózással."""

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

                # Riasztás, ha a válasz csonkított
                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")

Költségek nyomon követése valós időben

Az, hogy csak a havi számlán fedezed fel a fogyasztásodat, olyan luxus, amit kevés csapat engedhet meg magának. Az alábbi követő minden hívásról egy JSONL sort ír: időbélyegző, modell, bemeneti és kimeneti tokenek, finish_reason, kérés ID – és fenntart egy munkamenet-összesítőt, amelyet bármikor lekérdezhetsz. A JSONL formátum nem apróság: elemzőeszközökkel további parsing lépés nélkül aggregálható, a kérés ID jelenléte pedig lehetővé teszi, hogy egy költségrendellenességet egy konkrét híváshoz köss.

import json
from datetime import datetime, timezone

class CostTracker:
    """Valós idejű API-költségkövetés."""

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

Ellenőrzés mindkét végponton

Egy robusztus alkalmazás nem bízik sem abban, ami bemegy, sem abban, ami kijön. Bemenetnél utasítsd el az üres üzeneteket, korlátozd a hosszat 10 000 karakterre, hogy megakadályozd, hogy egy szerencsétlen másolás-beillesztés felfújja a számládat, és távolítsd el azokat a vezérlőkaraktereket, amelyek megzavarják a tokenizálást. Kimenetnél ne utasíts el semmit, de emelj figyelmeztetéseket: potenciálisan csonkított válasz, rendellenesen rövid válasz (5 karakter alatt), rendellenesen hosszú válasz (50 000 felett). Ez a három jelzés a hallgatólagos hibák túlnyomó többségét elcsípi.

def validate_input(user_message: str) -> str:
    """Felhasználói bemenet ellenőrzése és tisztítása."""
    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)")

    # Vezérlőkarakterek tisztítása
    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:
    """API-kimenet ellenőrzése."""
    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}

A kontextusablak kordában tartása

Egy utolsó kérdés: a hosszú beszélgetések lassú elcsúszása. Az alábbi függvény becslést végez a volumenre (franciánál durván 1 token ~ 4 karakter) – ez hozzávetőleges, de védőkorlátként elegendő –, és addig engedi át a kéréseket, amíg azok a limit 80%-a alatt maradnak. Efelett megtartja a rendszerüzenetet (system prompt), és eltávolítja a legrégebbi üzeneteket, amíg vissza nem kerül 70% alá. A két küszöbérték közötti rés szándékos: ha csak a trigger-küszöbig vágnánk vissza, a következő üzenetnél a függvény ismét a vörös zónába kerülne.

def manage_context(messages: list, max_tokens: int = 100_000) -> list:
    """Üzenetek a modell tokenlimitjén belül tartása."""
    # Becslés: 1 token ~ 4 karakter franciánál
    total_chars = sum(len(m["content"]) for m in messages)
    estimated_tokens = total_chars // 4

    if estimated_tokens < max_tokens * 0.8:
        return messages  # Minden belefér

    # Rendszerüzenet + első és utolsó üzenetek megtartása
    system = [m for m in messages if m["role"] == "system"]
    history = [m for m in messages if m["role"] != "system"]

    # Legrégebbi üzenetek eltávolítása
    while estimated_tokens > max_tokens * 0.7 and len(history) > 2:
        removed = history.pop(0)
        estimated_tokens -= len(removed["content"]) // 4

    return system + history

Amit ebből a kurzusból magaddal viszel

Az út négy lépésből állt. Először az alapok: a végpont, szerepek, alapvető paraméterek és a válasz szerkezete. Ezt követte a streamelés, az SSE protokollal, annak Python megvalósításával, leállítási szekvenciákkal, valamint a safe_prompt és védőkorlátok révén történő megerősítéssel. A harmadik fázist a promptolás töltötte ki: éles rendszerüzenetek, few-shot példák, XML és Markdown strukturálás, anti-patternek. A kört a haladó paraméterek zárták le: hőmérséklet és Top P részletesen, jelenléti és gyakorisági büntetések, N számú kiegészítés, valamint ez az élesítési ellenőrzőlista.

Az alábbi konfiguráció ezeket a döntéseket sűríti össze egy védhető kiindulóponttá az első éles telepítéshez: rögzített verzió, az esethez igazított tokenplafon, alacsony hőmérséklet a ténybeli konzisztencia érdekében, érintetlen top_p (mivel a hőmérsékletet állítjuk), semleges büntetések, hacsak nincs konkrét igény rájuk, és engedélyezett safe_prompt.

# Tipikus konfiguráció éles környezeti alkalmazáshoz
PRODUCTION_CONFIG = {
    "model": "mistral-large-2512",      # Rögzített verzió
    "max_tokens": 2000,                  # Az esethez igazítva
    "temperature": 0.3,                  # Konzisztens és tényalapú
    "top_p": 1.0,                        # Érintetlen, ha a hőmérsékletet állítjuk
    "presence_penalty": 0.0,             # Alapértelmezett, hacsak nincs konkrét igény
    "frequency_penalty": 0.0,            # Alapértelmezett, hacsak nincs konkrét igény
    "safe_prompt": True,                 # Biztonság engedélyezve
}

Ha mélyebben szeretnél elmerülni a Mistral API világában, a Corsen Academy-n négy kiegészítő kurzus következik:

  • Beágyazások és RAG – Szemantikus keresés a mistral-embed modellel és vektoradatbázisokkal
  • Függvényhívás – A modell összekötése saját eszközeiddel és külső API-kkal
  • Finomhangolás – Modell adaptálása specifikus domainhez
  • Élesítés és Értékelés – Metrikák, automatizált értékelések, költséghatékonyság optimalizálása

Főbb megállapítások

  • Éles környezetben mindig verziózott modelleket használj, soha ne a -latest aliaszt
  • Implementálj újrapróbálkozást, visszalépést és naplózást már az első telepítéskor
  • Ellenőrizd minden API-hívás bemenetét ÉS kimenetét
  • Kövesd nyomon a költségeket valós időben egy tokenkövetővel
  • Kezeld a kontextusablakot hosszú beszélgetések esetén
  • Engedélyezd a safe_prompt opciót minimális biztonsági hálóként
  • Minden élesítés előtt teszteld a promptjaidat szélsőséges esetekkel

Teszteld a tudásod!

Nincsenek már titkaid a chat/completions végpont előtt? Győződjünk meg róla.

1. Mely szerepek strukturálják az üzenetlistát?

Válasz: system (a keret), user (kérések), assistant (modellválaszok) – a teljes történet minden hívással újraindul, mivel az API állapot nélküli.

2. Mit találsz a válasz usage mezőjében?

Válasz: A bemeneten és kimeneten elfogyasztott tokeneket – ez a számlázás alapja és az a metrika, amelyet a méretezés és a költségek miatt figyelni kell.

3. Hogyan működik az SSE streamelés?

Válasz: A válasz Server-Sent Events formájában érkezik, töredékről töredékre: megjeleníted, ahogy jön, majd összefűzöd a végső üzenet eldekezéséhez.

4. Mire valók a leállítási szekvenciák (stop sequences)?

Válasz: Arra, hogy a generálást azonnal leállítsák, amint egy adott karakterlánc megjelenik: hossz szabályozása, leállítás elválasztónál, tiszta formátumok garantálása.

5. Hőmérséklet, Top P, büntetések: milyen használat éles környezetben?

Válasz: A hőmérséklet/Top P feladatfüggő determinizmust állít be; a jelenléti/gyakorisági büntetések korlátozzák az ismétlést – ezeket az értékeket használati esetenként rögzíteni kell, és dokumentálni a promptok mellett.

Szerepek, felhasználás, streamelés, leállítások, hangolás: az alapok állnak – a fenti élesítési bevált módszerek pedig rendet tesznek közöttük.