Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Ehita täielik hääleagent

Õppetund 14 / 18 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Ehita täielik hääleagent
  2. Agendi arhitektuur
  3. Klass VoiceAgent
  4. Audio salvestamise moodul
  5. Sündmuste töötlemise moodul
  6. Tööriistade haldamise moodul
  7. Agendi käivitamine
  8. Peamised punktid

Uuendatud 2. novembril 2026 – Audiomudelid. Selles kursuses on mitu mudelit aegunud: tts-1, tts-1-hd ja gpt-4o-mini-tts lõpetavad töö 6. jaanuaril 2027 (järeltulija: gpt-realtime-2.1-mini, mida OpenAI TTS-i juhend kirjeldab kui mittetoetatud teenuse /v1/audio/speech poolt: kõnesünteesi migratsioon liigub Realtime API-le); gpt-realtime, gpt-4o-realtime ja vanad audiomudelid 20. jaanuaril 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe ja /v1/audio/translations 26. veebruaril 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Täisdupleksse kõne jaoks on GPT-Live 1 olnud API-s saadaval alates 10. septembrist 2026.

Parandatud 3. novembril 2026. Sisendi transkriptsioon kasutas mudelit gpt-live-transcribe, mis toimib ainult transkriptsiooni sessioonis ega toeta ei server_vad ega semantic_vad. Sellises vestlussessioonis, kus VAD valideerib iga pöörde, määratleb dokumentatsioon mudeli gpt-transcribe, mis transkribeerib valideeritud pöörded ja kasutab eelmisi pöördeid kontekstina. Allikad: Reaalaja transkriptsioon · GPT-Transcribe · GPT-Live-Transcribe.

Ehita täielik hääleagent

See õppetund ühendab kõik seni käsitletud mõisted, et luua täielikult toimiv ots-otsani hääleagent. Lood assistendi, kes kuulab kasutajat, mõistab tema soovi, täidab toiminguid ja vastab häälega – kõik reaalajas Realtime API kaudu.

Agendi arhitektuur

Neli moodulit ja ennenägematu piirang, mis juhib kogu arhitektuuri: kõik peab toimuma samaaegselt. Mikrofon salvestab samal ajal, kui mudel vastab, sündmused saabuvad samal ajal, kui heli mängib, ja kasutaja võib katkestada igal hetkel. Hääleagent ei ole küsimuste ja vastuste tsükkel; see on süsteem, kus mitu voogu edenevad paralleelselt – seetõttu tuginevad järgnevad lahendused tugevalt asyncio-le.

Audio
Salvestamine ja taasesitus
Sessioon
WebSocket ja konfiguratsioon
Tööriistad
Äritegevused
Olek
Vestluse haldamine

Klass VoiceAgent

See klass koondab oleku, mida need paralleelsed vood peavad jagama: ühenduse, praeguse sessiooni ja parasjagu esitatava vastuse. Just seetõttu, et mitu ülesannet pääsevad sellele olekule samaaegselt ligi, on objekt eelistatud globaalsete muutujate hulgale – kui pead tühistama käimasolevat vastust, pead teadma, et see eksisteerib.

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

class VoiceAgent:
    """Täielik hääleagent, mis põhineb Realtime API-l."""

    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):
        """Loob ühenduse ja konfigureerib sessiooni."""
        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)

        # Oota session.created
        event = json.loads(await self.ws.recv())
        print(f"Sessioon: {event['session']['id']}")

        # Konfigureeri
        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("Hääleagent on valmis.")

    async def start(self):
        """Käivitab hääleagendi."""
        await self.connect()
        await asyncio.gather(
            self._capture_audio(),
            self._process_events()
        )

Audio salvestamise moodul

    async def _capture_audio(self):
        """Salvestab mikrofonisisendi ja saadab selle Realtime API-le."""
        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
                }))

Sündmuste töötlemise moodul

    async def _process_events(self):
        """Töötleb kõik serverilt saabuvad sündmused."""
        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"\nViga: {event['error']['message']}")

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

Tööriistade haldamise moodul

See moodul muudab agendi lihtsast häälechatbotist assistendiks, kes suudab tegutseda. Erinevus klassikalisest funktsioonide kutsumisest seisneb ajapiirangus: kasutaja on liinil ilma visuaalse edenemisnäidikuta. Kui täitmine võtab rohkem kui sekundi või kaks, pane agent rääkima töö tegemise ajal – „Kontrollin seda teie jaoks kohe“ –, sest vaikus häälevestluses kõlab nagu tõrge.

    async def _handle_response_done(self, event):
        """Haldab vastuses olevaid funktsioonikutsunguid."""
        response = event["response"]
        function_calls = [
            o for o in response.get("output", [])
            if o["type"] == "function_call"
        ]

        if not function_calls:
            print()  # Uus rida pärast transkriptsiooni
            return

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

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

            # Täida funktsioon (kohanda oma äriloogikaga)
            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)
                }
            }))

        # Palu mudelil jätkata
        await self.ws.send(json.dumps({"type": "response.create"}))

    async def _execute_function(self, name: str, args: dict) -> dict:
        """Suunab funktsioonikutsungi."""
        # Rakenda vastavalt oma äriloogikale
        return {"error": f"Funktsioon {name} on realiseerimata"}

Agendi käivitamine

async def main():
    agent = VoiceAgent(
        api_key="sk-...",
        instructions=(
            "Oled Corsen AI hääleassistent. "
            "Aidad kasutajatel hallata oma kohtumisi "
            "ja saada teavet meie teenuste kohta. "
            "Vasta prantsuse keeles, lakooniliselt ja professionaalselt."
        ),
        tools=[
            {
                "type": "function",
                "name": "check_availability",
                "description": "Kontrollib saadavust ajavahemiku jaoks",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "date": {"type": "string"},
                        "service": {"type": "string"}
                    },
                    "required": ["date"]
                }
            }
        ]
    )

    await agent.start()

asyncio.run(main())

Peamised punktid

  • Täielik hääleagent ühendab neli moodulit: audio, sessioon, tööriistad ja olekuhaldus
  • Klass VoiceAgent kapseldab kogu loogika lihtsa liidese taha
  • asyncio.gather võimaldab mikrofoni salvestamist ja sündmuste töötlemist paralleelselt
  • Katkestuste käsitlemine (vastuse tühistamine, kui kasutaja räägib) on hädavajalik
  • Tööriistad muudavad agendi lihtsast häälechatbotist tegutsemisvõimeliseks assistendiks