Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Léiriú: Scálú agus Monatóireacht

Ceacht 18 as 18 Nuashonraithe 3 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Léiriú: Scálú agus Monatóireacht
  2. Ailtireacht Léirithe
  3. Seisiúin Chomhuaineacha a Bhainistiú
  4. Logáil Struchtúrtha
  5. Méadrachtaí Prometheus
  6. Bainistiú Costais
  7. Láimhseáil Earráidí sa Léiriú
  8. Príomhphointí
  9. Tástáil do Chuid Eolais

Nuashonraithe 2 Samhain, 2026 — Múnlaí fuaime. Tá roinnt múnlaí sa chúrsa seo imithe in éag: stopfaidh tts-1, tts-1-hd, agus gpt-4o-mini-tts ag obair ar 6 Eanáir, 2027 (ionadaí: gpt-realtime-2.1-mini, a deir treoir TTS OpenAI nach dtacaítear leis le /v1/audio/speech: caithfidh imirce sintéise cainte dul tríd an API Realtime); gpt-realtime, gpt-4o-realtime, agus múnlaí fuaime oidhreachta ar 20 Eanáir, 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe, agus /v1/audio/translations ar 26 Feabhra, 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Maidir le guth lán-dúbailte, tá GPT-Live 1 ar fáil san API ó 10 Meán Fómhair, 2026.

Nuashonraithe 3 Samhain, 2026. Bhíodh bainistiú costais oiriúnach in abairt amháin; léiríonn sé anois an tsamhail billeála a thuairiscíonn OpenAI (billeáil in aghaidh freagartha, comhrá ar ais gach casadh, fuaim áirithe i dtócananna, taisceadh uathoibríoch, tras-scríobh billeáilte ar leithligh) agus gearradh trí retention_ratio, a fíoraíodh a fhormáid i gcoinne cineálacha SDK openai leagan 3.42.1. Foinse: Cost optimization.

Léiriú: Scálú agus Monatóireacht

Éilíonn bogadh ó phrótaitíopa gníomhaire gutha go seirbhís léirithe iontaofa, inscálaithe aird dhíreach ar bhonneagar, monatóireacht, agus láimhseáil earráidí. Clúdaíonn an ceacht deireanach seo na bunriachtanais oibríochtúla chun gníomhaire gutha a chur in úsáid i gcoinníollacha an tsaoil réadaigh.

Ailtireacht Léirithe

Sa léiriú, ritheann an gníomhaire gutha taobh thiar de chothromóir ualaigh agus linn oibrithe:

1

Cothromóir Ualaigh (nginx / HAProxy)

Dáileann sé naisc WebSocket isteach thar oibrithe. Tacaíonn sé le seisiáin ghreamaitheacha chun cleamhnas a choinneáil.

2

Oibrithe (FastAPI + uvicorn)

Láimhseálann gach oibrí roinnt seisiún Realtime comhuaineacha mar gheall ar asyncio.

3

Bunachar Sonraí (PostgreSQL)

Stórálann sé logaí comhráite, méadrachtaí, agus cumraíocht an ghníomhaire.

4

Monatóireacht (Prometheus + Grafana)

Bailíonn sé méadrachtaí fíor-ama: moill, líon seisiún, earráidí, costais.

Seisiúin Chomhuaineacha a Bhainistiú

Coinníonn gach nasc WebSocket seisiún API Realtime. Tá an líon seisiún comhuaineach teoranta ag do theorainneacha ráta OpenAI agus acmhainn do chuid oibrithe:

import asyncio
from dataclasses import dataclass

@dataclass
class SessionManager:
    """Bainistíonn sé seisiúin API Realtime comhuaineacha."""
    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):
        """Cruthaíonn sé seisiún nua le rialú comhthreomhaireachta."""
        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):
        """Dúnann sé seisiún i gceart."""
        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)

Logáil Struchtúrtha

Déan logáil ar gach idirghníomhaíocht chun dífhabhtaithe agus comhlíontachta:

import logging
import json
from datetime import datetime

class ConversationLogger:
    """Logálaí struchtúrtha do chomhráite gutha."""

    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):
        """Buanaíonn sé an loga iomlán sa bhunachar sonraí."""
        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)
            )

Méadrachtaí Prometheus

Nocht méadrachtaí le haghaidh monatóireachta fíor-ama:

from prometheus_client import Counter, Histogram, Gauge, start_http_server

# Méadrachtaí tábhachtacha
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
)

# Tosaigh an freastalaí méadrachtaí
start_http_server(9090)

Bainistiú Costais

De réir threoir Cost optimization ó OpenAI, billeáiltear seisiún comhrá Realtime in aghaidh na freagartha, i dtócananna ionchuir agus aschuir do théacs, fuaim, agus íomhánna. Tiomáineann trí mheicníocht an chuid is mó den bhille:

  • Seoltar an comhrá iomlán ar ais chuig an múnla le gach freagra: costálann casanna níos déanaí níos mó ná cinn níos luaithe.
  • Áirítear fuaim i dtócananna: 1 tócan in aghaidh gach 100 ms d’fhuaime úsáideora, 1 tócan in aghaidh gach 50 ms d’fhuaime an chúntóra.
  • Baineann taisceadh leid isteach go huathoibríoch: fad nach n-athraíonn tús an chomhrá, billeáiltear é ag an ráta laghdaithe tócananna taisce. Briseann modhnú nó scriosadh eiliminte níos sine an taisce ón bpointe sin amach.

Má chumasaítear é, billeáiltear tras-scríobh ionchuir ar leithligh ag ráta a mhúnla féin: gearrtar táille ar gpt-transcribe de réir faid, léite ón imeacht conversation.item.input_audio_transcription.completed. Feictear tomhaltas do gach freagra in response.done, faoi response.usage (total_tokens, input_tokens, output_tokens, chomh maith leis an mbriseadh síos do théacs, fuaim, íomhá, agus taisce).

Chun méid an chomhthéacs a theorannú — agus mar sin costais chasanna níos déanaí — glacann an seisiún le riail ghearrtha: thar an teorainn, scaoiltear na teachtaireachtaí is sine. Le retention_ratio socraithe faoi 1, baineann an freastalaí beagán níos mó ná mar is gá, rud a chuireann spás idir gearrthacha agus a chaomhnaíonn an taisce:

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

An malartú: déanann gníomhaire a choinníonn níos lú comhthéacs dearmad níos tapúla. Comhlánaigh é seo le teorainneacha seisiúna i do chód:

class CostController:
    """Rialaíonn sé costais do sheisiún 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 ""

Láimhseáil Earráidí sa Léiriú

async def production_event_loop(ws, logger, cost_ctrl):
    """Lúb imeachta láidir don léiriú."""
    cost_ctrl.start()

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

            # Seiceáil teorainneacha costais
            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()

Príomhphointí

  • Scarann ailtireacht léirithe cothromóir ualaigh, oibrithe asyncio, bunachar sonraí, agus monatóireacht
  • Rialaíonn SessionManager le semaphore líon na seisiún comhuaineach
  • Cumasaíonn logáil struchtúrtha JSON dífhabhtú agus comhlíontacht (taifeadadh comhráite)
  • Tá méadrachtaí Prometheus (TTFA, fad, tócananna, earráidí) riachtanach d’oibríochtaí laethúla
  • Teorannaíonn an CostController fad seisiúna agus tócananna chun sáruithe buiséid a chosc

Tástáil do Chuid Eolais

Cúig cheist a chlúdaíonn an slabhra gutha iomlán, ó WebSocket go dtí cur in úsáid léirithe.

1. Cén fáth a n-úsáideann an API Realtime WebSocket in ionad iarratais HTTP?

Freagra: Toisc go ligeann nasc leanúnach, déthreoch duit fuaime micreafóin a shruthlú agus freagraí a fháil go leanúnach, gan an t-ualach a bhaineann le hiarratas a bhunú do gach malartú a íoc. Is é seo an réamhriachtanas do chomhrá íseal-mhoille.

2. Cad a chaithfidh tú a sheoladh láithreach tar éis `session.created`, agus cén fáth?

Freagra: session.update, láithreach: is é seo an áit a ndéanann tú cumraíocht ar an nguth, treoracha, uirlisí, agus formáid fuaime. Go dtí go seoltar an teachtaireacht seo, ritheann an seisiún le luachanna réamhshocraithe.

3. Cén fáth a bhfuil freastalaí seachfhreastail riachtanach sa léiriú?

Freagra: Cuireann sé cosc ar an eochair API a nochtadh sa chliant, agus ligeann sé duit an t-úsáideoir a fhíordheimhniú, tomhaltas a theorannú, agus glaonna a logáil — trí rud nach féidir a dhéanamh má labhraíonn an brabhsálaí go díreach leis an API.

4. Cad é cuspóir an pharaiméadair `prompt` san API tras-scríofa?

Freagra: Chun aitheantas a stiúradh i dtreo foclóraíochta a bhfuiltear ag súil léi: ainmneacha dílse, brandaí, argóit fearainn. Déantar téarmaí a liostaíonn tú ansin a thras-scríobh i bhfad níos cruinne.

5. Cad é an príomhghiómar don mhoill mheasta i ngníomhaire gutha?

Freagra: Sruthú ó cheann go ceann: seinm fuaime chomh luath agus a thagann na chéad blúirí isteach in ionad fanacht leis an bhfreagra iomlán, agus láimhseáil cur isteach ionas gur féidir leis an úsáideoir isteach a ghearradh ag am ar bith.