Najbolje prakse za proizvodnju
Na ovoj stranici
Lekcija ažurirana 3. studenog 2026. na temelju OpenAI dokumentacije: parametri
temperatureitop_pprihvaćeni su samo uz napor razmišljanja (reasoning effort) vrijednostinone, dok modeli GPT-5.6 prema zadanim postavkama razmišljaju (medium). Pozivi koji postavljaju ove parametre stoga moraju specificiratireasoning={"effort": "none"}(Responses API) ilireasoning_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