Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Productie: Schalen en Monitoring

Les 18 van 18 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Productie: Schalen en Monitoring
  2. Productiearchitectuur
  3. Gelijktijdige sessies beheren
  4. Gestructureerd loggen
  5. Prometheus-metrieken
  6. Kostenbeheer
  7. Foutafhandeling in productie
  8. Belangrijkste punten
  9. Test uw kennis

Bijgewerkt op 2 november 2026 — Audiomodellen. Verschillende modellen in deze cursus zijn verouderd: tts-1, tts-1-hd en gpt-4o-mini-tts stoppen op 6 januari 2027 (vervanging: gpt-realtime-2.1-mini, waarvan de OpenAI TTS-gids aangeeft dat deze niet wordt ondersteund door /v1/audio/speech: migratie van spraaksynthese moet via de Realtime API verlopen); gpt-realtime, gpt-4o-realtime en legacy audiomodellen op 20 januari 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe en /v1/audio/translations op 26 februari 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Voor full-duplex spraak is GPT-Live 1 beschikbaar in de API sinds 10 september 2026.

Bijgewerkt op 3 november 2026. Kostenbeheer paste eerder in één zin; dit weerspiegelt nu het facturatiemodel zoals beschreven door OpenAI (facturatie per antwoord, conversatie wordt bij elke beurt teruggestuurd, audio geteld in tokens, automatische caching, transcriptie apart gefactureerd) en truncatie via retention_ratio, waarvan het formaat is geverifieerd tegen de openai SDK-types versie 3.42.1. Bron: Cost optimization.

Productie: Schalen en Monitoring

De overstap van een prototype voor een spraakagent naar een betrouwbare, schaalbare productiedienst vereist nauwgezette aandacht voor infrastructuur, monitoring en foutafhandeling. Deze laatste les behandelt de operationele essentiële onderdelen voor het implementeren van een spraakagent onder reële omstandigheden.

Productiearchitectuur

In productie draait de spraakagent achter een load balancer en een pool van workers:

1

Load Balancer (nginx / HAProxy)

Verdeelt inkomende WebSocket-verbindingen over de workers. Ondersteunt sticky sessions om affiniteit te behouden.

2

Workers (FastAPI + uvicorn)

Elke worker behandelt meerdere gelijktijdige Realtime-sessies dankzij asyncio.

3

Database (PostgreSQL)

Slaat conversatielogboeken, metrieken en agentconfiguratie op.

4

Monitoring (Prometheus + Grafana)

Verzamelt realtime-metrieken: latentie, aantal sessies, fouten, kosten.

Gelijktijdige sessies beheren

Elke WebSocket-verbinding onderhoudt een Realtime API-sessie. Het aantal gelijktijdige sessies wordt beperkt door uw OpenAI-ratelimits en de capaciteit van uw workers:

import asyncio
from dataclasses import dataclass

@dataclass
class SessionManager:
    """Beheert gelijktijdige Realtime API-sessies."""
    max_sessions: int = 50
    active_sessions: dict = None
    semaphore: asyncio.Semaphore = None

    def __post_init__(self):
        self.active_sessions = {}
        self.semaphore = asyncio.Semaphore(self.max_sessions)

    async def create_session(self, session_id: str, config: dict):
        """Maakt een nieuwe sessie aan met concurrentiebeheersing."""
        async with self.semaphore:
            if session_id in self.active_sessions:
                raise ValueError(f"Session {session_id} already active")

            self.active_sessions[session_id] = {
                "created_at": asyncio.get_event_loop().time(),
                "config": config,
                "status": "active"
            }
            return session_id

    async def close_session(self, session_id: str):
        """Sluit een sessie correct af."""
        if session_id in self.active_sessions:
            del self.active_sessions[session_id]

    @property
    def active_count(self) -> int:
        return len(self.active_sessions)

    @property
    def available_slots(self) -> int:
        return self.max_sessions - self.active_count

session_manager = SessionManager(max_sessions=50)

Gestructureerd loggen

Log elke interactie voor debugging en compliance:

import logging
import json
from datetime import datetime

class ConversationLogger:
    """Gestructureerde logger voor spraakconversaties."""

    def __init__(self, session_id: str):
        self.session_id = session_id
        self.logger = logging.getLogger(f"voice.{session_id}")
        self.events = []

    def log_event(self, event_type: str, data: dict = None):
        entry = {
            "timestamp": datetime.utcnow().isoformat(),
            "session_id": self.session_id,
            "event_type": event_type,
            "data": data or {}
        }
        self.events.append(entry)
        self.logger.info(json.dumps(entry))

    def log_transcription(self, role: str, text: str):
        self.log_event("transcription", {
            "role": role,
            "text": text
        })

    def log_function_call(self, name: str, args: dict, result: dict, duration_ms: float):
        self.log_event("function_call", {
            "name": name,
            "arguments": args,
            "result": result,
            "duration_ms": round(duration_ms)
        })

    def log_error(self, error_type: str, message: str):
        self.log_event("error", {
            "type": error_type,
            "message": message
        })

    async def save_to_db(self, db_pool):
        """Slaat het volledige logboek persistent op in de database."""
        async with db_pool.acquire() as conn:
            await conn.execute(
                "INSERT INTO conversation_logs (session_id, events, created_at) "
                "VALUES ($1, $2, NOW())",
                self.session_id, json.dumps(self.events)
            )

Prometheus-metrieken

Stel metrieken beschikbaar voor realtime-monitoring:

from prometheus_client import Counter, Histogram, Gauge, start_http_server

# Belangrijke metrieken
sessions_active = Gauge(
    "voice_sessions_active",
    "Number of active voice sessions"
)

session_duration = Histogram(
    "voice_session_duration_seconds",
    "Duration of voice sessions",
    buckets=[30, 60, 120, 300, 600, 1800]
)

response_latency = Histogram(
    "voice_response_latency_ms",
    "Response latency (end of speech → first audio)",
    buckets=[200, 400, 600, 800, 1000, 1500, 2000, 3000]
)

errors_total = Counter(
    "voice_errors_total",
    "Total number of errors",
    ["error_type"]
)

tokens_used = Counter(
    "voice_tokens_total",
    "Tokens consumed",
    ["type"]  # input_audio, output_audio, input_text, output_text
)

# Start de metriekenserver
start_http_server(9090)

Kostenbeheer

Volgens de gids Cost optimization van OpenAI wordt een Realtime-conversatiesessie per antwoord gefactureerd, in input- en outputtokens voor tekst, audio en afbeeldingen. Drie mechanismen drijven het grootste deel van de factuur aan:

  • De volledige conversatie wordt bij elk antwoord teruggestuurd naar het model: latere beurten kosten meer dan eerdere.
  • Audio wordt geteld in tokens: 1 token per 100 ms gebruikersaudio, 1 token per 50 ms assistant-audio.
  • Prompt-caching wordt automatisch toegepast: zolang het begin van de conversatie niet verandert, wordt dit gefactureerd tegen het verlaagde tarief voor gecachete tokens. Het wijzigen of verwijderen van een ouder element “breekt” de cache vanaf dat punt.

Input-transcriptie wordt, indien ingeschakeld, apart gefactureerd tegen het tarief van het eigen model: gpt-transcribe wordt in rekening gebracht op basis van duur, afgelezen van de conversation.item.input_audio_transcription.completed-gebeurtenis. Het verbruik voor elk antwoord verschijnt in response.done, onder response.usage (total_tokens, input_tokens, output_tokens, plus de uitsplitsing voor tekst, audio, afbeelding en cache).

Om de contextgrootte – en dus de kosten van latere beurten – te beperken, accepteert de sessie een truncatieregel: voorbij de limiet worden de oudste berichten verwijderd. Met retention_ratio ingesteld op minder dan 1, verwijdert de server iets meer dan nodig is, wat truncaties spreidt en de cache behoudt:

await ws.send(json.dumps({
    "type": "session.update",
    "session": {
        "type": "realtime",
        "truncation": {
            "type": "retention_ratio",
            "retention_ratio": 0.8,
            "token_limits": {"post_instructions": 8000},
        },
    },
}))

De afweging: een agent die minder context behoudt, vergeet sneller. Vul dit aan met sessielimieten in uw code:

class CostController:
    """Beheert kosten voor een Realtime-sessie."""

    def __init__(self, max_duration_s: int = 600, max_tokens: int = 50000):
        self.max_duration_s = max_duration_s
        self.max_tokens = max_tokens
        self.total_tokens = 0
        self.start_time = None

    def start(self):
        self.start_time = asyncio.get_event_loop().time()

    def update_tokens(self, usage: dict):
        self.total_tokens += usage.get("total_tokens", 0)

    @property
    def elapsed_seconds(self) -> float:
        if not self.start_time:
            return 0
        return asyncio.get_event_loop().time() - self.start_time

    @property
    def should_terminate(self) -> bool:
        if self.elapsed_seconds > self.max_duration_s:
            return True
        if self.total_tokens > self.max_tokens:
            return True
        return False

    @property
    def warning_message(self) -> str:
        remaining = self.max_duration_s - self.elapsed_seconds
        if remaining < 60:
            return f"This session will end in {int(remaining)} seconds."
        return ""

Foutafhandeling in productie

async def production_event_loop(ws, logger, cost_ctrl):
    """Robuuste event loop voor productie."""
    cost_ctrl.start()

    try:
        async for raw in ws:
            event = json.loads(raw)
            t = event["type"]

            # Controleer kostenlimieten
            if cost_ctrl.should_terminate:
                logger.log_event("session_limit_reached")
                await ws.send(json.dumps({
                    "type": "conversation.item.create",
                    "item": {
                        "type": "message",
                        "role": "user",
                        "content": [{"type": "input_text",
                                     "text": "The session is approaching its duration limit."}]
                    }
                }))
                break

            if t == "response.done":
                usage = event["response"].get("usage", {})
                cost_ctrl.update_tokens(usage)
                tokens_used.labels(type="total").inc(usage.get("total_tokens", 0))

            elif t == "error":
                error = event["error"]
                logger.log_error(error["type"], error["message"])
                errors_total.labels(error_type=error["type"]).inc()

                if error["type"] == "rate_limit_error":
                    await asyncio.sleep(1)

    except websockets.exceptions.ConnectionClosed as e:
        logger.log_error("connection_closed", str(e))
    except Exception as e:
        logger.log_error("unexpected", str(e))
    finally:
        session_duration.observe(cost_ctrl.elapsed_seconds)
        sessions_active.dec()

Belangrijkste punten

  • Productiearchitectuur scheidt load balancer, asyncio-workers, database en monitoring
  • Een SessionManager met een semaphore regelt het aantal gelijktijdige sessies
  • Gestructureerd JSON-loggen maakt debugging en compliance mogelijk (opname van conversaties)
  • Prometheus-metrieken (TTFA, duur, tokens, fouten) zijn essentieel voor dagelijkse operaties
  • De CostController beperkt sessieduur en tokens om budgetoverschrijdingen te voorkomen

Test uw kennis

Vijf vragen die de volledige spraakketen bestrijken, van WebSocket tot productie-implementatie.

1. Waarom gebruikt de Realtime API WebSocket in plaats van HTTP-verzoeken?

Antwoord: Omdat een persistente, bidirectionele verbinding u in staat stelt microfoonaudio te streamen en continu antwoorden te ontvangen, zonder de overhead van het tot stand brengen van een verzoek voor elke uitwisseling. Dit is de voorwaarde voor conversaties met lage latentie.

2. Wat moet u direct na `session.created` verzenden, en waarom?

Antwoord: session.update, onmiddellijk: hier configureert u de stem, instructies, tools en het audioformaat. Totdat dit bericht is verzonden, draait de sessie met standaardwaarden.

3. Waarom is een proxyserver essentieel in productie?

Antwoord: Het voorkomt dat de API-sleutel wordt blootgesteld in de client, en het stelt u in staat de gebruiker te authenticeren, het verbruik te beperken en oproepen te loggen – drie dingen die onmogelijk zijn als de browser rechtstreeks met de API communiceert.

4. Wat is het doel van de `prompt`-parameter in de transcriptie-API?

Antwoord: Om herkenning te sturen naar verwachte woordenschat: eigennamen, merken, vakjargon. Termen die u daar opsomt, worden veel nauwkeuriger getranscribeerd.

5. Wat is de belangrijkste hefboom voor waargenomen latentie in een spraakagent?

Antwoord: End-to-end streaming: audio afspelen zodra de eerste fragmenten binnenkomen in plaats van te wachten op het volledige antwoord, en onderbrekingen afhandelen zodat de gebruiker op elk moment kan onderbreken.