Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Építs fel egy teljes hangalapú ügynököt

14. lecke 18 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Építs fel egy teljes hangalapú ügynököt
  2. Az ügynök architektúrája
  3. A VoiceAgent osztály
  4. Hangrögzítő modul
  5. Eseményfeldolgozó modul
  6. Eszközkezelő modul
  7. Az ügynök indítása
  8. Főbb megállapítások

Frissítve: 2026. november 2. – Hangmodellek. A tanfolyam több modellje elavult: a tts-1, tts-1-hd és a gpt-4o-mini-tts támogatása 2027. január 6-án megszűnik (utódjuk: gpt-realtime-2.1-mini, amelyet az OpenAI TTS útmutatója szerint a /v1/audio/speech nem támogat: a beszédszintézis migrációja a Realtime API felé történik); a gpt-realtime, gpt-4o-realtime és a régi hangmodellek támogatása 2027. január 20-án szűnik meg (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); a whisper-1, gpt-4o-transcribe és a /v1/audio/translations végpontok használata 2027. február 26-án jár le (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). A teljes duplex hangkommunikációhoz a GPT-Live 1 már 2026. szeptember 10. óta elérhető az API-ban.

Helyesbítve: 2026. november 3. A bemeneti átírás korábban a gpt-live-transcribe modellt használta, amely kizárólag átírási munkamenetben működik, és nem támogatja sem a server_vad, sem a semantic_vad funkciót. Egy ilyen beszélgetési munkamenetben, ahol a VAD (Voice Activity Detection) minden fordulót érvényesít, a dokumentáció a gpt-transcribe használatát írja elő, amely az érvényesített fordulókat írja át, és a korábbi fordulókat kontextusként kezeli. Források: Valós idejű átírás · GPT-Transcribe · GPT-Live-Transcribe.

Építs fel egy teljes hangalapú ügynököt

Ez a lecke összefogja az eddig tárgyalt összes fogalmat, hogy felépíts egy teljesen működőképes, végpontok közötti hangalapú ügynököt. Létrehozol egy asszisztenst, amely figyeli a felhasználót, megérti a kéréseit, végrehajtja a műveleteket, és hangon válaszol – mindezt valós időben, a Realtime API-n keresztül.

Az ügynök architektúrája

Négy modul, és mindenekelőtt egy kényszerítő erő, amely az egész architektúrát meghatározza: mindennek egyszerre kell történnie. A mikrofon rögzít, miközben a modell válaszol; események érkeznek, miközben a hang lejátszása zajlik; és a felhasználó bármikor megszakíthatja a folyamatot. Egy hangalapú ügynök nem egyszerű kérdés-válasz ciklus; ez egy rendszer, ahol több adatfolyam halad párhuzamosan – ezért támaszkodunk erősen az asyncio használatára a következőkben.

Hang
Rögzítés és lejátszás
Munkamenet
WebSocket és konfiguráció
Eszközök
Üzleti műveletek
Állapot
Beszélgetés-kezelés

A VoiceAgent osztály

Az osztály gyűjti össze azt az állapotot, amelyet ezeknek a párhuzamos adatfolyamoknak meg kell osztaniuk: a kapcsolatot, az aktuális munkamenetet és a éppen lejátszás alatt álló választ. Pontosan azért, mert több feladat fér hozzá egyszerre ehhez az állapothoz, egy objektum előnyösebb, mint a globális változók halmaza – amikor meg kell szakítanod egy folyamatban lévő választ, tudnod kell, hogy létezik ilyen.

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

class VoiceAgent:
    """Teljes hangalapú ügynök a Realtime API alapján."""

    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):
        """Létrehozza a kapcsolatot és konfigurálja a munkamenetet."""
        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)

        # Várakozás a session.created eseményre
        event = json.loads(await self.ws.recv())
        print(f"Munkamenet: {event['session']['id']}")

        # Konfiguráció
        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("Hangalapú ügynök készen áll.")

    async def start(self):
        """Elindítja a hangalapú ügynököt."""
        await self.connect()
        await asyncio.gather(
            self._capture_audio(),
            self._process_events()
        )

Hangrögzítő modul

    async def _capture_audio(self):
        """Rögzíti a mikrofon bemenetét és elküldi a Realtime API-nak."""
        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
                }))

Eseményfeldolgozó modul

    async def _process_events(self):
        """Feldolgozza az összes eseményt a szerverről."""
        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"\nHiba: {event['error']['message']}")

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

Eszközkezelő modul

Ez a modul alakítja át az ügynököt egy egyszerű hangalapú chatbottól egy cselekvésre képes asszisztenssé. A klasszikus függvényhívástól való eltérés az időzítési kényszerben rejlik: a felhasználó a vonalban van, vizuális folyamatjelző nélkül. Ha a végrehajtás több mint egy-két másodpercig tart, beszéltessd az ügynököt munka közben – „Hadd ellenőrizzem ezt önnek most“ –, mert a csend egy hangalapú beszélgetésben hibának vagy leállásnak tűnik.

    async def _handle_response_done(self, event):
        """Kezeli a válaszban lévő függvényhívásokat."""
        response = event["response"]
        function_calls = [
            o for o in response.get("output", [])
            if o["type"] == "function_call"
        ]

        if not function_calls:
            print()  # Új sor az átírás után
            return

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

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

            # Függvény végrehajtása (igazítsd az üzleti logikádhoz)
            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)
                }
            }))

        # Kérd meg a modellt a folytatásra
        await self.ws.send(json.dumps({"type": "response.create"}))

    async def _execute_function(self, name: str, args: dict) -> dict:
        """Kézbesíti a függvényhívást."""
        # Implementáld az üzleti logikád szerint
        return {"error": f"A(z) {name} függvény nincs implementálva"}

Az ügynök indítása

async def main():
    agent = VoiceAgent(
        api_key="sk-...",
        instructions=(
            "Te a Corsen AI hangalapú asszisztense vagy. "
            "Segítesz a felhasználóknak az időpontfoglalásban "
            "és információkat adsz szolgáltatásainkról. "
            "Válaszolj franciául, tömören és professzionálisan."
        ),
        tools=[
            {
                "type": "function",
                "name": "check_availability",
                "description": "Ellenőrzi a rendelkezésre állást egy adott időpontra",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "date": {"type": "string"},
                        "service": {"type": "string"}
                    },
                    "required": ["date"]
                }
            }
        ]
    )

    await agent.start()

asyncio.run(main())

Főbb megállapítások

  • Egy teljes hangalapú ügynök négy modult kombinál: hang, munkamenet, eszközök és állapotkezelés
  • A VoiceAgent osztály egy egyszerű felület mögé zárja az összes logikát
  • Az asyncio.gather lehetővé teszi a mikrofon rögzítésének és az eseményfeldolgozásnak a párhuzamos futtatását
  • A megszakítások kezelése (a válasz megszakítása, amikor a felhasználó megszólal) elengedhetetlen
  • Az eszközök alakítják át az ügynököt egy egyszerű hangalapú chatbottól egy cselekvésre képes asszisztenssé