Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Best Practices voor Productie

Les 17 van 22 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Best Practices voor Productie
  2. 1. Client-architectuur
  3. 2. Prompt-beheer
  4. 3. Time-outs en limieten
  5. 4. Model Fallback
  6. 5. Batchverwerking
  7. 6. Testen en validatie
  8. 7. Checklist voor implementatie in productie
  9. Belangrijkste punten

Les bijgewerkt op 3 november 2026 op basis van OpenAI-documentatie: temperature en top_p worden alleen geaccepteerd met een redeneerinspanning van none, terwijl GPT-5.6-modellen standaard redeneren (medium). Aanroepen die deze parameters instellen, moeten daarom reasoning={"effort": "none"} (Responses API) of reasoning_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