Изграждане на пълен гласов агент
На тази страница
Обновено на 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.
Класът 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позволява паралелно заснемане от микрофона и обработка на събития- Обработката на прекъсвания (отменяне на отговор, когато потребителят говори) е от съществено значение
- Инструментите трансформират агента от обикновен гласов чатбот в асистент, способен на действие