Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Sukurkite išsamų balso agentą

Paskaita 14 iš 18 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. Sukurkite išsamų balso agentą
  2. Agento architektūra
  3. Klasė „VoiceAgent“
  4. Garso fiksavimo modulis
  5. Įvykių apdorojimo modulis
  6. Įrankių valdymo modulis
  7. Agento paleidimas
  8. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 2 d. — Garso modeliai. Keli šio kurso modeliai yra pasenę: tts-1, tts-1-hd ir gpt-4o-mini-tts nustos veikti 2027 m. sausio 6 d. (įpėdinis: gpt-realtime-2.1-mini, kurio, kaip nurodo „OpenAI“ TTS gidas, nepalaiko /v1/audio/speech: kalbos sintezės migracija perkeliama į „Realtime API“); gpt-realtime, gpt-4o-realtime ir senieji garso modeliai nustos veikti 2027 m. sausio 20 d. (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe ir /v1/audio/translations nustos veikti 2027 m. vasario 26 d. (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Pilno dublekso balsui „GPT-Live 1“ API buvo prieinamas nuo 2026 m. rugsėjo 10 d.

Ištaisyta 2026 m. lapkričio 3 d. Įvesties transkripcijai buvo naudojamas gpt-live-transcribe, kuris veikia tik transkripcijos sesijoje ir nepalaiko nei server_vad, nei semantic_vad. Pokalbio sesijoje, kaip ši, kurioje VAD patvirtina kiekvieną ėjimą, dokumentacijoje nurodoma naudoti gpt-transcribe, kuris transkribuoja patvirtintus ėjimus ir naudoja ankstesnius ėjimus kaip kontekstą. Šaltiniai: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.

Sukurkite išsamų balso agentą

Šioje pamokoje sujungsime visas iki šiol nagrinėtas sąvokas, kad sukurtume visiškai veikiantį balso agentą nuo pradžių iki galo. Sukursite asistentą, kuris klauso naudotojo, supranta jo prašymą, vykdo veiksmus ir atsako balsu – visa tai realiuoju laiku naudojant „Realtime API“.

Agento architektūra

Keturi moduliai ir viena pagrindinė sąlyga, lemianti visą architektūrą: viskas turi vykti vienu metu. Mikrofonas fiksuoja garsą, kol modelis atsako, įvykiai atkeliauja, kol grojamas garso įrašas, o naudotojas gali bet kada pertraukti. Balso agentas nėra klausimų ir atsakymų ciklas; tai sistema, kurioje kelios srovės juda lygiagrečiai – todėl toliau taip intensyviai remiamės asyncio.

Audio
Fiksavimas ir atkūrimas
Sesija
„WebSocket“ ir konfigūracija
Įrankiai
Verslo veiksmai
Būsena
Pokalbio valdymas

Klasė „VoiceAgent“

Ši klasė apjungia būseną, kurią turi bendrinti šios lygiagrečios srovės: ryšį, dabartinę sesiją ir šiuo metu atkuriamą atsakymą. Būtent todėl, kad kelios užduotys vienu metu pasiekia šią būseną, objektas yra geresnis pasirinkimas nei globalių kintamųjų rinkinys – kai reikia atšaukti vykstantį atsakymą, turite žinoti, kad jis egzistuoja.

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

class VoiceAgent:
    """Išsamus balso agentas, pagrįstas „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):
        """Užmezga ryšį ir konfigūruoja sesiją."""
        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)

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

        # Konfigūravimas
        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("Balso agentas paruoštas.")

    async def start(self):
        """Paleidžia balso agentą."""
        await self.connect()
        await asyncio.gather(
            self._capture_audio(),
            self._process_events()
        )

Garso fiksavimo modulis

    async def _capture_audio(self):
        """Fiksuoja mikrofono įvestį ir siunčia ją į „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
                }))

Įvykių apdorojimo modulis

    async def _process_events(self):
        """Apdoroja visus serverio įvykius."""
        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"\nError: {event['error']['message']}")

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

Įrankių valdymo modulis

Šis modulis paverčia agentą iš paprasto balso pokalbių roboto į asistentą, pajėgų imtis veiksmų. Skirtumas nuo klasikinio funkcijų kvietimo slypi laiko apribojime: naudotojas yra linijoje be jokio vizualaus progreso indikatoriaus. Jei vykdymas trunka ilgiau nei sekundę ar dvi, leiskite agentui kalbėti dirbant – „Leiskite man tai patikrinti dabar pat“, nes tyla balso pokalbyje skamba kaip gedimas.

    async def _handle_response_done(self, event):
        """Tvarko funkcijų kvietimus atsakyme."""
        response = event["response"]
        function_calls = [
            o for o in response.get("output", [])
            if o["type"] == "function_call"
        ]

        if not function_calls:
            print()  # Nauja eilutė po transkripcijos
            return

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

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

            # Vykdyti funkciją (pritaikykite savo verslo logikai)
            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)
                }
            }))

        # Paprašyti modelio tęsti
        await self.ws.send(json.dumps({"type": "response.create"}))

    async def _execute_function(self, name: str, args: dict) -> dict:
        """Nukreipia funkcijos kvietimą."""
        # Įgyvendinkite pagal savo verslo logiką
        return {"error": f"Function {name} not implemented"}

Agento paleidimas

async def main():
    agent = VoiceAgent(
        api_key="sk-...",
        instructions=(
            "You are a voice assistant for Corsen AI. "
            "You help users manage their appointments "
            "and get information about our services. "
            "Respond in French, concisely and professionally."
        ),
        tools=[
            {
                "type": "function",
                "name": "check_availability",
                "description": "Checks availability for a time slot",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "date": {"type": "string"},
                        "service": {"type": "string"}
                    },
                    "required": ["date"]
                }
            }
        ]
    )

    await agent.start()

asyncio.run(main())

Svarbiausi punktai

  • Išsamus balso agentas sujungia keturis modulius: garso, sesijos, įrankių ir būsenos valdymo
  • Klasė VoiceAgent apgaubia visą logiką už paprastos sąsajos
  • asyncio.gather leidžia lygiagrečiai fiksuoti mikrofono garsą ir apdoroti įvykius
  • Pertraukimų valdymas (atsakymo atšaukimas, kai naudotojas pradeda kalbėti) yra esminis
  • Įrankiai paverčia agentą iš paprasto balso pokalbių roboto į asistentą, pajėgų imtis veiksmų