Najboljše prakse za proizvodno okolje
Na tej strani
Lekcija posodobljena 3. novembra 2026 na podlagi dokumentacije OpenAI: parametra
temperatureintop_psta sprejeta le pri naporu razmišljanja (reasoning effort) vrednostinone, medtem ko modeli GPT-5.6 privzeto razmišljajo (medium). Klici, ki nastavljajo te parametre, morajo zato določitireasoning={"effort": "none"}(Responses API) alireasoning_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