Osvedčené postupy pre nasadenie do produkcie
Na tejto strane
Lekcia aktualizovaná 3. novembra 2026 na základe dokumentácie OpenAI: parametre
temperatureatop_psú akceptované len pri úsilí o logické uvažovanie (reasoning effort) nastavenom nanone, zatiaľ čo modely GPT-5.6 štandardne uvažujú (medium). Volania, ktoré nastavujú tieto parametre, preto musia špecifikovaťreasoning={"effort": "none"}(Responses API) aleboreasoning_effort="none"(Chat Completions). Zdroje: Using GPT-6 · GPT-5.6 Terra.
Osvedčené postupy pre nasadenie do produkcie
Táto lekcia pokrýva kľúčové osvedčené postupy pre nasadenie aplikácie využívajúcej OpenAI API do produkčného prostredia. Ber to ako svoj kontrolný zoznam pred spustením. Predchádzajúce lekcie ti poskytli stavebné kamene – spracovanie chýb, limity rýchlosti, odolnosť, pozorovateľnosť a náklady. Teraz je čas poskladať ich do aplikácie, ktorú môže prevziať a prevádzkovať tvoj kolega aj bez tvojej prítomnosti.
1. Architektúra klienta
Singleton s centralizovanou konfiguráciou
Vytváranie inštancie klienta OpenAI pri každom volaní plytvá základným HTTP pripojením a, čo je vážnejšie, roztriešti tvoju konfiguráciu. Nakoniec máš tu 30-sekundový časový limit a tam predvolenú hodnotu, bez možnosti zistiť, ktorá sa v produkcii skutočne použije. Dekorátor lru_cache zaručí jedinú inštanciu nakonfigurovanú na jednom mieste.
from openai import OpenAI
from functools import lru_cache
@lru_cache(maxsize=1)
def get_client() -> OpenAI:
"""Singleton klient s produkčnou konfiguráciou."""
return OpenAI(
max_retries=3,
timeout=30.0,
)
# Všade vo svojom kóde:
client = get_client()
Premenné prostredia
Rovnaký princíp platí pre nastavenia, ktoré sa líšia medzi prostrediami. Skontroluj požadované premenné pri štarte: je lepšie, ak služba odmietne štartovať s jasnou správou, než aby štartovala a zlyhala pri prvom volaní používateľa. To umožňuje upravovať model, limit tokenov a teplotu bez opätovného nasadenia.
import os
# POVINNÉ: nikdy neukladaj kľúče natvrdo
REQUIRED_ENV = ["OPENAI_API_KEY"]
for var in REQUIRED_ENV:
if not os.environ.get(var):
raise RuntimeError(f"Chýbajúca premenná {var}")
# Konfigurácia špecifická pre prostredie
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. Správa promptov
Oddeľ prompty od kódu
Prompt je obchodný majetok, rovnako ako obchodné pravidlo. Ak ho zakopeš do f-stringu vo vnútri funkcie, znemožníš jeho kontrolu niekomu, kto pozná business, ale nepozná Python. Izoluj ho ako parameterizovanú šablónu: funkcia sa potom zredukuje na formátovanie a volanie, a teplota 0,0 zabezpečí reprodukovateľnosť klasifikácie.
# 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()
Verziuj svoje prompty
Zmena promptu mení správanie systému rovnako isto ako zmena kódu, ale bez toho, aby si to všimol unit test. Uchovávaj postupné verzie a aktívnu vyberaj prostredníctvom konfigurácie. To ti umožní porovnať dve formulácie na reálnej premávke a v prípade zhoršenia výsledkov sa vrátiť k predchádzajúcej verzii pomocou premennej prostredia.
PROMPTS = {
"classification_v1": "Classify: {texte}",
"classification_v2": "Analyze and classify precisely: {texte}",
}
# V produkcii používaj konkrétnu verziu
ACTIVE_PROMPT = os.environ.get("PROMPT_VERSION", "classification_v2")
3. Časové limity a obmedzenia
Ohranič akýkoľvek vstup zvonku skôr, než sa dostane k API. Používateľ, ktorý vloží 200-stranový PDF do vstupného poľa, nesmie mať možnosť spustiť volanie za viac dolárov alebo spôsobiť zlyhanie požiadavky kvôli pretečeniu kontextu. Preventívne orezanie v kombinácii s limitom výstupu a teplotou z konfigurácie zabezpečí predvídateľnosť nákladov a latencie každého volania.
def appel_avec_garde_fous(prompt: str) -> str:
"""Volanie API so všetkými poistkami."""
# Obmedzenie veľkosti promptu
MAX_PROMPT_CHARS = 50000
if len(prompt) > MAX_PROMPT_CHARS:
prompt = prompt[:MAX_PROMPT_CHARS]
print(f"Prompt orezaný na {MAX_PROMPT_CHARS} znakov")
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. Záložný model (Fallback)
Keď je model preťažený alebo dočasne nedostupný, vrátenie chyby nie je jedinou možnosťou. Prepnutie na sekundárny model zhorší kvalitu, ale zachová službu – kompromis, ktorý je často výhodnejší pre asistenta podpory, menej však pre analýzu zmlúv. Cyklus prechádza modelmi v poradí podľa preferencie a výnimku vyhodí až v prípade, že zlyhajú všetky.
from openai import RateLimitError, InternalServerError
def appel_avec_fallback(prompt: str) -> str:
"""Skúsi Terra a v prípade chyby prejde 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} nedostupný: {e}")
continue
raise RuntimeError("Všetky modely sú nedostupné")
5. Dávkové spracovanie
Na spracovanie tisícov dokumentov sú sekvenčné volania príliš pomalé a simultánne volania nafúknu tvoje limity rýchlosti. Semafór nájde správnu rovnováhu. Dva detaily robia túto implementáciu robustnou: return_exceptions=True zabráni tomu, aby jedna chyba zrušila celú dávku, a zoradenie podľa indexu obnoví pôvodné poradie, ktoré asyncio.gather v čase vykonania nezaručuje.
import asyncio
from openai import AsyncOpenAI
async def traiter_batch(prompts: list[str], max_concurrent: int = 5) -> list:
"""Spracuje dávku promptov s obmedzenou súbežnosťou."""
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)
# Zoradenie podľa indexu na zachovanie poradia
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. Testovanie a validácia
Potrebuješ dva rôzne typy testov. Prvý kontroluje inštaláciu – kľúč funguje, sieť prechádza, model odpovedá – a hodí sa do kontrolného stavu pri štarte. Druhý, originálnejší, testuje samotnú kvalitu promptu: odošleš prípad, kde poznáš správnu odpoveď, a overíš, či sa objaví. Tieto tvrdenia sú tvojou bezpečnostnou sieťou proti regresii pri preformulovaní šablóny.
def test_api_disponible():
"""Overí dostupnosť API."""
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:
"""Overí, či prompt vracia konzistentný výsledok."""
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
# Testy regresie promptov
assert test_prompt_quality(
"Classify 'excellent product': positive or negative?",
"positive"
)
Vytvor tucet takýchto testovacích prípadov reprezentujúcich tvoje reálne použitie a spúšťaj ich vždy, keď upravíš prompt. Desaťminútová sada testov ti ušetrí týždne pochybností o vnímanej kvalite.
7. Kontrolný zoznam nasadenia do produkcie
Pred nasadením over každú položku:
Infraštruktúra
- Nakonfigurované premenné prostredia (OPENAI_API_KEY atď.)
- Nastavené časové limity a max_retries
- Zavedené štruktúrované logovanie
- Povolené monitorovanie nákladov
Odolnosť
- Kompletné spracovanie chýb (všetky HTTP kódy)
- Exponenciálne oneskorenie pri opakovaných pokusoch
- Istič (circuit breaker) pri dlhších výpadkoch
- Záložný prechod na alternatívny model
Bezpečnosť
- API kľúč nikdy neodhalený v kóde ani logoch
- Validácia vstupov od používateľov
- Obmedzenie rýchlosti na strane klienta
- Žiadne citlivé údaje v promptoch
Výkon
- Povolené streamovanie pre používateľské rozhrania
- Dávkové spracovanie pre úlohy s vysokým objemom
- Cachovanie pre opakujúce sa požiadavky
- Výber modelu prispôsobený každej úlohe
Náklady
- Definovaný denný rozpočet
- Nakonfigurované alerty
- Nastavené max_output_tokens tam, kde je to možné
- Výber najvýhodnejšieho modelu pre každú úlohu
Kľúčové poznatky
- Centralizuj konfiguráciu klienta pomocou singletonu
- Oddeľ a verziuj svoje prompty mimo kód
- Implementuj záložný model pre vysokú dostupnosť
- Používaj dávkové spracovanie s obmedzenou súbežnosťou pre veľké objemy
- Testuj svoje prompty pomocou kontrol kvality
- Pred každým nasadením do produkcie dodržuj kompletný kontrolný zoznam