Geriausios gamybos praktikos
Šiame puslapyje
Pamoka atnaujinta 2026 m. lapkričio 3 d. pagal „OpenAI“ dokumentaciją: parametrai
temperatureirtop_ppriimami tik esantnonelygio samprotavimui, tuo tarpu GPT-5.6 modeliai pagal nutylėjimą samprotauja (medium). Todėl kvietimuose, kuriuose nustatomi šie parametrai, būtina nurodytireasoning={"effort": "none"}(Responses API) arbareasoning_effort="none"(Chat Completions). Šaltiniai: Using GPT-6 · GPT-5.6 Terra.
Geriausios gamybos praktikos
Šioje pamokoje aptariamos pagrindinės geriausios praktikos diegiant „OpenAI“ API pagrindu sukurtą programą į gamybinę aplinką. Laikyk tai savo prieš paleidimą sudaromu kontroliniu sąrašu. Ankstesnėse pamokose gavai statybinius blokus – klaidų apdorojimą, ribojimus, atsparumą, stebėseną ir kaštus. Dabar metas juos sujungti į programą, kurią kolega galėtų perimti ir valdyti be tavęs pagalbos.
1. Kliento architektūra
Vienetinis objektas su centralizuota konfigūracija
„OpenAI“ kliento kūrimas kiekvieno kvietimo metu eikvoja pagrindinį HTTP ryšį ir, kas dar svarbiau, išbarsto konfigūraciją. Galiausiai gauni 30 sekundžių laiko limitą vienoje vietoje ir numatytąjį kitur, neturėdamas būdo sužinoti, kuris galioja gamyboje. Dekoratorius lru_cache garantuoja vieną egzempliorių, sukonfigūruotą vienoje vietoje.
from openai import OpenAI
from functools import lru_cache
@lru_cache(maxsize=1)
def get_client() -> OpenAI:
"""Vienetinis klientas su gamybine konfigūracija."""
return OpenAI(
max_retries=3,
timeout=30.0,
)
# Visur savo kode:
client = get_client()
Aplinkos kintamieji
Tas pats principas taikomas nustatymams, kurie skiriasi priklausomai nuo aplinkos. Patikrink būtinus kintamuosius paleidimo metu: geriau, kad tarnyba atsisakytų startuoti su aiškiu pranešimu, nei startuotų ir sugestų atlikdama pirmąjį naudotojo kvietimą. Tai leidžia keisti modelį, žetonų limitą ir temperatūrą neperdiegiant programos.
import os
# BŪTINA: niekada nekoduok raktų tiesiogiai
REQUIRED_ENV = ["OPENAI_API_KEY"]
for var in REQUIRED_ENV:
if not os.environ.get(var):
raise RuntimeError(f"Trūksta kintamojo {var}")
# Aplinkai specifinė konfigūracija
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. Promptų valdymas
Atskirk promptus nuo kodo
Promptas yra verslo turtas, lygiai kaip ir verslo taisyklė. Jo paslėpimas f-eilutėje funkcijos viduje neleidžia žmogui, kuris išmano verslą, bet nemoka „Python“, jo peržiūrėti. Izoliuok jį kaip parametrizuotą šabloną: tuomet funkcija redukuojama iki formatavimo ir kvietimo, o 0,0 temperatūra užtikrina klasifikacijos atkuriamumą.
# 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()
Versijuok savo promptus
Prompto keitimas keičia sistemos elgseną taip pat tikrai, kaip ir kodo keitimas, tačiau jokia vienetinė testas to nepastebi. Saugok nuoseklias versijas ir pasirink aktyviąją per konfigūraciją. Tai leidžia palyginti dvi formuluotes realiu srautu ir, jei naujoji pablogina rezultatus, grįžti prie ankstesnės naudojant aplinkos kintamąjį.
PROMPTS = {
"classification_v1": "Classify: {texte}",
"classification_v2": "Analyze and classify precisely: {texte}",
}
# Gamyboje naudok specifinę versiją
ACTIVE_PROMPT = os.environ.get("PROMPT_VERSION", "classification_v2")
3. Laiko limitai ir ribos
Apribok bet kokį išorinį įvesties duomenį, prieš jam pasiekiant API. Naudotojas, įklijuojantis 200 puslapių PDF failą į tavo įvesties lauką, neturi galėti inicijuoti kelių dolerių vertės kvietimo arba sukelti užklausos nesėkmę dėl konteksto perpildymo. Prevencinis apkarpymas, kartu su išvesties limitu ir temperatūra iš konfigūracijos, daro kiekvieno kvietimo kaštus ir delsą nuspėjamus.
def appel_avec_garde_fous(prompt: str) -> str:
"""API kvietimas su visomis apsaugomis."""
# Apribok prompto dydį
MAX_PROMPT_CHARS = 50000
if len(prompt) > MAX_PROMPT_CHARS:
prompt = prompt[:MAX_PROMPT_CHARS]
print(f"Promptas apkirptas iki {MAX_PROMPT_CHARS} simbolių")
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. Modelio atsarginis variantas (Fallback)
Kai modelis yra perkrautas arba laikinai nepasiekiamas, grąžinti klaidą nėra vienintelė išeitis. Perjungimas į antrinį modelį šiek tiek sumažina kokybę, bet išsaugo tarnybą – tai kompromisas, dažnai pageidautinas pagalbos asistentui, nors mažiau tinkamas sutarčių analizei. Ciklas iteruoja modelius pagal pageidavimų eilę ir išmeta išimtį tik tada, jei visi nepavyksta.
from openai import RateLimitError, InternalServerError
def appel_avec_fallback(prompt: str) -> str:
"""Bando Terra, o klaidos atveju pereina prie 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} nepasiekiamas: {e}")
continue
raise RuntimeError("Visi modeliai nepasiekiami")
5. Grupinis apdorojimas
Apdorojant tūkstantį dokumentų, nuoseklūs kvietimai yra per lėti, o vienu metu vykdomi kvietimai viršija tavo ribojimus. Semafaras pasiekia tinkamą pusiausvyrą. Du detalės daro šį įgyvendinimą patikimu: return_exceptions=True neleidžia vienai nesėkmei atšaukti viso grupinio apdorojimo, o rūšiavimas pagal indeksą atkuria pradinę tvarką, ko asyncio.gather vykdymo laiku negarantuoja.
import asyncio
from openai import AsyncOpenAI
async def traiter_batch(prompts: list[str], max_concurrent: int = 5) -> list:
"""Apdoroja promptų grupę su ribotu lygiagretumu."""
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)
# Rūšiuok pagal indeksą, kad išlaikytum tvarką
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. Testavimas ir validavimas
Tau reikia dviejų skirtingų tipų testų. Pirmasis tikrina infrastruktūrą – raktas veikia, tinklas praleidžia, modelis atsako – ir puikiai tinka paleidimo būsenos patikrai. Antrasis, originalesnis, testuoja paties prompto kokybę: pateiki atvejį, kurį žinai teisingą atsakymą, ir patikrini, ar jis atsiranda. Šie teiginiai yra tavo saugos tinklas nuo regresijų, kai perfrazuoji šabloną.
def test_api_disponible():
"""Patikrina, ar API yra pasiekiamas."""
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:
"""Patikrina, ar promptas grąžina nuoseklų 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
# Prompto regresijos testai
assert test_prompt_quality(
"Classify 'excellent product': positive or negative?",
"positive"
)
Sukurk apie dešimt tokių testų atvejų, reprezentuojančių tavo realius naudojimo scenarijus, ir vykdyk juos kiekvieną kartą, kai modifikuoji promptą. Dešimties minučių testų rinkinys sutaupys savaites abejonių dėl suvokiamos kokybės.
7. Gamybinio diegimo kontrolinis sąrašas
Prieš diegdami patikrinkite kiekvieną punktą:
Infrastruktūra
- Suconfigūruoti aplinkos kintamieji (OPENAI_API_KEY ir kt.)
- Suconfigūruoti laiko limitai ir max_retries
- Įdiegtas struktūruotas žurnalavimas
- Įjungtas kaštų stebėjimas
Atsparumas
- Pilnas klaidų apdorojimas (visi HTTP kodai)
- Eksponentinis delsos didinimas kartojimams
- Grandinės nutraukiklis ilgalaikiams sutrikimams
- Perjungimas į alternatyvų modelį
Saugumas
- API raktas niekada neatskleistas kode ar žurnaluose
- Naudotojo įvesties validavimas
- Kliento pusės ribojimas
- Jokių konfidencialių duomenų promptuose
Našumas
- Srautinis perdavimas įjungtas naudotojo sąsajoms
- Grupinis apdorojimas didelės apimties užduotims
- Talpyklos naudojimas pasikartojantiems prašymams
- Modelio pasirinkimas pritaikytas kiekvienai užduočiai
Kaštai
- Apibrėžtas dienos biudžetas
- Suconfigūruoti įspėjimai
- Nustatytas max_output_tokens, kur įmanoma
- Pasirinktas kiekvienai užduočiai ekonomiškiausias modelis
Svarbiausi punktai
- Centralizuok kliento konfigūraciją naudodamas vienetinį objektą
- Atskirk ir versijuok savo promptus už kodo ribų
- Įgyvendink modelio atsarginį variantą dideliam prieinamumui
- Naudok grupinį apdorojimą su ribotu lygiagretumu didelėms apimtims
- Testuok savo promptus su kokybės teiginiais
- Prieš kiekvieną diegimą į gamybą laikykis pilno kontrolinio sąrašo