Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Tuotanto: skaalaus ja valvonta

Oppitunti 18 / 18 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Tuotanto: skaalaus ja valvonta
  2. Tuotantoarkkitehtuuri
  3. Samanaikaisten istuntojen hallinta
  4. Jäsennelty lokitus
  5. Prometheus-mittarit
  6. Kulujen hallinta
  7. Tuotannon virheenkäsittely
  8. Keskeiset asiat
  9. Testaa tietosi

Päivitetty 2. marraskuuta 2026 — Äänimallit. Useat tämän kurssin malleista on poistettu käytöstä: tts-1, tts-1-hd ja gpt-4o-mini-tts lakkaavat toimimasta 6. tammikuuta 2027 (korvaaja: gpt-realtime-2.1-mini, jonka OpenAI:n TTS-opas ilmoittaa ei tuetun /v1/audio/speech-päätepistettä: puhesynteesin migraation on kuljettava Realtime API:n kautta); gpt-realtime, gpt-4o-realtime ja vanhat äänimallit 20. tammikuuta 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe ja /v1/audio/translations 26. helmikuuta 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Täysdupleksista ääntä varten GPT-Live 1 on ollut saatavilla API:ssa 10. syyskuuta 2026 lähtien.

Päivitetty 3. marraskuuta 2026. Kulujen hallinta mahtui aiemmin yhteen lauseeseen; nyt se heijastaa OpenAI:n kuvaamaa laskutusmallia (laskutus vastauksittain, keskustelu palautetaan joka vuorolla, ääni lasketaan tokeneina, automaattinen välimuisti, transkriptio laskutetaan erikseen) ja typistystä retention_ratio-parametrin kautta, jonka muoto varmistettiin openai SDK -tyyppien versiosta 3.42.1. Lähde: Cost optimization.

Tuotanto: skaalaus ja valvonta

Siirtyminen ääniagentin prototyypistä luotettavaan, skaalautuvaan tuotantopalveluun vaatii tarkkaa huomiota infrastruktuuriin, valvontaan ja virheenkäsittelyyn. Tämä viimeinen oppitunti kattaa ääniagentin käyttöönoton operatiiviset perusasiat reaaliolosuhteissa.

Tuotantoarkkitehtuuri

Tuotannossa ääniagentti toimii kuormantasaimen ja työntekijäpoolin takana:

1

Kuormantasain (nginx / HAProxy)

Jakaa saapuvat WebSocket-yhteydet työntekijöiden kesken. Tukee sticky session -toimintoa affiniteetin ylläpitämiseksi.

2

Työntekijät (FastAPI + uvicorn)

Jokainen työntekijä käsittelee useita samanaikaisia Realtime-istuntoja asyncio:n ansiosta.

3

Tietokanta (PostgreSQL)

Tallentaa keskustelulokit, mittarit ja agentin konfiguraation.

4

Valvonta (Prometheus + Grafana)

Kerää reaaliaikaisia mittareita: viive, istuntomäärä, virheet, kustannukset.

Samanaikaisten istuntojen hallinta

Jokainen WebSocket-yhteys ylläpitää Realtime API -istuntoa. Samanaikaisten istuntojen määrää rajoittavat OpenAI:n nopeusrajoituksesi ja työntekijöidesi kapasiteetti:

import asyncio
from dataclasses import dataclass

@dataclass
class SessionManager:
    """Hallitsee samanaikaisia Realtime API -istuntoja."""
    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):
        """Luo uuden istunnon samanaikaisuuden hallinnalla."""
        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):
        """Sulkee istunnon asianmukaisesti."""
        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)

Jäsennelty lokitus

Lokita jokainen vuorovaikutus vianetsintää ja vaatimustenmukaisuutta varten:

import logging
import json
from datetime import datetime

class ConversationLogger:
    """Jäsennelty lokittaja äänikeskusteluille."""

    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):
        """Tallentaa koko lokin tietokantaan."""
        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-mittarit

Altista mittarit reaaliaikaista valvontaa varten:

from prometheus_client import Counter, Histogram, Gauge, start_http_server

# Keskeiset mittarit
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
)

# Käynnistä mittaripalvelin
start_http_server(9090)

Kulujen hallinta

OpenAI:n Cost optimization -oppaan mukaan Realtime-keskusteluistunto laskutetaan vastauksittain teksti-, ääni- ja kuvatokeneina syötteessä ja tulosteessa. Kolme mekanismia ajaa suurimman osan laskusta:

  • Koko keskustelu lähetetään takaisin mallille jokaisella vastauksella: myöhemmät vuorot maksavat enemmän kuin aikaisemmat.
  • Ääni lasketaan tokeneina: 1 token per 100 ms käyttäjän ääntä, 1 token per 50 ms avustajan ääntä.
  • Kehotteen välimuisti (prompt caching) toimii automaattisesti: niin kauan kuin keskustelun alku ei muutu, se laskutetaan alennetulla välimuistitetun tokenin hinnalla. Vanhemman elementin muuttaminen tai poistaminen “rikko” välimuistin siitä kohdasta eteenpäin.

Syötteen transkriptio, jos se on käytössä, laskutetaan erikseen oman mallinsa hinnalla: gpt-transcribe veloitetaan keston perusteella, joka luetaan tapahtumasta conversation.item.input_audio_transcription.completed. Kulutus jokaiselle vastaukselle näkyy kohdassa response.done, under response.usage (total_tokens, input_tokens, output_tokens, plus erittely tekstille, äänelle, kuvalle ja välimuistille).

Kontekstin koon – ja siten myöhempien vuorojen kustannusten – rajoittamiseksi istunto hyväksyy typistyssäännön: rajan ylittyessä vanhimmat viestit pudotetaan. Kun retention_ratio on asetettu alle arvon 1, palvelin poistaa hieman enemmän kuin on tarpeen, mikä harventaa typistyksiä ja säilyttää välimuistin:

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

Kauppa on seuraava: vähemmän kontekstia säilyttävä agentti unohtaa nopeammin. Täydennä tätä istuntorajoituksilla koodissasi:

class CostController:
    """Hallitsee Realtime-istunnon kustannuksia."""

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

Tuotannon virheenkäsittely

async def production_event_loop(ws, logger, cost_ctrl):
    """Vankka tapahtumasilmukka tuotantoon."""
    cost_ctrl.start()

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

            # Tarkista kustannusrajat
            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()

Keskeiset asiat

  • Tuotantoarkkitehtuuri erottaa kuormantasaimen, asyncio-työntekijät, tietokannan ja valvonnan
  • SessionManager puolijohteella (semaphore) hallitsee samanaikaisten istuntojen määrää
  • JSON-muotoinen jäsennelty lokitus mahdollistaa vianetsinnän ja vaatimustenmukaisuuden (keskustelun tallennus)
  • Prometheus-mittarit (TTFA, kesto, tokenit, virheet) ovat välttämättömiä päivittäiselle toiminnalle
  • CostController rajoittaa istunnon kestoa ja tokeneja budjetin ylitysten estämiseksi

Testaa tietosi

Viisi kysymystä kattaa koko ääniketjun WebSocketista tuotantokäyttöönottoon.

1. Miksi Realtime API käyttää WebSocketia HTTP-pyyntöjen sijaan?

Vastaus: Koska pysyvä, kaksisuuntainen yhteys mahdollistaa mikrofonin äänen suoratoiston ja vastausten vastaanoton jatkuvasti ilman jokaisen vaihdon pyynnön muodostamisen aiheuttamaa kuormitusta. Tämä on edellytys pieniviiveiselle keskustelulle.

2. Mitä sinun on lähetettävä välittömästi `session.created`-tapahtuman jälkeen ja miksi?

Vastaus: session.update, välittömästi: tässä määrität äänen, ohjeet, työkalut ja äänimuodon. Ennen tämän viestin lähettämistä istunto toimii oletusarvoilla.

3. Miksi välityspalvelin (proxy) on välttämätön tuotannossa?

Vastaus: Se estää API-avaimen paljastumisen asiakaspuolella ja mahdollistaa käyttäjän todentamisen, kulutuksen rajoittamisen sekä puhelujen lokittamisen – kolme asiaa, jotka ovat mahdottomia, jos selain keskustelee suoraan API:n kanssa.

4. Mikä on `prompt`-parametrin tarkoitus transkriptio-API:ssa?

Vastaus: Ohjata tunnistusta odotettuun sanastoon: erisnimet, brändit, alan jargon. Siinä luetellut termit transkriptoidaan huomattavasti tarkemmin.

5. Mikä on ääniagentin koetun viiveen päävipu?

Vastaus: End-to-end-suoratoisto: äänen toistaminen heti ensimmäisten osien saavuttua koko vastauksen odottamisen sijaan ja keskeytysten käsittely, jotta käyttäjä voi puuttua puheeseen milloin tahansa.