Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Produzzjoni: Skalar u Monitoraġġ

Lezzjoni 18 / 18 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Produzzjoni: Skalar u Monitoraġġ
  2. Arkitettura tal-Produzzjoni
  3. Ġestjoni ta’ Sessjonijiet Konkorrenti
  4. Reġistrar Strutturat
  5. Metriċi ta’ Prometheus
  6. Ġestjoni tal-Ispejjeż
  7. Immaniġġjar ta’ Żbalji fil-Produzzjoni
  8. Punti Ewlenin
  9. Ittestja l-Għarfien Tiegħek

Aġġornat fit-2 ta’ Novembru, 2026 — Mudelli tal-awdjo. Diversi mudelli f’dan il-kors huma deprekati: tts-1, tts-1-hd, u gpt-4o-mini-tts se jieqfu jaħdmu fis-6 ta’ Jannar, 2027 (sostituzzjoni: gpt-realtime-2.1-mini, li l-gwida tat-TTS ta’ OpenAI tiddikjara li mhix appoġġjata minn /v1/audio/speech: il-migrazzjoni tas-sinteżi tal-kliem trid tgħaddi mill-API Realtime); gpt-realtime, gpt-4o-realtime, u mudelli tal-awdjo legacy fl-20 ta’ Jannar, 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe, u /v1/audio/translations fis-26 ta’ Frar, 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Għall-vuċi full-duplex, GPT-Live 1 kien disponibbli fl-API mill-10 ta’ Settembru, 2026.

Aġġornat fit-3 ta’ Novembru, 2026. Il-ġestjoni tal-ispejjeż qabel kienet tidħol f’sentenza waħda; issa tirrifletti l-mudell ta’ fatturazzjoni deskritt minn OpenAI (fatturazzjoni għal kull tweġiba, konversazzjoni rritornata f’kull dawra, awdjo mgħoddud f’tokens, caching awtomatiku, trascrizzjoni fatturata separatament) u t-truncation permezz ta’ retention_ratio, li l-format tiegħu ġie vverifikat kontra t-tipi tal-SDK openai verżjoni 3.42.1. Sors: Ottimizzazzjoni tal-ispejjeż.

Produzzjoni: Skalar u Monitoraġġ

Il-passaġġ minn prototip ta’ aġent tal-vuċi għal servizz ta’ produzzjoni affidabbli u li jiskala jeħtieġ attenzjoni qrib lejn l-infrastruttura, il-monitoraġġ, u l-immaniġġjar tal-iżbalji. Din il-lezzjoni finali tkopri l-essenzjali operattivi għad-dispjegament ta’ aġent tal-vuċi f’kundizzjonijiet tad-dinja reali.

Arkitettura tal-Produzzjoni

Fil-produzzjoni, l-aġent tal-vuċi jaħdem wara load balancer u pool ta’ ħaddiema (workers):

1

Load Balancer (nginx / HAProxy)

Jiddistribwixxi konnessjonijiet WebSocket li qed jaslu fost il-ħaddiema. Jappoġġja sessjonijiet "sticky" biex iżomm l-affinità.

2

Ħaddiema (FastAPI + uvicorn)

Kull ħaddiem jimmaniġġja sessjonijiet Realtime multipli simultanjament grazzi għal asyncio.

3

Database (PostgreSQL)

Jaħżen logs tal-konversazzjoni, metriċi, u konfigurazzjoni tal-aġent.

4

Monitoraġġ (Prometheus + Grafana)

Jiġbor metriċi f'ħin reali: latenza, għadd ta' sessjonijiet, żbalji, spejjeż.

Ġestjoni ta’ Sessjonijiet Konkorrenti

Kull konnessjoni WebSocket iżżomm sessjoni tal-API Realtime. In-numru ta’ sessjonijiet simultanji huwa limitat mil-limiti tar-rata ta’ OpenAI tiegħek u mill-kapaċità tal-ħaddiema tiegħek:

import asyncio
from dataclasses import dataclass

@dataclass
class SessionManager:
    """Jimmaniġġja sessjonijiet konkurrenti tal-API 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):
        """Joħloq sessjoni ġdida b'kontroll tal-konkorrenza."""
        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):
        """Jagħlaq sessjoni b'mod korrett."""
        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)

Reġistrar Strutturat

Irreġistra kull interazzjoni għad-debugging u l-konformità:

import logging
import json
from datetime import datetime

class ConversationLogger:
    """Reġistratur strutturat għal konversazzjonijiet bil-vuċi."""

    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):
        """Jippersisti l-log sħiħ fid-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)
            )

Metriċi ta’ Prometheus

Esponi metriċi għall-monitoraġġ f’ħin reali:

from prometheus_client import Counter, Histogram, Gauge, start_http_server

# Metriċi ewlenin
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
)

# Ibda s-server tal-metriċi
start_http_server(9090)

Ġestjoni tal-Ispejjeż

Skont il-gwida ta’ Ottimizzazzjoni tal-ispejjeż ta’ OpenAI, sessjoni ta’ konversazzjoni Realtime tiġi fatturata għal kull tweġiba, f’tokens tal-input u tal-output għat-test, l-awdjo, u l-immaġnijiet. Tliet mekkaniżmi jmexxu l-biċċa l-kbira tal-fattura:

  • Il-konversazzjoni sħiħa tintbagħat lura lill-mudell ma’ kull tweġiba: id-dawriet ta’ wara jiswew aktar minn dawk ta’ qabel.
  • L-awdjo jiġi mgħoddud f’tokens: token wieħed kull 100 ms ta’ awdjo tal-utent, token wieħed kull 50 ms ta’ awdjo tal-assistent.
  • Il-caching tal-prompt japplika awtomatikament: sakemm il-bidu tal-konversazzjoni ma jinbidilx, jiġi fatturat bir-rata mnaqqsa tat-token cached. Il-modifika jew it-tħassir ta’ element aktar antik “jikser” il-cache minn dak il-punt ‘il quddiem.

It-trascrizzjoni tal-input, jekk attivata, tiġi fatturata separatament bir-rata tal-mudell tagħha stess: gpt-transcribe tiġi ċċarġjata skont id-durata, moqrija mill-avveniment conversation.item.input_audio_transcription.completed. Il-konsum għal kull tweġiba jidher f’response.done, taħt response.usage (total_tokens, input_tokens, output_tokens, flimkien mat-tqassim għat-test, l-awdjo, l-immaġni, u l-cache).

Biex tillimita d-daqs tal-kuntest—u għalhekk l-ispiża tad-dawriet ta’ wara—is-sessjoni taċċetta regola ta’ truncation: lil hinn mil-limitu, il-messaġġi l-aktar antiki jitneħħew. B’retention_ratio stabbilit taħt 1, is-server ineħħi ftit aktar milli meħtieġ, li jbiegħed it-truncations u jippreserva l-cache:

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

Il-kompromess: aġent li jżomm inqas kuntest jinsa aktar malajr. Ikkumplimenta dan b’limiti tas-sessjoni fil-kodiċi tiegħek:

class CostController:
    """Jikkontrolla l-ispejjeż għal sessjoni 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 ""

Immaniġġjar ta’ Żbalji fil-Produzzjoni

async def production_event_loop(ws, logger, cost_ctrl):
    """Loop tal-avvenimenti robust għall-produzzjoni."""
    cost_ctrl.start()

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

            # Iċċekkja l-limiti tal-ispejjeż
            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()

Punti Ewlenin

  • L-arkitettura tal-produzzjoni tissepara l-load balancer, il-ħaddiema asyncio, id-database, u l-monitoraġġ
  • SessionManager b’semaphore jikkontrolla n-numru ta’ sessjonijiet simultanji
  • Ir-reġistrar strutturat JSON jippermetti d-debugging u l-konformità (reġistrazzjoni tal-konversazzjoni)
  • Il-metriċi ta’ Prometheus (TTFA, durata, tokens, żbalji) huma essenzjali għall-operazzjonijiet ta’ kuljum
  • Il-CostController jillimita d-durata tas-sessjoni u t-tokens biex jipprevjeni qbiż tal-baġit

Ittestja l-Għarfien Tiegħek

Ħames mistoqsijiet li jkopru l-katina kollha tal-vuċi, mill-WebSocket sad-dispjegament fil-produzzjoni.

1. Għaliex l-API Realtime tuża WebSocket minflok talbiet HTTP?

Tweġiba: Għax konnessjoni persistenti u bidirezzjonali tippermettilek li tistreamja l-awdjo tal-mikrofon u tirċievi tweġibiet kontinwament, mingħajr ma tħallas l-overhead li tistabbilixxi talba għal kull skambju. Dan huwa l-prerekwiżit għal konversazzjoni b’latenza baxxa.

2. X'għandek tibgħat immedjatament wara `session.created`, u għaliex?

Tweġiba: session.update, immedjatament: dan huwa fejn tikkonfigura l-vuċi, l-istruzzjonijiet, l-għodod, u l-format tal-awdjo. Sakemm din il-messaġġ ma tintbagħatx, is-sessjoni taħdem b’valuri default.

3. Għaliex server proxy huwa essenzjali fil-produzzjoni?

Tweġiba: Jipprevjeni li tesponi l-API key fil-klijent, u jħallik tawtentika lill-utent, tillimita l-konsum, u tirreġistra s-sejħiet—tliet affarijiet impossibbli jekk il-browser jitkellem direttament mal-API.

4. X'inhu l-għan tal-parametru `prompt` fl-API tat-trascrizzjoni?

Tweġiba: Biex tiddirieġi r-rikonoxximent lejn vokabolarju mistenni: ismijiet proprji, marki, ġargon tad-dominju. It-termini li telenka hemm jiġu traskritti b’mod ħafna aktar preċiż.

5. X'inhu l-leva ewlenija għall-latenza perċepita f'aġent tal-vuċi?

Tweġiba: Streaming end-to-end: li tħaddan l-awdjo hekk kif jaslu l-ewwel frammenti minflok ma tistenna t-tweġiba sħiħa, u li timmaniġġja l-interruzzjoni sabiex l-utent ikun jista’ jindaħal fi kwalunkwe ħin.