Salt la conținutul principal
Română— Alege o limbă
Meniu

Production: Scalabilitate și Monitorizare

Lecția 18 din 18 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Production: Scalabilitate și Monitorizare
  2. Arhitectura de Producție
  3. Gestionarea Sesiunilor Concurente
  4. Jurnalizare Structurată
  5. Metrici Prometheus
  6. Gestionarea Costurilor
  7. Gestionarea Erorilor în Producție
  8. Puncte cheie
  9. Testați-vă cunoștințele

Actualizat pe 2 noiembrie 2026 — Modele audio. Mai multe modele din acest curs sunt depreciate: tts-1, tts-1-hd și gpt-4o-mini-tts vor înceta să funcționeze la 6 ianuarie 2027 (înlocuitor: gpt-realtime-2.1-mini, pe care ghidul OpenAI TTS îl declară necompatibil cu /v1/audio/speech: migrarea sintezei vocale trebuie făcută prin API-ul Realtime); gpt-realtime, gpt-4o-realtime și modelele audio legacy la 20 ianuarie 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe și /v1/audio/translations la 26 februarie 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Pentru voce full-duplex, GPT-Live 1 este disponibil în API din 10 septembrie 2026.

Actualizat pe 3 noiembrie 2026. Gestionarea costurilor, care anterior se rezuma la o singură propoziție, reflectă acum modelul de facturare descris de OpenAI (facturare per răspuns, conversația returnată la fiecare tură, audio contorizat în tokeni, cache automat, transcrierea facturată separat) și trunchierea prin retention_ratio, al cărui format a fost verificat față de tipurile SDK openai versiunea 3.42.1. Sursă: Optimizarea costurilor.

Production: Scalabilitate și Monitorizare

Trecerea de la un prototip de agent vocal la un serviciu de producție fiabil și scalabil necesită o atenție deosebită infrastructurii, monitorizării și gestionării erorilor. Această lecție finală acoperă elementele operaționale esențiale pentru implementarea unui agent vocal în condiții reale.

Arhitectura de Producție

În producție, agentul vocal rulează în spatele unui echilibrator de sarcină (load balancer) și al unui pool de lucrători (workers):

1

Load Balancer (nginx / HAProxy)

Distribuie conexiunile WebSocket incoming către lucrători. Suportă sesiuni persistente (sticky sessions) pentru a menține afinitatea.

2

Workers (FastAPI + uvicorn)

Fiecare lucrător gestionează multiple sesiuni Realtime simultane datorită asyncio.

3

Database (PostgreSQL)

Stochează jurnalele de conversație, metricile și configurația agentului.

4

Monitoring (Prometheus + Grafana)

Colectează metrici în timp real: latență, număr de sesiuni, erori, costuri.

Gestionarea Sesiunilor Concurente

Fiecare conexiune WebSocket menține o sesiune API Realtime. Numărul de sesiuni simultane este limitat de rate limits-urile dumneavoastră OpenAI și de capacitatea lucrătorilor:

import asyncio
from dataclasses import dataclass

@dataclass
class SessionManager:
    """Gestionează sesiunile concurente ale API-ului Realtime."""
    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):
        """Creează o nouă sesiune cu control al concurenței."""
        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):
        """Închide corect o sesiune."""
        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)

Jurnalizare Structurată

Jurnalizați fiecare interacțiune pentru depanare și conformitate:

import logging
import json
from datetime import datetime

class ConversationLogger:
    """Jurnalizator structurat pentru conversațiile vocale."""

    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):
        """Persistă jurnalul complet în baza de date."""
        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)
            )

Metrici Prometheus

Expuneți metrici pentru monitorizare în timp real:

from prometheus_client import Counter, Histogram, Gauge, start_http_server

# Metrici cheie
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
)

# Pornește serverul de metrici
start_http_server(9090)

Gestionarea Costurilor

Conform ghidului Cost optimization al OpenAI, o sesiune de conversație Realtime este facturată per răspuns, în tokeni de intrare și ieșire pentru text, audio și imagini. Trei mecanisme generează cea mai mare parte a facturii:

  • Întreaga conversație este trimisă înapoi modelului la fiecare răspuns: tururile ulterioare costă mai mult decât cele inițiale.
  • Audio este contorizat în tokeni: 1 token per 100 ms de audio utilizator, 1 token per 50 ms de audio asistent.
  • Cache-ul de prompt se aplică automat: atâta timp cât începutul conversației nu se schimbă, este facturat la rata redusă a tokenilor cached. Modificarea sau ștergerea unui element mai vechi „sparge“ cache-ul de la acel punct încolo.

Transcrierea de intrare, dacă este activată, este facturată separat la tariful propriului model: gpt-transcribe este taxat pe durată, citit din evenimentul conversation.item.input_audio_transcription.completed. Consumul pentru fiecare răspuns apare în response.done, sub response.usage (total_tokens, input_tokens, output_tokens, plus defalcarea pentru text, audio, imagine și cache).

Pentru a limita dimensiunea contextului — și astfel costul tururilor ulterioare — sesiunea acceptă o regulă de trunchiere: dincolo de limită, mesajele cele mai vechi sunt eliminate. Cu retention_ratio setat sub 1, serverul elimină puțin mai mult decât este necesar, ceea ce spațiază trunchierile și păstrează cache-ul:

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

Compromisul: un agent care reține mai puțin context uită mai repede. Completați acest lucru cu limite de sesiune în codul dumneavoastră:

class CostController:
    """Controlează costurile pentru o sesiune Realtime."""

    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 ""

Gestionarea Erorilor în Producție

async def production_event_loop(ws, logger, cost_ctrl):
    """Buclă de evenimente robustă pentru producție."""
    cost_ctrl.start()

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

            # Verifică limitele de cost
            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()

Puncte cheie

  • Arhitectura de producție separă load balancer-ul, lucrătorii asyncio, baza de date și monitorizarea
  • Un SessionManager cu semaphore controlează numărul de sesiuni simultane
  • Jurnalizarea structurată JSON permite depanarea și conformitatea (înregistrarea conversațiilor)
  • Metricile Prometheus (TTFA, durată, tokeni, erori) sunt esențiale pentru operațiunile zilnice
  • CostController limitează durata sesiunii și tokenii pentru a preveni depășirea bugetului

Testați-vă cunoștințele

Cinci întrebări care acoperă întregul lanț vocal, de la WebSocket la implementarea în producție.

1. De ce folosește API-ul Realtime WebSocket în loc de cereri HTTP?

Răspuns: Deoarece o conexiune persistentă și bidirecțională vă permite să transmiteți în flux audio de la microfon și să primiți răspunsuri continuu, fără a plăti overhead-ul stabilirii unei cereri pentru fiecare schimb. Aceasta este condiția prealabilă pentru o conversație cu latență scăzută.

2. Ce trebuie să trimiteți imediat după `session.created` și de ce?

Răspuns: session.update, imediat: aici configurați vocea, instrucțiunile, instrumentele și formatul audio. Până la trimiterea acestui mesaj, sesiunea rulează cu valori implicite.

3. De ce este esențial un server proxy în producție?

Răspuns: Previne expunerea cheii API în client și vă permite să autentificați utilizatorul, să limitați consumul și să jurnalizați apelurile — trei lucruri imposibile dacă browserul vorbește direct cu API-ul.

4. Care este scopul parametrului `prompt` în API-ul de transcriere?

Răspuns: Pentru a orienta recunoașterea către vocabularul așteptat: nume proprii, mărci, jargon de domeniu. Termenii listați acolo sunt transcriși mult mai precis.

5. Care este pârghia principală pentru latența percepută într-un agent vocal?

Răspuns: Streaming-ul end-to-end: redarea audio imediat ce sosesc primele fragmente, în loc să așteptați răspunsul complet, și gestionarea întreruperilor astfel încât utilizatorul să poată interveni în orice moment.