Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Tóg gníomhaire gutha iomlán

Ceacht 14 as 18 Nuashonraithe 3 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Tóg gníomhaire gutha iomlán
  2. Ailtireacht an ghníomhaire
  3. An rang VoiceAgent
  4. Modúl gabhála fuaime
  5. Modúl próiseála imeachtaí
  6. Modúl bainistíochta uirlisí
  7. Tosaigh an gníomhaire
  8. Príomhphointí

Nuashonraithe 2 Samhain, 2026 — Múnlaí fuaime. Tá roinnt múnlaí sa chúrsa seo tar éis dul in éag: stopfaidh tts-1, tts-1-hd, agus gpt-4o-mini-tts ar 6 Eanáir, 2027 (an t-ionadaí: gpt-realtime-2.1-mini, a deir treoir TTS OpenAI nach dtacaítear leis le /v1/audio/speech: aistrítear sintéis cainte chuig an Realtime API); stopfaidh gpt-realtime, gpt-4o-realtime, agus múnlaí fuaime oidhreachta ar 20 Eanáir, 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); stopfaidh whisper-1, gpt-4o-transcribe, agus /v1/audio/translations ar 26 Feabhra, 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Maidir le guth lán-dúbailte, tá GPT-Live 1 ar fáil san API ón 10 Meán Fómhair, 2026.

Ceartaithe 3 Samhain, 2026. Úsáideadh gpt-live-transcribe le haghaidh tras-scríbhneoireacht ionchuir, ach ní oibríonn sé ach i seisiún tras-scríbhneoireachta agus ní thacaíonn sé le server_vad ná le semantic_vad. I seisiún comhrá mar an ceann seo, áit a ndéanann VAD bailíochtú ar gach casadh, sonraíonn an doiciméadú gpt-transcribe, a thras-scríobhann casadh bailíochtaithe agus a úsáideann casadh roimhe seo mar chomhthéacs. Foincí: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.

Tóg gníomhaire gutha iomlán

Tugann an ceacht seo le chéile na coincheapa go léir a pléadh go dtí seo chun gníomhaire gutha feidhmiúil end-to-end a thógáil. Cruthóidh tú cúntóir a éisteann leis an úsáideoir, a thuigeann a iarratas, a fheidhmíonn gníomhartha, agus a fhreagraíonn le guth—go léir i bhfíor-am tríd an Realtime API.

Ailtireacht an ghníomhaire

Ceithre mhodúl, agus os a chionn sin uile, srian amháin a thiomáineann an ailtireacht iomlán: caithfidh gach rud tarlú ag an am céanna. Gabhann an micreafón fad is a fhreagraíonn an múnla, tagann imeachtaí fad is a sheinntear fuaim, agus is féidir leis an úsáideoir cur isteach ag aon nóiméad. Ní lúb ceisteanna agus freagraí é gníomhaire gutha; is córas é ina n-advancálann sruthanna iolracha go comhthreomhar—sin an fáth go mbraitheann muid go mór ar asyncio sa chuid seo a leanas.

Fuaim
Gabháil agus seinm
Seisiún
WebSocket agus cumraíocht
Uirlisí
Gníomhartha gnó
Stát
Bainistíocht comhrá

An rang VoiceAgent

Bailíonn an rang an stát a chaithfidh na sruthanna comhthreomhara seo a roinnt: an nasc, an seisiún reatha, agus an fhreagra atá á seinm faoi láthair. Go díreach toisc go rochtaineann tascanna iolracha an stát seo ag an am céanna, is fearr oibiacht ná tacar athróga domhanda—nuair a theastaíonn uait freagra atá ar siúl a chealú, caithfidh a fhios a bheith agat go bhfuil ceann ann.

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

class VoiceAgent:
    """Gníomhaire gutha iomlán bunaithe ar an 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):
        """Bunaíonn sé an nasc agus cumraíonn sé an seisiún."""
        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)

        # Fan le session.created
        event = json.loads(await self.ws.recv())
        print(f"Seisiún: {event['session']['id']}")

        # Cumraigh
        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("Gníomhaire gutha réidh.")

    async def start(self):
        """Tosaíonn sé an gníomhaire gutha."""
        await self.connect()
        await asyncio.gather(
            self._capture_audio(),
            self._process_events()
        )

Modúl gabhála fuaime

    async def _capture_audio(self):
        """Gabháil ionchur micreafóin agus seoladh chuig an 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
                }))

Modúl próiseála imeachtaí

    async def _process_events(self):
        """Próiseálann sé gach imeacht ón bhfreastalaí."""
        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"\nEarráid: {event['error']['message']}")

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

Modúl bainistíochta uirlisí

Tiontaíonn an modúl seo an gníomhaire ó chatbot gutha simplí go cúntóir atá in ann gníomhú. Is é an difríocht leis an nglao feidhme clasaiceach ná an srian ama: tá an t-úsáideoir ar an líne gan aon tháscaire dul chun cinn amhairc. Má thógann an fheidhmiú níos mó ná soicind nó dhó, bíodh an gníomhaire ag caint fad is atá sé ag obair—“Seiceálfaidh mé sin duit anois”—toisc go gciallaíonn ciúnas i gcomhrá gutha go bhfuil briseadh ann.

    async def _handle_response_done(self, event):
        """Láimhseálann sé glaoite feidhme sa fhreagra."""
        response = event["response"]
        function_calls = [
            o for o in response.get("output", [])
            if o["type"] == "function_call"
        ]

        if not function_calls:
            print()  # Líne nua tar éis tras-scríbhneoireachta
            return

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

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

            # Feidhmigh an fheidhm (oiriúnaigh do do loighic gnó)
            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)
                }
            }))

        # Iarr ar an múnla leanúint ar aghaidh
        await self.ws.send(json.dumps({"type": "response.create"}))

    async def _execute_function(self, name: str, args: dict) -> dict:
        """Seolann sé an glao feidhme."""
        # Cuir i bhfeidhm de réir do loighic gnó
        return {"error": f"Níl an fheidhm {name} curtha i bhfeidhm"}

Tosaigh an gníomhaire

async def main():
    agent = VoiceAgent(
        api_key="sk-...",
        instructions=(
            "Is cúntóir gutha tú do Corsen AI. "
            "Cabhraíonn tú le húsáideoirí a gceapacháin a bhainistiú "
            "agus faisnéis a fháil faoinár seirbhísí. "
            "Freagair i bhFraincis, go gonta agus go gairmiúil."
        ),
        tools=[
            {
                "type": "function",
                "name": "check_availability",
                "description": "Seiceálann sé infhaighteacht do shlot ama",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "date": {"type": "string"},
                        "service": {"type": "string"}
                    },
                    "required": ["date"]
                }
            }
        ]
    )

    await agent.start()

asyncio.run(main())

Príomhphointí

  • Comhcheanglaíonn gníomhaire gutha iomlán ceithre mhodúl: fuaim, seisiún, uirlisí, agus bainistíocht stáit
  • Cuimsíonn an rang VoiceAgent an loighic uile taobh thiar d’aghaidh shimplí
  • Cumasaíonn asyncio.gather gabháil micreafóin agus próiseáil imeachtaí go comhthreomhar
  • Tá láimhseáil cur isteach (freagra a chealú nuair a labhraíonn an t-úsáideoir) riachtanach
  • Tiontaíonn uirlisí an gníomhaire ó chatbot gutha simplí go cúntóir atá in ann gníomhú