Best Practices voor Productie
Op deze pagina
Les bijgewerkt op 3 november 2026 op basis van OpenAI-documentatie:
temperatureentop_pworden alleen geaccepteerd met een redeneerinspanning vannone, terwijl GPT-5.6-modellen standaard redeneren (medium). Aanroepen die deze parameters instellen, moeten daaromreasoning={"effort": "none"}(Responses API) ofreasoning_effort="none"(Chat Completions) specificeren. Bronnen: Using GPT-6 · GPT-5.6 Terra.
Best Practices voor Productie
Deze les behandelt de essentiële best practices voor het implementeren van een op de OpenAI API gebaseerde applicatie in productie. Beschouw dit als uw checklist voorafgaand aan de lancering. Eerdere lessen gaven u de bouwstenen—foutafhandeling, rate limits, veerkracht, observability en kosten. Nu is het tijd om deze samen te voegen tot een applicatie die een collega kan overnemen en draaien zonder uw hulp.
1. Client-architectuur
Singleton met gecentraliseerde configuratie
Het bij elke aanroep instantiëren van een OpenAI-client verspilt de onderliggende HTTP-verbinding en, wat ernstiger is, verspreidt uw configuratie. U krijgt hier een time-out van 30 seconden en daar de standaardwaarde, zonder te weten welke in productie van toepassing is. De lru_cache-decorator garandeert één enkel exemplaar, op één plek geconfigureerd.
from openai import OpenAI
from functools import lru_cache
@lru_cache(maxsize=1)
def get_client() -> OpenAI:
"""Singleton client met productieconfiguratie."""
return OpenAI(
max_retries=3,
timeout=30.0,
)
# Overal in uw code:
client = get_client()
Omgevingsvariabelen
Hetzelfde principe geldt voor instellingen die per omgeving verschillen. Controleer bij het opstarten op vereiste variabelen: het is beter dat een service weigert te starten met een duidelijke melding, dan dat hij start en faalt bij de eerste gebruikersaanroep. Hierdoor zijn het model, de tokenlimiet en de temperatuur aanpasbaar zonder herimplementatie.
import os
# VEREIST: sla nooit sleutels hard-coded op
REQUIRED_ENV = ["OPENAI_API_KEY"]
for var in REQUIRED_ENV:
if not os.environ.get(var):
raise RuntimeError(f"Missing variable {var}")
# Omgevingsspecifieke configuratie
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-beheer
Prompts scheiden van code
Een prompt is een bedrijfsmiddel, net als een bedrijfsregel. Het verbergen ervan in een f-string binnen een functie maakt het onmogelijk voor iemand die het bedrijf kent maar geen Python, om dit te beoordelen. Isoleer het als een geparametriseerde sjabloon: de functie reduceert dan tot formatteren en aanroepen, en een temperatuur van 0.0 maakt classificatie reproduceerbaar.
# 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()
Versioneer uw prompts
Het wijzigen van een prompt verandert het systeemgedrag net zo zeker als het wijzigen van code, maar zonder dat een unit test dit merkt. Bewaar opeenvolgende versies en selecteer de actieve via configuratie. Hiermee kunt u twee formuleringen vergelijken op echt verkeer en teruggaan naar de vorige met een omgevingsvariabele als de nieuwe de resultaten verslechtert.
PROMPTS = {
"classification_v1": "Classify: {texte}",
"classification_v2": "Analyze and classify precisely: {texte}",
}
# Gebruik in productie een specifieke versie
ACTIVE_PROMPT = os.environ.get("PROMPT_VERSION", "classification_v2")
3. Time-outs en limieten
Begrens elke invoer van buitenaf voordat deze de API bereikt. Een gebruiker die een PDF van 200 pagina’s in uw invoerveld plakt, mag geen aanroep van meerdere dollars kunnen triggeren of ervoor zorgen dat het verzoek faalt door context-overloop. Preventief inkorten, gecombineerd met de uitvoercap en temperatuur uit de configuratie, maakt de kosten en latentie van elke aanroep voorspelbaar.
def appel_avec_garde_fous(prompt: str) -> str:
"""API-aanroep met alle veiligheidsmaatregelen."""
# Beperk prompt-grootte
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
Wanneer een model verzadigd is of tijdelijk niet beschikbaar, is het teruggeven van een fout niet uw enige optie. Overschakelen naar een secundair model verslechtert de kwaliteit maar behoudt de service—een afweging die vaak verkieslijk is voor een supportassistent, minder voor contractanalyse. De lus doorloopt modellen in volgorde van voorkeur en gooit alleen een uitzondering als alles faalt.
from openai import RateLimitError, InternalServerError
def appel_avec_fallback(prompt: str) -> str:
"""Probeert Terra en valt terug op Luna bij een fout."""
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. Batchverwerking
Om duizend documenten te verwerken, zijn sequentiële aanroepen te traag en gelijktijdige aanroepen blazen uw rate limits op. Een semaphore biedt de juiste balans. Twee details maken deze implementatie robuust: return_exceptions=True voorkomt dat één enkele fout de hele batch annuleert, en sorteren op index herstelt de oorspronkelijke volgorde, wat asyncio.gather niet garandeert qua uitvoeringstijd.
import asyncio
from openai import AsyncOpenAI
async def traiter_batch(prompts: list[str], max_concurrent: int = 5) -> list:
"""Verwerkt een batch prompts met beperkte gelijktijdigheid."""
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)
# Sorteer op index om de volgorde te behouden
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. Testen en validatie
U heeft twee verschillende soorten tests nodig. De eerste controleert de infrastructuur—de sleutel werkt, het netwerk passeert, het model reageert—en past goed in een health check bij het opstarten. De tweede, originelere, test de kwaliteit van de prompt zelf: u dient een geval in waarvan u het juiste antwoord kent en verifieert dat dit verschijnt. Deze asserties zijn uw veiligheidsnet tegen regressies wanneer u een sjabloon herformuleert.
def test_api_disponible():
"""Verifieert dat de API toegankelijk is."""
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:
"""Verifieert dat een prompt een consistent resultaat retourneert."""
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
# Prompt-regressietests
assert test_prompt_quality(
"Classify 'excellent product': positive or negative?",
"positive"
)
Bouw een dozijn van dergelijke testgevallen, representatief voor uw echte use cases, en voer ze uit telkens wanneer u een prompt wijzigt. Een testsuite van tien minuten bespaart u weken van twijfel over de waargenomen kwaliteit.
7. Checklist voor implementatie in productie
Controleer voordat u implementeert elk punt:
Infrastructuur
- Omgevingsvariabelen geconfigureerd (OPENAI_API_KEY, enz.)
- Time-outs en max_retries geconfigureerd
- Gestructureerde logging ingesteld
- Kostenmonitoring ingeschakeld
Veerkracht
- Volledige foutafhandeling (alle HTTP-codes)
- Exponentiële backoff voor retries
- Circuit breaker voor langdurige storingen
- Fallback naar een alternatief model
Beveiliging
- API-sleutel nooit blootgesteld in code of logs
- Validatie van gebruikersinvoer
- Client-side rate limiting
- Geen gevoelige data in prompts
Prestaties
- Streaming ingeschakeld voor gebruikersinterfaces
- Batchverwerking voor taken met hoog volume
- Caching voor herhalende verzoeken
- Modelkeuze aangepast aan elke taak
Kosten
- Dagbudget gedefinieerd
- Alerts geconfigureerd
- max_output_tokens ingesteld waar mogelijk
- Kosteneffectiefste model geselecteerd per taak
Belangrijkste punten
- Centraliseer clientconfiguratie met een singleton
- Scheid en versioneer uw prompts buiten de code om
- Implementeer model-fallback voor hoge beschikbaarheid
- Gebruik batchverwerking met beperkte gelijktijdigheid voor volume
- Test uw prompts met kwaliteitsasserties
- Volg de volledige checklist voor elke implementatie in productie