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

Rakenna täydellinen puheagentti

Oppitunti 14 / 18 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Rakenna täydellinen puheagentti
  2. Agentin arkkitehtuuri
  3. VoiceAgent-luokka
  4. Äänen sieppausmoduuli
  5. Tapahtumien käsittelymoduuli
  6. Työkalujen hallintamoduuli
  7. Käynnistä agentti
  8. Keskeiset asiat

Päivitetty 2. marraskuuta 2026 — Äänimallit. Useat tämän kurssin malleista on vanhentumassa: tts-1, tts-1-hd ja gpt-4o-mini-tts lakkaavat toimimasta 6. tammikuuta 2027 (seuraaja: gpt-realtime-2.1-mini, jonka OpenAI:n TTS-opas ilmoittaa ei tukevan /v1/audio/speech: puheentuotto siirtyy Realtime API:n piiriin); 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 puheenvuoroa varten GPT-Live 1 on ollut saatavilla rajapinnassa 10. syyskuuta 2026 lähtien.

Korjattu 3. marraskuuta 2026. Syötteen litterointi käytti mallia gpt-live-transcribe, joka toimii vain litterointi-istunnossa eikä tue server_vad- eikä semantic_vad-toimintoja. Tämän kaltaisessa keskusteluistunnossa, jossa VAD vahvistaa jokaisen vuoron, dokumentaatio määrää käyttämään mallia gpt-transcribe, joka litteroi vahvistetut vuorot ja hyödyntää aiempia vuoroja kontekstina. Lähteet: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.

Rakenna täydellinen puheagentti

Tässä oppitunnissa yhdistämme kaikki tähän mennessä käsitellyt konseptit toimivan, päästä päähän ulottuvan puheagentin rakentamiseksi. Luot assistentin, joka kuuntelee käyttäjää, ymmärtää pyynnöt, suorittaa toimintoja ja vastaa äänellä – kaikki reaaliajassa Realtime API:n kautta.

Agentin arkkitehtuuri

Neljä moduulia ja ennen kaikkea yksi rajoite, joka ohjaa koko arkkitehtuuria: kaiken on tapahduttava samanaikaisesti. Mikrofoni tallentaa mallin vastatessa, tapahtumat saapuvat äänen toistuessa, ja käyttäjä voi keskeyttää milloin tahansa. Puheagentti ei ole kysymys-vastaus-silmukka; se on järjestelmä, jossa useat virrat etenevät rinnakkain – minkä vuoksi nojaamme seuraavassa vahvasti asyncio:hon.

Audio
Sieppaus ja toisto
Istunto
WebSocket ja konfiguraatio
Työkalut
Liiketoimintatoiminnot
Tila
Keskustelun hallinta

VoiceAgent-luokka

Luokka kokoaa yhteen tilan, jota näiden rinnakkaisten virtojen on jaettava: yhteyden, nykyisen istunnon ja parhaillaan toistettavan vastauksen. Juuri siksi, että useat tehtävät käyttävät tätä tilaa samanaikaisesti, olio on parempi vaihtoehto kuin joukko globaaleja muuttujia – kun sinun on peruutettava käynnissä oleva vastaus, sinun on tiedettävä sellaisen olevan olemassa.

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

class VoiceAgent:
    """Täydellinen puheagentti Realtime API:n pohjalta."""

    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):
        """Muodostaa yhteyden ja määrittää istunnon."""
        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)

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

        # Määritä
        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("Puheagentti valmiina.")

    async def start(self):
        """Käynnistää puheagentin."""
        await self.connect()
        await asyncio.gather(
            self._capture_audio(),
            self._process_events()
        )

Äänen sieppausmoduuli

    async def _capture_audio(self):
        """Sieppaa mikrofonisyötteen ja lähettää sen Realtime API:lle."""
        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
                }))

Tapahtumien käsittelymoduuli

    async def _process_events(self):
        """Käsittelee kaikki palvelimelta tulevat tapahtumat."""
        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"\nVirhe: {event['error']['message']}")

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

Työkalujen hallintamoduuli

Tämä moduuli muuttaa agentin yksinkertaisesta puhekeskustelubotista toimia pystyväksi assistentiksi. Ero perinteiseen funktiokutsuun liittyy aikarajoitteeseen: käyttäjä on linjalla ilman visuaalista edistymisindikaattoria. Jos suoritus kestää yli sekunnin tai kaksi, saa agentin puhumaan työn aikana – “Tarkistan tämän sinulle heti” – sillä hiljaisuus puhekeskustelussa kuulostaa katkokselta.

    async def _handle_response_done(self, event):
        """Käsittelee vastauksen funktiokutsut."""
        response = event["response"]
        function_calls = [
            o for o in response.get("output", [])
            if o["type"] == "function_call"
        ]

        if not function_calls:
            print()  # Uusi rivi litteroinnin jälkeen
            return

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

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

            # Suorita funktio (sovita liiketoimintalogiikkaasi)
            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)
                }
            }))

        # Pyydä mallia jatkamaan
        await self.ws.send(json.dumps({"type": "response.create"}))

    async def _execute_function(self, name: str, args: dict) -> dict:
        """Ohjaa funktiokutsun eteenpäin."""
        # Toteuta liiketoimintalogiikkasi mukaan
        return {"error": f"Funktiota {name} ei ole toteutettu"}

Käynnistä agentti

async def main():
    agent = VoiceAgent(
        api_key="sk-...",
        instructions=(
            "Olet Corsen AI:n puheassistentti. "
            "Autat käyttäjiä hallitsemaan tapaamisiaan "
            "ja saamaan tietoa palveluistamme. "
            "Vastaa ranskaksi, ytimekkäästi ja ammattimaisesti."
        ),
        tools=[
            {
                "type": "function",
                "name": "check_availability",
                "description": "Tarkistaa saatavuuden aikavälille",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "date": {"type": "string"},
                        "service": {"type": "string"}
                    },
                    "required": ["date"]
                }
            }
        ]
    )

    await agent.start()

asyncio.run(main())

Keskeiset asiat

  • Täydellinen puheagentti yhdistää neljä moduulia: äänen, istunnon, työkalut ja tilanhallinnan
  • VoiceAgent-luokka kapseloi koko logiikan yksinkertaisen käyttöliittymän taakse
  • asyncio.gather mahdollistaa mikrofonin sieppauksen ja tapahtumien käsittelyn rinnakkain
  • Keskeytysten käsittely (vastauksen peruuttaminen käyttäjän puhuessa) on välttämätöntä
  • Työkalut muuttavat agentin yksinkertaisesta puhekeskustelubotista toimia pystyväksi assistentiksi