Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Izgradi celovitega glasovnega agenta

Lekcija 14 od 18 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Izgradi celovitega glasovnega agenta
  2. Arhitektura agenta
  3. Razred VoiceAgent
  4. Modul za zajem zvoka
  5. Modul za obdelavo dogodkov
  6. Modul za upravljanje orodij
  7. Zagon agenta
  8. Ključne ugotovitve

Posodobljeno 2. novembra 2026 — Zvočni modeli. Več modelov v tem tečaju je zastarelih: tts-1, tts-1-hd in gpt-4o-mini-tts bodo prenehali delovati 6. januarja 2027 (naslednik: gpt-realtime-2.1-mini, ki ga vodnik za OpenAI TTS navaja kot nepodprtega z /v1/audio/speech: selitev sinteze govora prehaja na Realtime API); gpt-realtime, gpt-4o-realtime in stari zvočni modeli 20. januarja 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe in /v1/audio/translations 26. februarja 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Za polnodupleksni govor je GPT-Live 1 na voljo v API-ju od 10. septembra 2026.

Popravljeno 3. novembra 2026. Vnosni prepis je uporabljal gpt-live-transcribe, ki deluje le v seji za prepis in ne podpira niti server_vad niti semantic_vad. V pogovorni seji, kot je ta, kjer VAD potrjuje vsak obrat, dokumentacija določa gpt-transcribe, ki prepisuje potrjene obrate in uporablja prejšnje obrate kot kontekst. Viri: Prepis v realnem času · GPT-Transcribe · GPT-Live-Transcribe.

Izgradi celovitega glasovnega agenta

Ta lekcija združuje vse doslej obravnavane koncepte za izgradnjo popolnoma funkcionalnega glasovnega agenta od konca do konca. Ustvaril boš pomočnika, ki posluša uporabnika, razume njegovo zahtevo, izvaja dejanja in odgovarja z glasom – vse v realnem času prek Realtime API-ja.

Arhitektura agenta

Štirje moduli in predvsem ena omejitev, ki poganja celotno arhitekturo: vse se mora zgoditi hkrati. Mikrofon zajema zvok, medtem ko model odgovarja, dogodki prihajajo, medtem ko se predvaja zvok, in uporabnik lahko kadarkoli prekine. Glasovni agent ni zanka vprašanj in odgovorov; je sistem, kjer več tokov napreduje vzporedno – zato se v nadaljevanju močno zanašamo na asyncio.

Zvok
Zajem in predvajanje
Seja
WebSocket in konfiguracija
Orodja
Poslovna dejanja
Stanje
Upravljanje pogovora

Razred VoiceAgent

Razred združuje stanje, ki si ga morajo ti vzporedni tokovi deliti: povezavo, trenutno sejo in odziv, ki se trenutno predvaja. Prav zato, ker več opravil hkrati dostopa do tega stanja, je objekt boljša izbira od niza globalnih spremenljivk – ko moraš preklicati odziv v teku, moraš vedeti, da ta obstaja.

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

class VoiceAgent:
    """Celovit glasovni agent, temelječ na Realtime API-ju."""

    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):
        """Vzpostavi povezavo in konfigurira sejo."""
        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)

        # Počakaj na session.created
        event = json.loads(await self.ws.recv())
        print(f"Seja: {event['session']['id']}")

        # Konfiguriraj
        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("Glasovni agent je pripravljen.")

    async def start(self):
        """Zažene glasovnega agenta."""
        await self.connect()
        await asyncio.gather(
            self._capture_audio(),
            self._process_events()
        )

Modul za zajem zvoka

    async def _capture_audio(self):
        """Zajema vhod z mikrofona in ga pošilja v 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
                }))

Modul za obdelavo dogodkov

    async def _process_events(self):
        """Obdeluje vse dogodke s strežnika."""
        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"\nNapaka: {event['error']['message']}")

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

Modul za upravljanje orodij

Ta modul spremeni agenta iz preprostega glasovnega klepetalnega robota v pomočnika, ki zmore ukrepati. Razlika glede na klasično klicanje funkcij je v časovni omejitvi: uporabnik je na zvezi brez vizualnega indikatorja napredka. Če izvajanje traja več kot sekundo ali dve, naj agent govori, medtem ko dela – „Trenutno preverjam za vas” –, saj tišina v glasovnem pogovoru deluje kot okvara.

    async def _handle_response_done(self, event):
        """Obdeluje klice funkcij v odzivu."""
        response = event["response"]
        function_calls = [
            o for o in response.get("output", [])
            if o["type"] == "function_call"
        ]

        if not function_calls:
            print()  # Nova vrstica po prepisu
            return

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

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

            # Izvedi funkcijo (prilagodi svoji poslovni logiki)
            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)
                }
            }))

        # Prosi model, naj nadaljuje
        await self.ws.send(json.dumps({"type": "response.create"}))

    async def _execute_function(self, name: str, args: dict) -> dict:
        """Usmeri klic funkcije."""
        # Implementiraj glede na svojo poslovno logiko
        return {"error": f"Funkcija {name} ni implementirana"}

Zagon agenta

async def main():
    agent = VoiceAgent(
        api_key="sk-...",
        instructions=(
            "Si glasovni pomočnik za Corsen AI. "
            "Uporabnikom pomagaš upravljati termine "
            "in pridobivati informacije o naših storitvah. "
            "Odgovarjaj v francoščini, jedrnato in profesionalno."
        ),
        tools=[
            {
                "type": "function",
                "name": "check_availability",
                "description": "Preveri razpoložljivost za časovni termin",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "date": {"type": "string"},
                        "service": {"type": "string"}
                    },
                    "required": ["date"]
                }
            }
        ]
    )

    await agent.start()

asyncio.run(main())

Ključne ugotovitve

  • Celovit glasovni agent združuje štiri module: zvok, sejo, orodja in upravljanje stanja
  • Razred VoiceAgent encapsulira vso logiko za preprostim vmesnikom
  • asyncio.gather omogoča vzporeden zajem z mikrofona in obdelavo dogodkov
  • Obvladovanje prekinitev (preklic odziva, ko uporabnik spregovori) je bistveno
  • Orodja spremenijo agenta iz preprostega glasovnega klepetalnega robota v pomočnika, ki zmore ukrepati