Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Produkcija: Skaliranje i nadzor

Lekcija 18 od 18 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Produkcija: Skaliranje i nadzor
  2. Produkcijska arhitektura
  3. Upravljanje istovremenim sesijama
  4. Strukturirano bilježenje (Logging)
  5. Prometheus metrike
  6. Upravljanje troškovima
  7. Rukovanje greškama u produkciji
  8. Ključne točke
  9. Provjeri svoje znanje

Ažurirano 2. studenoga 2026. — Audio modeli. Nekoliko modela u ovom tečaju je zastarjelo: tts-1, tts-1-hd i gpt-4o-mini-tts prestat će raditi 6. siječnja 2027. (zamjena: gpt-realtime-2.1-mini, za koji OpenAI TTS vodič navodi da nije podržan od strane /v1/audio/speech: migracija sinteze govora mora ići kroz Realtime API); gpt-realtime, gpt-4o-realtime i stariji audio modeli 20. siječnja 2027. (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe i /v1/audio/translations 26. veljače 2027. (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Za full-duplex glas, GPT-Live 1 dostupan je u API-ju od 10. rujna 2026.

Ažurirano 3. studenoga 2026. Upravljanje troškovima ranije je stalo u jednu rečenicu; sada odražava model naplate koji opisuje OpenAI (naplata po odgovoru, razgovor se vraća u svakom koraku, audio se broji u tokenima, automatsko keširanje, transkripcija se naplaćuje odvojeno) i skraćivanje putem retention_ratio, čiji je format verificiran prema openai SDK tipovima verzije 3.42.1. Izvor: Optimizacija troškova.

Produkcija: Skaliranje i nadzor

Prijelaz s prototipa glasovnog agenta na pouzdanu, skalabilnu produkcijsku uslugu zahtijeva pomnu pozornost na infrastrukturu, nadzor i rukovanje greškama. Ova posljednja lekcija pokriva operativne osnove za deploy glasovnog agenta u stvarnim uvjetima.

Produkcijska arhitektura

U produkciji, glasovni agent radi iza balancera opterećenja i poola radnika:

1

Balancer opterećenja (nginx / HAProxy)

Distribuira dolazne WebSocket veze između radnika. Podržava ljepljive sesije (sticky sessions) za održavanje afiniteta.

2

Radnici (FastAPI + uvicorn)

Svaki radnik obrađuje više istovremenih Realtime sesija zahvaljujući asyncio.

3

Baza podataka (PostgreSQL)

Pohranjuje zapisnike razgovora, metrike i konfiguraciju agenta.

4

Nadzor (Prometheus + Grafana)

Prikuplja metrike u stvarnom vremenu: latencija, broj sesija, greške, troškovi.

Upravljanje istovremenim sesijama

Svaka WebSocket veza održava sesiju Realtime API-ja. Broj istovremenih sesija ograničen je tvojim OpenAI limitima brzine (rate limits) i kapacitetom tvojih radnika:

import asyncio
from dataclasses import dataclass

@dataclass
class SessionManager:
    """Upravlja istovremenim sesijama Realtime API-ja."""
    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):
        """Stvara novu sesiju s kontrolom konkurentnosti."""
        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):
        """Ispravno zatvara sesiju."""
        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)

Strukturirano bilježenje (Logging)

Bilježi svaku interakciju radi otklanjanja grešaka i usklađenosti:

import logging
import json
from datetime import datetime

class ConversationLogger:
    """Strukturirani logger za glasovne razgovore."""

    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):
        """Trajno pohranjuje cijeli zapis u bazu podataka."""
        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 metrike

Izloži metrike za nadzor u stvarnom vremenu:

from prometheus_client import Counter, Histogram, Gauge, start_http_server

# Ključne metrike
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
)

# Pokreni poslužitelj metrika
start_http_server(9090)

Upravljanje troškovima

Prema OpenAI vodiču Cost optimization, sesija razgovora u Realtime modu naplaćuje se po odgovoru, u ulaznim i izlaznim tokenima za tekst, audio i slike. Tri mehanizma pokreću većinu računa:

  • Cijeli razgovor se šalje natrag modelu sa svakim odgovorom: kasniji koraci koštaju više od ranijih.
  • Audio se broji u tokenima: 1 token na svakih 100 ms korisničkog audia, 1 token na svakih 50 ms audio zapisa asistenta.
  • Keširanje prompta vrijedi automatski: sve dok se početak razgovora ne mijenja, naplaćuje se po smanjenoj stopi za keširane tokene. Izmjena ili brisanje starijeg elementa „kida“ keš od te točke nadalje.

Ulazna transkripcija, ako je omogućena, naplaćuje se odvojeno po stopi vlastitog modela: gpt-transcribe se naplaćuje po trajanju, očitanom iz događaja conversation.item.input_audio_transcription.completed. Potrošnja za svaki odgovor pojavljuje se u response.done, pod response.usage (total_tokens, input_tokens, output_tokens, plus raščlamba za tekst, audio, sliku i keš).

Za ograničavanje veličine konteksta—i time troška kasnijih koraka—sesija prihvaća pravilo skraćivanja: iznad limita, najstarije poruke se odbacuju. S retention_ratio postavljenim ispod 1, poslužitelj uklanja nešto više nego što je nužno, što razmakne skraćivanja i čuva keš:

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

Kompromis: agent koji zadržava manje konteksta brže zaboravlja. Nadopuni ovo limitima sesije u svom kodu:

class CostController:
    """Kontrolira troškove za Realtime sesiju."""

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

Rukovanje greškama u produkciji

async def production_event_loop(ws, logger, cost_ctrl):
    """Robusna petlja događaja za produkciju."""
    cost_ctrl.start()

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

            # Provjeri limite troškova
            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()

Ključne točke

  • Produkcijska arhitektura odvaja balancer opterećenja, asyncio radnike, bazu podataka i nadzor
  • SessionManager sa semaforom kontrolira broj istovremenih sesija
  • JSON strukturirano bilježenje omogućuje otklanjanje grešaka i usklađenost (snimanje razgovora)
  • Prometheus metrike (TTFA, trajanje, tokeni, greške) ključne su za svakodnevni rad
  • CostController ograničava trajanje sesije i broj tokena kako bi spriječio prekoračenje budžeta

Provjeri svoje znanje

Pet pitanja koja pokrivaju cijeli lanac glasa, od WebSocketa do deploya u produkciju.

1. Zašto Realtime API koristi WebSocket umjesto HTTP zahtjeva?

Odgovor: Zato što trajna, dvosmjerna veza omogućuje strujanje (streaming) audio zapisa s mikrofona i kontinuirani prijem odgovora, bez plaćanja režije uspostave zahtjeva za svaku razmjenu. To je preduvjet za razgovor s niskom latencijom.

2. Što moraš poslati odmah nakon `session.created` i zašto?

Odgovor: session.update, odmah: ovdje konfiguriraš glas, upute, alate i audio format. Dok se ta poruka ne pošalje, sesija radi s zadanim vrijednostima.

3. Zašto je proxy poslužitelj ključan u produkciji?

Odgovor: Sprječava izlaganje API ključa u klijentu i omogućuje ti autentifikaciju korisnika, ograničavanje potrošnje i bilježenje poziva—tri stvari nemoguće ako preglednik izravno komunicira s API-jem.

4. Koja je svrha parametra `prompt` u API-ju za transkripciju?

Odgovor: Usmjeravanje prepoznavanja prema očekivanom rječniku: vlastita imena, brendovi, žargonski izrazi domene. Izrazi koje tamo navedeš transkribiraju se mnogo preciznije.

5. Koja je glavna poluga za percipiranu latenciju kod glasovnog agenta?

Odgovor: End-to-end streaming: reprodukcija audija čim stignu prvi fragmenti umjesto čekanja cijelog odgovora, te rukovanje prekidima kako bi korisnik mogao upasti u riječ u bilo kojem trenutku.