Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Vytvor kompletného hlasového agenta

Lekcia 14 z 18 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Vytvor kompletného hlasového agenta
  2. Architektúra agenta
  3. Trieda VoiceAgent
  4. Modul snímania zvuku
  5. Modul spracovania udalostí
  6. Modul správy nástrojov
  7. Spustenie agenta
  8. Kľúčové poznatky

Aktualizované 2. novembra 2026 — Zvukové modely. Niektoré modely v tomto kurze sú zastarané: tts-1, tts-1-hd a gpt-4o-mini-tts prestanú fungovať 6. januára 2027 (nástupca: gpt-realtime-2.1-mini, ktorý podľa príručky OpenAI TTS nie je podporovaný rozhraním /v1/audio/speech: migrácia syntézy reči prechádza na Realtime API); gpt-realtime, gpt-4o-realtime a staršie zvukové modely skončia 20. januára 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe a /v1/audio/translations skončia 26. februára 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Pre plno duplexný hlas je GPT-Live 1 dostupný v API od 10. septembra 2026.

Opravené 3. novembra 2026. Vstupný prepis používal gpt-live-transcribe, ktorý funguje len v relácii typu transcription a nepodporuje ani server_vad, ani semantic_vad. V konverzačnej relácii, ako je táto, kde VAD overuje každý obrat, dokumentácia špecifikuje použitie gpt-transcribe, ktorý prepisuje overené obraty a využíva predchádzajúce obraty ako kontext. Zdroje: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.

Vytvor kompletného hlasového agenta

Táto lekcia spája všetky doteraz prebrané koncepty do funkčného end-to-end hlasového agenta. Vytvoríš asistenta, ktorý počúva používateľa, rozumie jeho požiadavkám, vykonáva akcie a odpovedá hlasom – všetko v reálnom čase prostredníctvom Realtime API.

Architektúra agenta

Štyri moduly a predovšetkým jedno obmedzenie, ktoré určuje celú architektúru: všetko sa musí diať naraz. Mikrofón sníma, zatiaľ čo model odpovedá, udalosti prichádzajú, zatiaľ čo sa prehráva zvuk, a používateľ môže prerušiť komunikáciu kedykoľvek. Hlasový agent nie je sluška otázka-odpoveď; je to systém, v ktorom viaceré toky prebiehajú paralelne – preto sa v nasledujúcich častiach silno spoliehame na asyncio.

Audio
Snímanie a prehrávanie
Relácia
WebSocket a konfigurácia
Nástroje
Obchodné akcie
Stav
Správa konverzácie

Trieda VoiceAgent

Táto trieda zhromažďuje stav, ktorý musia tieto paralelné toky zdieľať: pripojenie, aktuálnu reláciu a práve prehrávanú odpoveď. Práve preto, že k tomuto stavu pristupuje viacero úloh súčasne, je objekt vhodnejší ako sada globálnych premenných – keď potrebuješ zrušiť prebiehajúcu odpoveď, musíš vedieť, že existuje.

import asyncio
import json
import base64
import websockets
import sounddevice as sd
import numpy as np
import pyaudio

class VoiceAgent:
    """Kompletný hlasový agent založený na Realtime API."""

    def __init__(self, api_key: str, instructions: str, tools: list = None):
        self.api_key = api_key
        self.instructions = instructions
        self.tools = tools or []
        self.ws = None
        self.is_playing = False
        self.sample_rate = 24000
        self.chunk_size = 2400  # 100ms

    async def connect(self):
        """Nadviaže pripojenie a nakonfiguruje reláciu."""
        url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1"
        headers = {
            "Authorization": f"Bearer {self.api_key}"
        }

        self.ws = await websockets.connect(url, additional_headers=headers)

        # Počkaj na session.created
        event = json.loads(await self.ws.recv())
        print(f"Relácia: {event['session']['id']}")

        # Konfigurácia
        await self.ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "type": "realtime",
                "output_modalities": ["audio"],
                "instructions": self.instructions,
                "audio": {
                    "input": {
                        "format": {"type": "audio/pcm", "rate": 24000},
                        "transcription": {"model": "gpt-transcribe", "languages": ["fr"]},
                        "turn_detection": {
                            "type": "server_vad",
                            "threshold": 0.5,
                            "silence_duration_ms": 600
                        }
                    },
                    "output": {
                        "format": {"type": "audio/pcm", "rate": 24000},
                        "voice": "marin"
                    }
                },
                "tools": self.tools,
                "tool_choice": "auto"
            }
        }))

        await self.ws.recv()  # session.updated
        print("Hlasový agent je pripravený.")

    async def start(self):
        """Spustí hlasového agenta."""
        await self.connect()
        await asyncio.gather(
            self._capture_audio(),
            self._process_events()
        )

Modul snímania zvuku

    async def _capture_audio(self):
        """Sníma vstup z mikrofónu a odosiela ho do Realtime API."""
        loop = asyncio.get_event_loop()
        queue = asyncio.Queue()

        def callback(indata, frames, time_info, status):
            pcm = (indata[:, 0] * 32767).astype(np.int16)
            loop.call_soon_threadsafe(queue.put_nowait, pcm)

        stream = sd.InputStream(
            samplerate=self.sample_rate,
            channels=1,
            dtype="float32",
            blocksize=self.chunk_size,
            callback=callback
        )

        with stream:
            while True:
                pcm_data = await queue.get()
                audio_b64 = base64.b64encode(pcm_data.tobytes()).decode()
                await self.ws.send(json.dumps({
                    "type": "input_audio_buffer.append",
                    "audio": audio_b64
                }))

Modul spracovania udalostí

    async def _process_events(self):
        """Spracúva všetky udalosti zo servera."""
        pa = pyaudio.PyAudio()
        player = pa.open(
            format=pyaudio.paInt16, channels=1,
            rate=self.sample_rate, output=True
        )

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

                if t == "response.output_audio.delta":
                    audio = base64.b64decode(event["delta"])
                    player.write(audio)
                    self.is_playing = True

                elif t == "response.output_audio.done":
                    self.is_playing = False

                elif t == "response.output_audio_transcript.delta":
                    print(event["delta"], end="", flush=True)

                elif t == "input_audio_buffer.speech_started":
                    if self.is_playing:
                        await self.ws.send(json.dumps({
                            "type": "response.cancel"
                        }))
                        self.is_playing = False

                elif t == "response.done":
                    await self._handle_response_done(event)

                elif t == "error":
                    print(f"\nChyba: {event['error']['message']}")

        finally:
            player.close()
            pa.terminate()

Modul správy nástrojov

Tento modul mení agenta z jednoduchého hlasového chatbota na asistenta schopného konať. Rozdiel oproti klasickému volaniu funkcií spočíva v časovom obmedzení: používateľ je na linke bez vizuálneho indikátora priebehu. Ak vykonávanie trvá viac ako sekundu alebo dve, nechaj agenta hovoriť, zatiaľ čo pracuje – „Dovoľte mi to hneď skontrolovať“ – pretože ticho v hlasovej konverzácii pôsobí ako výpadok.

    async def _handle_response_done(self, event):
        """Spracúva volania funkcií v odpovedi."""
        response = event["response"]
        function_calls = [
            o for o in response.get("output", [])
            if o["type"] == "function_call"
        ]

        if not function_calls:
            print()  # Nový riadok po prepise
            return

        for call in function_calls:
            name = call["name"]
            args = json.loads(call["arguments"])
            call_id = call["call_id"]

            print(f"\n→ {name}({args})")

            # Vykonaj funkciu (prispôsob svojej obchodnej logike)
            result = await self._execute_function(name, args)

            await self.ws.send(json.dumps({
                "type": "conversation.item.create",
                "item": {
                    "type": "function_call_output",
                    "call_id": call_id,
                    "output": json.dumps(result)
                }
            }))

        # Požiadaj model o pokračovanie
        await self.ws.send(json.dumps({"type": "response.create"}))

    async def _execute_function(self, name: str, args: dict) -> dict:
        """Smeruje volanie funkcie."""
        # Implementuj podľa svojej obchodnej logiky
        return {"error": f"Funkcia {name} nie je implementovaná"}

Spustenie agenta

async def main():
    agent = VoiceAgent(
        api_key="sk-...",
        instructions=(
            "Si hlasový asistent pre Corsen AI. "
            "Pomáhaš používateľom spravovať ich stretnutia "
            "a získavať informácie o našich službách. "
            "Odpovedaj po francúzsky, stručne a profesionálne."
        ),
        tools=[
            {
                "type": "function",
                "name": "check_availability",
                "description": "Skontroluje dostupnosť časového slotu",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "date": {"type": "string"},
                        "service": {"type": "string"}
                    },
                    "required": ["date"]
                }
            }
        ]
    )

    await agent.start()

asyncio.run(main())

Kľúčové poznatky

  • Kompletný hlasový agent kombinuje štyri moduly: audio, reláciu, nástroje a správu stavu
  • Trieda VoiceAgent zapuzdruje celú logiku za jednoduché rozhranie
  • asyncio.gather umožňuje paralelné snímanie mikrofónu a spracovanie udalostí
  • Spracovanie prerušení (zrušenie odpovede, keď používateľ začne hovoriť) je nevyhnutné
  • Nástroje menia agenta z jednoduchého hlasového chatbota na asistenta schopného konať