Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Najbolje prakse za proizvodnju

Lekcija 17 od 22 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Najbolje prakse za proizvodnju
  2. 1. Arhitektura klijenta
  3. 2. Upravljanje promptovima
  4. 3. Vremenska ograničenja i limiti
  5. 4. Model Fallback (Rezervni model)
  6. 5. Grupna obrada (Batch Processing)
  7. 6. Testiranje i validacija
  8. 7. Popis provjere za uvođenje u proizvodnju
  9. Ključne točke

Lekcija ažurirana 3. studenog 2026. na temelju OpenAI dokumentacije: parametri temperature i top_p prihvaćeni su samo uz napor razmišljanja (reasoning effort) vrijednosti none, dok modeli GPT-5.6 prema zadanim postavkama razmišljaju (medium). Pozivi koji postavljaju ove parametre stoga moraju specificirati reasoning={"effort": "none"} (Responses API) ili reasoning_effort="none" (Chat Completions). Izvori: Korištenje GPT-6 · GPT-5.6 Terra.

Najbolje prakse za proizvodnju

Ova lekcija pokriva ključne najbolje prakse za uvođenje aplikacije temeljene na OpenAI API-ju u proizvodno okruženje. Promatraj ovo kao svoj popis provjere prije lansiranja. Prethodne lekcije dale su ti gradivne blokove—rukovanje greškama, ograničenja stope, otpornost, opservabilnost i troškove. Sada je vrijeme da ih sastaviš u aplikaciju koju kolega može preuzeti i pokrenuti bez tvoje prisutnosti.

1. Arhitektura klijenta

Singleton s centraliziranom konfiguracijom

Instanciranje OpenAI klijenta pri svakom pozivu troši osnovnu HTTP vezu i, što je ozbiljnije, raspršuje tvoju konfiguraciju. Završiš s vremenskim istekom od 30 sekundi ovdje i zadanim postavkama ondje, bez načina da znaš koja se primjenjuje u proizvodnji. Dekorator lru_cache jamči jednu instancu, konfiguriranu na jednom mjestu.

from openai import OpenAI
from functools import lru_cache

@lru_cache(maxsize=1)
def get_client() -> OpenAI:
    """Singleton klijent s proizvodnom konfiguracijom."""
    return OpenAI(
        max_retries=3,
        timeout=30.0,
    )

# Svugdje u tvom kodu:
client = get_client()

Varijable okruženja

Isto načelo vrijedi za postavke koje se razlikuju između okruženja. Provjeri potrebne varijable pri pokretanju: bolje je da servis odbije pokretanje s jasnom porukom nego da se pokrene i zakaže pri prvom korisničkom pozivu. To omogućuje prilagodbu modela, ograničenja tokena i temperature bez ponovnog uvođenja.

import os

# OBAVEZNO: nikada ne hardkodiraj ključeve
REQUIRED_ENV = ["OPENAI_API_KEY"]

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

# Konfiguracija specifična za okruženje
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 promptovima

Odvoji promptove od koda

Prompt je poslovno sredstvo, baš kao i poslovno pravilo. Zakopavanje u f-string unutar funkcije onemogućuje nekome tko poznaje poslovanje, ali ne i Python, da ga pregleda. Izoliraj ga kao parametrizirani predložak: funkcija se tada svodi na formatiranje i poziv, a temperatura od 0.0 čini klasifikaciju reproducibilnom.

# 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"},  # temperature requires effort none
        input=prompt,
        temperature=0.0
    )
    return response.output_text.strip()

Verzioniraj svoje promptove

Promjena prompta mijenja ponašanje sustava jednako sigurno kao i promjena koda, ali bez da to ijedan jedinični test primijeti. Čuvaj uzastopne verzije i odaberi aktivnu putem konfiguracije. To ti omogućuje usporedbu dviju formulacija na stvarnom prometu i povratak na prethodnu pomoću varijable okruženja ako nova pogorša rezultate.

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

# U proizvodnji koristi specifičnu verziju
ACTIVE_PROMPT = os.environ.get("PROMPT_VERSION", "classification_v2")

3. Vremenska ograničenja i limiti

Ograniči svaki ulaz izvana prije nego što stigne do API-ja. Korisnik koji zalijepi PDF od 200 stranica u tvoje polje za unos ne smije moći pokrenuti poziv vrijedan nekoliko dolara ili uzrokovati neuspjeh zahtjeva zbog prelaska konteksta. Preventivno skraćivanje, u kombinaciji s ograničenjem izlaza i temperaturom iz konfiguracije, čini trošak i kašnjenje svakog poziva predvidljivima.

def appel_avec_garde_fous(prompt: str) -> str:
    """API poziv sa svim zaštitnim mjerama."""
    # Ograniči veličinu prompta
    MAX_PROMPT_CHARS = 50000
    if len(prompt) > MAX_PROMPT_CHARS:
        prompt = prompt[:MAX_PROMPT_CHARS]
        print(f"Prompt truncated to {MAX_PROMPT_CHARS} characters")

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

    return response.output_text

4. Model Fallback (Rezervni model)

Kada je model zasićen ili privremeno nedostupan, vraćanje greške nije tvoja jedina opcija. Prebacivanje na sekundarni model smanjuje kvalitetu, ali održava uslugu—kompromis koji je često poželjniji za asistenta za podršku, a manje za analizu ugovora. Petlja iterira kroz modele po redoslijedu preferencije i podiže iznimku samo ako svi zakažu.

from openai import RateLimitError, InternalServerError

def appel_avec_fallback(prompt: str) -> str:
    """Pokušava Terra, a zatim prelazi na Luna u slučaju greške."""
    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} unavailable: {e}")
            continue

    raise RuntimeError("All models are unavailable")

5. Grupna obrada (Batch Processing)

Za obradu tisuću dokumenata, sekvencijalni pozivi su prespori, a istodobni pozivi ruše tvoja ograničenja stope. Semaforski mehanizam postiže pravu ravnotežu. Dva detalja čine ovu implementaciju robustnom: return_exceptions=True sprječava da jedan neuspjeh otkaže cijelu seriju, a sortiranje po indeksu vraća izvorni redoslijed, što asyncio.gather ne jamči u vremenu izvršenja.

import asyncio
from openai import AsyncOpenAI

async def traiter_batch(prompts: list[str], max_concurrent: int = 5) -> list:
    """Obrađuje seriju promptova s ograničenom konkurentnošću."""
    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)

    # Sortiraj po indeksu za održavanje redoslijeda
    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 i validacija

Trebaš dvije različite vrste testova. Prvi provjerava infrastrukturu—ključ radi, mreža prolazi, model odgovara—i dobro se uklapa u zdravstvenu provjeru pri pokretanju. Drugi, originalniji, testira samu kvalitetu prompta: šalješ slučaj za koji znaš točan odgovor i provjeravaš pojavljuje li se. Te tvrdnje su tvoja sigurnosna mreža protiv regresija kada preformuliraš predložak.

def test_api_disponible():
    """Provjerava je li API dostupan."""
    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:
    """Provjerava vraća li prompt dosljedan rezultat."""
    response = get_client().responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature requires effort none
        input=prompt,
        temperature=0.0
    )
    resultat = response.output_text.lower()
    return attendu.lower() in resultat

# Testovi regresije promptova
assert test_prompt_quality(
    "Classify 'excellent product': positive or negative?",
    "positive"
)

Izgradi desetak ovakvih testnih slučajeva, reprezentativnih za tvoje stvarne slučajeve upotrebe, i pokreći ih svaki put kada modificiraš prompt. Desetominutni testni set uštedjet će ti tjedne sumnje u percipiranu kvalitetu.

7. Popis provjere za uvođenje u proizvodnju

Prije uvođenja, provjeri svaku točku:

Infrastruktura

  • Konfigurirane varijable okruženja (OPENAI_API_KEY, itd.)
  • Konfigurirana vremenska ograničenja i max_retries
  • Postavljeno strukturirano bilježenje (logging)
  • Omogućeno praćenje troškova

Otpornost

  • Potpuno rukovanje greškama (svi HTTP kodovi)
  • Eksponencijalno povlačenje (backoff) za ponovne pokušaje
  • Osigurač (circuit breaker) za dugotrajne prekide
  • Prelazak na alternativni model

Sigurnost

  • API ključ nikada nije izložen u kodu ili zapisnicima
  • Validacija korisničkog unosa
  • Ograničenje stope na strani klijenta
  • Nema osjetljivih podataka u promptovima

Performanse

  • Omogućeno strujanje (streaming) za korisnička sučelja
  • Grupna obrada za zadatke velikog obujma
  • Predmemoriranje za ponavljajuće zahtjeve
  • Izbor modela prilagođen svakom zadatku

Troškovi

  • Definiran dnevni proračun
  • Konfigurirana upozorenja
  • Postavljen max_output_tokens gdje je moguće
  • Odabran najisplativiji model po zadatku

Ključne točke

  • Centraliziraj konfiguraciju klijenta pomoću singletona
  • Odvoji i verzioniraj svoje promptove izvan koda
  • Implementiraj rezervni model za visoku dostupnost
  • Koristi grupnu obradu s ograničenom konkurentnošću za velike obujme
  • Testiraj svoje promptove s tvrdnjama o kvaliteti
  • Slijedi potpuni popis provjere prije svakog uvođenja u proizvodnju