Production: Scalabilitate și Monitorizare
Pe această pagină
Actualizat pe 2 noiembrie 2026 — Modele audio. Mai multe modele din acest curs sunt depreciate:
tts-1,tts-1-hdșigpt-4o-mini-ttsvor î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/translationsla 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 SDKopenaiversiunea 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):
Load Balancer (nginx / HAProxy)
Distribuie conexiunile WebSocket incoming către lucrători. Suportă sesiuni persistente (sticky sessions) pentru a menține afinitatea.
Workers (FastAPI + uvicorn)
Fiecare lucrător gestionează multiple sesiuni Realtime simultane datorită asyncio.
Database (PostgreSQL)
Stochează jurnalele de conversație, metricile și configurația agentului.
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
SessionManagercu 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
CostControllerlimitează 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.