Építs fel egy teljes hangalapú ügynököt
Ezen az oldalon
Frissítve: 2026. november 2. – Hangmodellek. A tanfolyam több modellje elavult: a
tts-1,tts-1-hdés agpt-4o-mini-ttstámogatása 2027. január 6-án megszűnik (utódjuk:gpt-realtime-2.1-mini, amelyet az OpenAI TTS útmutatója szerint a/v1/audio/speechnem támogat: a beszédszintézis migrációja a Realtime API felé történik); agpt-realtime,gpt-4o-realtimeés a régi hangmodellek támogatása 2027. január 20-án szűnik meg (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5); awhisper-1,gpt-4o-transcribeés a/v1/audio/translationsvégpontok használata 2027. február 26-án jár le (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). A teljes duplex hangkommunikációhoz a GPT-Live 1 már 2026. szeptember 10. óta elérhető az API-ban.
Helyesbítve: 2026. november 3. A bemeneti átírás korábban a
gpt-live-transcribemodellt használta, amely kizárólag átírási munkamenetben működik, és nem támogatja sem aserver_vad, sem asemantic_vadfunkciót. Egy ilyen beszélgetési munkamenetben, ahol a VAD (Voice Activity Detection) minden fordulót érvényesít, a dokumentáció agpt-transcribehasználatát írja elő, amely az érvényesített fordulókat írja át, és a korábbi fordulókat kontextusként kezeli. Források: Valós idejű átírás · GPT-Transcribe · GPT-Live-Transcribe.
Építs fel egy teljes hangalapú ügynököt
Ez a lecke összefogja az eddig tárgyalt összes fogalmat, hogy felépíts egy teljesen működőképes, végpontok közötti hangalapú ügynököt. Létrehozol egy asszisztenst, amely figyeli a felhasználót, megérti a kéréseit, végrehajtja a műveleteket, és hangon válaszol – mindezt valós időben, a Realtime API-n keresztül.
Az ügynök architektúrája
Négy modul, és mindenekelőtt egy kényszerítő erő, amely az egész architektúrát meghatározza: mindennek egyszerre kell történnie. A mikrofon rögzít, miközben a modell válaszol; események érkeznek, miközben a hang lejátszása zajlik; és a felhasználó bármikor megszakíthatja a folyamatot. Egy hangalapú ügynök nem egyszerű kérdés-válasz ciklus; ez egy rendszer, ahol több adatfolyam halad párhuzamosan – ezért támaszkodunk erősen az asyncio használatára a következőkben.
A VoiceAgent osztály
Az osztály gyűjti össze azt az állapotot, amelyet ezeknek a párhuzamos adatfolyamoknak meg kell osztaniuk: a kapcsolatot, az aktuális munkamenetet és a éppen lejátszás alatt álló választ. Pontosan azért, mert több feladat fér hozzá egyszerre ehhez az állapothoz, egy objektum előnyösebb, mint a globális változók halmaza – amikor meg kell szakítanod egy folyamatban lévő választ, tudnod kell, hogy létezik ilyen.
import asyncio
import json
import base64
import websockets
import sounddevice as sd
import numpy as np
import pyaudio
class VoiceAgent:
"""Teljes hangalapú ügynök a Realtime API alapján."""
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):
"""Létrehozza a kapcsolatot és konfigurálja a munkamenetet."""
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)
# Várakozás a session.created eseményre
event = json.loads(await self.ws.recv())
print(f"Munkamenet: {event['session']['id']}")
# Konfiguráció
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("Hangalapú ügynök készen áll.")
async def start(self):
"""Elindítja a hangalapú ügynököt."""
await self.connect()
await asyncio.gather(
self._capture_audio(),
self._process_events()
)
Hangrögzítő modul
async def _capture_audio(self):
"""Rögzíti a mikrofon bemenetét és elküldi a Realtime API-nak."""
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
}))
Eseményfeldolgozó modul
async def _process_events(self):
"""Feldolgozza az összes eseményt a szerverről."""
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"\nHiba: {event['error']['message']}")
finally:
player.close()
pa.terminate()
Eszközkezelő modul
Ez a modul alakítja át az ügynököt egy egyszerű hangalapú chatbottól egy cselekvésre képes asszisztenssé. A klasszikus függvényhívástól való eltérés az időzítési kényszerben rejlik: a felhasználó a vonalban van, vizuális folyamatjelző nélkül. Ha a végrehajtás több mint egy-két másodpercig tart, beszéltessd az ügynököt munka közben – „Hadd ellenőrizzem ezt önnek most“ –, mert a csend egy hangalapú beszélgetésben hibának vagy leállásnak tűnik.
async def _handle_response_done(self, event):
"""Kezeli a válaszban lévő függvényhívásokat."""
response = event["response"]
function_calls = [
o for o in response.get("output", [])
if o["type"] == "function_call"
]
if not function_calls:
print() # Új sor az átírás után
return
for call in function_calls:
name = call["name"]
args = json.loads(call["arguments"])
call_id = call["call_id"]
print(f"\n→ {name}({args})")
# Függvény végrehajtása (igazítsd az üzleti logikádhoz)
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)
}
}))
# Kérd meg a modellt a folytatásra
await self.ws.send(json.dumps({"type": "response.create"}))
async def _execute_function(self, name: str, args: dict) -> dict:
"""Kézbesíti a függvényhívást."""
# Implementáld az üzleti logikád szerint
return {"error": f"A(z) {name} függvény nincs implementálva"}
Az ügynök indítása
async def main():
agent = VoiceAgent(
api_key="sk-...",
instructions=(
"Te a Corsen AI hangalapú asszisztense vagy. "
"Segítesz a felhasználóknak az időpontfoglalásban "
"és információkat adsz szolgáltatásainkról. "
"Válaszolj franciául, tömören és professzionálisan."
),
tools=[
{
"type": "function",
"name": "check_availability",
"description": "Ellenőrzi a rendelkezésre állást egy adott időpontra",
"parameters": {
"type": "object",
"properties": {
"date": {"type": "string"},
"service": {"type": "string"}
},
"required": ["date"]
}
}
]
)
await agent.start()
asyncio.run(main())
Főbb megállapítások
- Egy teljes hangalapú ügynök négy modult kombinál: hang, munkamenet, eszközök és állapotkezelés
- A
VoiceAgentosztály egy egyszerű felület mögé zárja az összes logikát - Az
asyncio.gatherlehetővé teszi a mikrofon rögzítésének és az eseményfeldolgozásnak a párhuzamos futtatását - A megszakítások kezelése (a válasz megszakítása, amikor a felhasználó megszólal) elengedhetetlen
- Az eszközök alakítják át az ügynököt egy egyszerű hangalapú chatbottól egy cselekvésre képes asszisztenssé