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

Najboljše prakse za proizvodno okolje

Lekcija 17 od 22 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Najboljše prakse za proizvodno okolje
  2. 1. Arhitektura odjemalca
  3. 2. Upravljanje pozivov (Prompt Management)
  4. 3. Časovni odklopi in omejitve
  5. 4. Nadomestni model (Fallback)
  6. 5. Serijska obdelava
  7. 6. Testiranje in validacija
  8. 7. Kontrolni seznam za uvedbo v proizvodno okolje
  9. Ključne ugotovitve

Lekcija posodobljena 3. novembra 2026 na podlagi dokumentacije OpenAI: parametra temperature in top_p sta sprejeta le pri naporu razmišljanja (reasoning effort) vrednosti none, medtem ko modeli GPT-5.6 privzeto razmišljajo (medium). Klici, ki nastavljajo te parametre, morajo zato določiti reasoning={"effort": "none"} (Responses API) ali reasoning_effort="none" (Chat Completions). Viri: Uporaba GPT-6 · GPT-5.6 Terra.

Najboljše prakse za proizvodno okolje

Ta lekcija pokriva bistvene najboljše prakse za uvedbo aplikacije, temelječe na API-ju OpenAI, v proizvodno okolje. Razmišljaj o tem kot o svojem kontrolnem seznamu pred zagonom. Prejšnje lekcije so ti dale gradnike – obravnavo napak, omejitve hitrosti, odpornost, opazovanje in stroške. Zdaj je čas, da jih sestaviš v aplikacijo, ki jo lahko prevzame in poganja tvoj kolega brez tvoje prisotnosti.

1. Arhitektura odjemalca

Singleton s centralizirano konfiguracijo

Ustvarjanje novega odjemalca OpenAI ob vsakem klicu zapravlja osnovno HTTP povezavo, kar je še resneje, konfiguracijo razprši na več mest. Končaš s 30-sekundnim časovnim odklopom tu in privzetim tam, brez možnosti, da bi vedel, katero velja v proizvodnji. Okrasnik lru_cache zagotavlja en sam primerek, konfiguriran na enem mestu.

from openai import OpenAI
from functools import lru_cache

@lru_cache(maxsize=1)
def get_client() -> OpenAI:
    """Odjemalec singleton s proizvodno konfiguracijo."""
    return OpenAI(
        max_retries=3,
        timeout=30.0,
    )

# Povsod v svoji kodi:
client = get_client()

Spremenljivke okolja

Enako načelo velja za nastavitve, ki se razlikujejo med okolji. Ob zagonu preveri zahtevane spremenljivke: bolje je, da storitev zavrne zagon z jasnim sporočilom, kot da se zažene in odpove ob prvem klicu uporabnika. To omogoča prilagajanje modela, omejitve žetonov in temperature brez ponovne uvedbe.

import os

# OBVEZNO: nikoli ne vgrajuj ključev v kodo
REQUIRED_ENV = ["OPENAI_API_KEY"]

for var in REQUIRED_ENV:
    if not os.environ.get(var):
        raise RuntimeError(f"Manjka spremenljivka {var}")

# Konfiguracija, specifična za okolje
MODEL = os.environ.get("OPENAI_MODEL", "gpt-5.6-terra")
MAX_TOKENS = int(os.environ.get("OPENAI_MAX_TOKENS", "4096"))
TEMPERATURE = float(os.environ.get("OPENAI_TEMPERATURE", "0.7"))

2. Upravljanje pozivov (Prompt Management)

Ločevanje pozivov od kode

Poziv je poslovno sredstvo, prav tako kot poslovno pravilo. Če ga zakoplješ v niz f-string znotraj funkcije, onemogočiš pregled osebi, ki pozna posel, a ne Pythona. Izoliraj ga kot parametrizirano predlogo: funkcija se nato zreducira na formatiranje in klic, temperatura 0.0 pa poskrbi za ponovljivost klasifikacije.

# prompts/classification.txt
PROMPT_CLASSIFICATION = """You are a text classifier.
Classify the following text into one of these categories:
{categories}

Text: {texte}

Reply only with the category name."""

def classifier(texte: str, categories: list[str]) -> str:
    prompt = PROMPT_CLASSIFICATION.format(
        categories=", ".join(categories),
        texte=texte
    )
    response = get_client().responses.create(
        model=MODEL,
        reasoning={"effort": "none"},  # temperatura zahteva napor none
        input=prompt,
        temperature=0.0
    )
    return response.output_text.strip()

različičenje pozivov

Sprememba poziva spremeni obnašanje sistema enako zanesljivo kot sprememba kode, vendar brez opozorila enotnega testa. Hrani zaporedne različice in aktivno izberi prek konfiguracije. To ti omogoča primerjavo dveh formulacij na realnem prometu in povrnitev na prejšnjo različico s spremenljivko okolja, če nova poslabša rezultate.

PROMPTS = {
    "classification_v1": "Classify: {texte}",
    "classification_v2": "Analyze and classify precisely: {texte}",
}

# V proizvodnji uporabi določeno različico
ACTIVE_PROMPT = os.environ.get("PROMPT_VERSION", "classification_v2")

3. Časovni odklopi in omejitve

Omeji vsak vhod od zunaj, preden doseže API. Uporabnik, ki prilepi 200-stranski PDF v tvoje vnosno polje, ne sme sprožiti klica, vrednega več dolarjev, ali povzročiti neuspeha zahteve zaradi preobremenitve konteksta. Preventivno obrezovanje v kombinaciji z omejitvijo izhoda in temperaturo iz konfiguracije naredi stroške in zakasnitev vsakega klica predvidljiva.

def appel_avec_garde_fous(prompt: str) -> str:
    """Klic API-ja z vsemi varovali."""
    # Omeji velikost poziva
    MAX_PROMPT_CHARS = 50000
    if len(prompt) > MAX_PROMPT_CHARS:
        prompt = prompt[:MAX_PROMPT_CHARS]
        print(f"Poziv obrezan na {MAX_PROMPT_CHARS} znakov")

    response = get_client().responses.create(
        model=MODEL,
        reasoning={"effort": "none"},  # temperatura zahteva napor none
        input=prompt,
        max_output_tokens=MAX_TOKENS,
        temperature=TEMPERATURE,
    )

    return response.output_text

4. Nadomestni model (Fallback)

Ko je model zasičen ali začasno nedostopen, vračanje napake ni tvoja edina možnost. Preklop na sekundarni model poslabša kakovost, a ohrani storitev – kompromis, ki je pogosto preferablezen za asistenta za podporo, manj pa za analizo pogodb. Zanka iterira skozi modele po vrstnem redu preferenc in sproži izjemo le, če vsi odpovejo.

from openai import RateLimitError, InternalServerError

def appel_avec_fallback(prompt: str) -> str:
    """Poskusi Terra, nato ob napaki preklopi na Luna."""
    modeles = ["gpt-5.6-terra", "gpt-5.6-luna"]

    for modele in modeles:
        try:
            response = get_client().responses.create(
                model=modele,
                input=prompt
            )
            return response.output_text
        except (RateLimitError, InternalServerError) as e:
            print(f"{modele} ni na voljo: {e}")
            continue

    raise RuntimeError("Vsi modeli so nedostopni")

5. Serijska obdelava

Za obdelavo tisoč dokumentov so zaporedni klici prepočasni, sočasni klici pa razstrelijo tvoje omejitve hitrosti. Semafor doseže pravo ravnovesje. Dve podrobnosti naredita to izvedbo robustno: return_exceptions=True prepreči, da bi ena sama napaka preklicala celotno serijo, razvrščanje po indeksu pa obnovi prvotni vrstni red, česar asyncio.gather med izvajanjem ne zagotavlja.

import asyncio
from openai import AsyncOpenAI

async def traiter_batch(prompts: list[str], max_concurrent: int = 5) -> list:
    """Obdela serijo pozivov z omejeno sočasnostjo."""
    client = AsyncOpenAI()
    semaphore = asyncio.Semaphore(max_concurrent)
    resultats = []

    async def traiter_un(index: int, prompt: str):
        async with semaphore:
            response = await client.responses.create(
                model="gpt-5.6-terra",
                input=prompt
            )
            return index, response.output_text

    tasks = [traiter_un(i, p) for i, p in enumerate(prompts)]
    results = await asyncio.gather(*tasks, return_exceptions=True)

    # Razvrsti po indeksu za ohranitev vrstnega reda
    sorted_results = sorted(
        [(idx, res) for idx, res in results if not isinstance(res, Exception)],
        key=lambda x: x[0]
    )
    return [res for _, res in sorted_results]

# prompts = ["Question 1", "Question 2", "Question 3"]
# résultats = asyncio.run(traiter_batch(prompts))

6. Testiranje in validacija

Potrebuješ dve različni vrsti testov. Prvi preveri infrastrukturo – ključ deluje, omrežje prehaja, model odgovarja – in se dobro prilega zdravstvenemu preverjanju ob zagonu. Drugi, bolj izviren, testira kakovost samega poziva: predložiš primer, kjer poznaš pravilen odgovor, in preveriš, ali se ta pojavi. Te trditve so tvoja varnostna mreža pred regresijami, ko preoblikuješ predlogo.

def test_api_disponible():
    """Preveri, ali je API dostopen."""
    try:
        response = get_client().responses.create(
            model="gpt-5.6-terra",
            input="test",
            max_output_tokens=5
        )
        assert response.output_text is not None
        print("API OK")
        return True
    except Exception as e:
        print(f"API KO: {e}")
        return False

def test_prompt_quality(prompt: str, attendu: str) -> bool:
    """Preveri, ali poziv vrne dosleden rezultat."""
    response = get_client().responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperatura zahteva napor none
        input=prompt,
        temperature=0.0
    )
    resultat = response.output_text.lower()
    return attendu.lower() in resultat

# Regresijski testi pozivov
assert test_prompt_quality(
    "Classify 'excellent product': positive or negative?",
    "positive"
)

Sestavi ducat takšnih testnih primerov, reprezentativnih za tvoje realne primere uporabe, in jih zaženi vsakič, ko spremeniš poziv. Desetminutni testni niz ti bo prihranil tedne dvomov o zaznani kakovosti.

7. Kontrolni seznam za uvedbo v proizvodno okolje

Pred uvedbo preveri vsako točko:

Infrastruktura

  • Konfigurirane spremenljivke okolja (OPENAI_API_KEY itd.)
  • Konfigurirani časovni odklopi in max_retries
  • Vzpostavljeno strukturirano beleženje
  • Omogočeno spremljanje stroškov

Odpornost

  • Popolna obravnava napak (vse HTTP kode)
  • Eksponentno nazadovanje pri ponovnih poskusih
  • Odklopnik tokokroga za dolgotrajne izpade
  • Nadomestni model (fallback) na alternativni model

Varnost

  • Ključ API nikoli ni izpostavljen v kodi ali dnevnikih
  • Validacija uporabniškega vnosa
  • Omejevanje hitrosti na strani odjemalca
  • V pozivih ni občutljivih podatkov

Zmogljivost

  • Omogočeno pretakanje (streaming) za uporabniške vmesnike
  • Serijska obdelava za naloge z veliko obsega
  • Predpomnenje za ponavljajoče se zahteve
  • Izbira modela prilagojena vsaki nalogi

Stroški

  • Opredeljen dnevni proračun
  • Konfigurirana opozorila
  • Nastavljeno max_output_tokens, kjer je mogoče
  • Za vsako nalogo izbran najbolj stroškovno učinkovit model

Ključne ugotovitve

  • Centraliziraj konfiguracijo odjemalca s singletom
  • Loči pozive od kode in jih različiči
  • Implementiraj nadomestni model za visoko razpoložljivost
  • Uporabi serijsko obdelavo z omejeno sočasnostjo za velike količine
  • Testiraj svoje pozive s trditvami o kakovosti
  • Pred vsako uvedbo v proizvodno okolje sledi popolnemu kontrolnemu seznamu