Премини към основното съдържание
Български— Изберете език
Меню

Изграждане на пълен гласов агент

Урок 14 от 18 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Изграждане на пълен гласов агент
  2. Архитектура на агента
  3. Класът VoiceAgent
  4. Модул за аудио заснемане
  5. Модул за обработка на събития
  6. Модул за управление на инструменти
  7. Стартиране на агента
  8. Ключови изводи

Обновено на 2 ноември 2026 г. — Аудио модели. Няколко модела в този курс са депрецирали: tts-1, tts-1-hd и gpt-4o-mini-tts ще спрат работа на 6 януари 2027 г. (наследник: gpt-realtime-2.1-mini, за който ръководството на OpenAI за TTS посочва, че не се поддържа от /v1/audio/speech: миграцията на синтез на реч преминава към Realtime API); gpt-realtime, gpt-4o-realtime и наследените аудио модели на 20 януари 2027 г. (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe и /v1/audio/translations на 26 февруари 2027 г. (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). За дуплексна гласова връзка, GPT-Live 1 е наличен в API от 10 септември 2026 г.

Коригирано на 3 ноември 2026 г. Входната транскрипция използваше gpt-live-transcribe, който работи само в сесия за транскрипция и не поддържа нито server_vad, нито semantic_vad. В разговорна сесия като тази, където VAD валидира всяка реплика, документацията специфицира gpt-transcribe, който транскрибира валидирани реплики и използва предишните реплики като контекст. Източници: Транскрипция в реално време · GPT-Transcribe · GPT-Live-Transcribe.

Изграждане на пълен гласов агент

Този урок обединява всички концепции, разгледани до момента, за изграждането на напълно функционален гласов агент от край до край. Ще създадете асистент, който слуша потребителя, разбира неговата заявка, изпълнява действия и отговаря с глас — всичко в реално време чрез Realtime API.

Архитектура на агента

Четири модула и преди всичко едно ограничение, което движи цялата архитектура: всичко трябва да се случва едновременно. Микрофонът записва, докато моделът отговаря, събитията пристигат, докато се възпроизвежда аудио, и потребителят може да прекъсне във всеки момент. Гласовият агент не е цикъл от въпроси и отговори; това е система, в която множество потоци напредват паралелно — затова в следващите стъпки разчитаме силно на asyncio.

Audio
Запис и възпроизвеждане
Session
WebSocket и конфигурация
Tools
Бизнес действия
State
Управление на разговора

Класът VoiceAgent

Класът обединява състоянието, което тези паралелни потоци трябва да споделят: връзката, текущата сесия и отговорът, който се възпроизвежда в момента. Точно защото множество задачи достъпват това състояние едновременно, един обект е за предпочитане пред набор от глобални променливи — когато трябва да отмените текущ отговор, трябва да знаете, че такъв съществува.

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

class VoiceAgent:
    """Пълен гласов агент, базиран на 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):
        """Установява връзката и конфигурира сесията."""
        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)

        # Изчакване на session.created
        event = json.loads(await self.ws.recv())
        print(f"Session: {event['session']['id']}")

        # Конфигуриране
        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("Гласовият агент е готов.")

    async def start(self):
        """Стартира гласовия агент."""
        await self.connect()
        await asyncio.gather(
            self._capture_audio(),
            self._process_events()
        )

Модул за аудио заснемане

    async def _capture_audio(self):
        """Заснема вход от микрофона и го изпраща към 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
                }))

Модул за обработка на събития

    async def _process_events(self):
        """Обработва всички събития от сървъра."""
        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()

Модул за управление на инструменти

Този модул трансформира агента от обикновен гласов чатбот в асистент, способен да предприема действия. Разликата спрямо класическото извикване на функции се крие в ограничението за време: потребителят е на линия без визуален индикатор за напредък. Ако изпълнението отнеме повече от секунда-две, накарайте агента да говори, докато работи — „Нека проверя това за Вас веднага“ — защото тишината в гласов разговор звучи като срив.

    async def _handle_response_done(self, event):
        """Обработва извикванията на функции в отговора."""
        response = event["response"]
        function_calls = [
            o for o in response.get("output", [])
            if o["type"] == "function_call"
        ]

        if not function_calls:
            print()  # Нов ред след транскрипцията
            return

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

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

            # Изпълнение на функцията (адаптирайте към Вашата бизнес логика)
            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)
                }
            }))

        # Поискване от модела да продължи
        await self.ws.send(json.dumps({"type": "response.create"}))

    async def _execute_function(self, name: str, args: dict) -> dict:
        """Насочва извикването на функцията."""
        # Имплементирайте според Вашата бизнес логика
        return {"error": f"Function {name} not implemented"}

Стартиране на агента

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())

Ключови изводи

  • Един пълен гласов агент комбинира четири модула: аудио, сесия, инструменти и управление на състоянието
  • Класът VoiceAgent капсулира цялата логика зад прост интерфейс
  • asyncio.gather позволява паралелно заснемане от микрофона и обработка на събития
  • Обработката на прекъсвания (отменяне на отговор, когато потребителят говори) е от съществено значение
  • Инструментите трансформират агента от обикновен гласов чатбот в асистент, способен на действие