Vytvor kompletného hlasového agenta
Na tejto strane
Aktualizované 2. novembra 2026 — Zvukové modely. Niektoré modely v tomto kurze sú zastarané:
tts-1,tts-1-hdagpt-4o-mini-ttsprestanú fungovať 6. januára 2027 (nástupca:gpt-realtime-2.1-mini, ktorý podľa príručky OpenAI TTS nie je podporovaný rozhraním/v1/audio/speech: migrácia syntézy reči prechádza na Realtime API);gpt-realtime,gpt-4o-realtimea staršie zvukové modely skončia 20. januára 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribea/v1/audio/translationsskončia 26. februára 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Pre plno duplexný hlas je GPT-Live 1 dostupný v API od 10. septembra 2026.
Opravené 3. novembra 2026. Vstupný prepis používal
gpt-live-transcribe, ktorý funguje len v relácii typu transcription a nepodporuje aniserver_vad, anisemantic_vad. V konverzačnej relácii, ako je táto, kde VAD overuje každý obrat, dokumentácia špecifikuje použitiegpt-transcribe, ktorý prepisuje overené obraty a využíva predchádzajúce obraty ako kontext. Zdroje: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.
Vytvor kompletného hlasového agenta
Táto lekcia spája všetky doteraz prebrané koncepty do funkčného end-to-end hlasového agenta. Vytvoríš asistenta, ktorý počúva používateľa, rozumie jeho požiadavkám, vykonáva akcie a odpovedá hlasom – všetko v reálnom čase prostredníctvom Realtime API.
Architektúra agenta
Štyri moduly a predovšetkým jedno obmedzenie, ktoré určuje celú architektúru: všetko sa musí diať naraz. Mikrofón sníma, zatiaľ čo model odpovedá, udalosti prichádzajú, zatiaľ čo sa prehráva zvuk, a používateľ môže prerušiť komunikáciu kedykoľvek. Hlasový agent nie je sluška otázka-odpoveď; je to systém, v ktorom viaceré toky prebiehajú paralelne – preto sa v nasledujúcich častiach silno spoliehame na asyncio.
Trieda VoiceAgent
Táto trieda zhromažďuje stav, ktorý musia tieto paralelné toky zdieľať: pripojenie, aktuálnu reláciu a práve prehrávanú odpoveď. Práve preto, že k tomuto stavu pristupuje viacero úloh súčasne, je objekt vhodnejší ako sada globálnych premenných – keď potrebuješ zrušiť prebiehajúcu odpoveď, musíš vedieť, že existuje.
import asyncio
import json
import base64
import websockets
import sounddevice as sd
import numpy as np
import pyaudio
class VoiceAgent:
"""Kompletný hlasový agent založený na 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):
"""Nadviaže pripojenie a nakonfiguruje reláciu."""
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čkaj na session.created
event = json.loads(await self.ws.recv())
print(f"Relácia: {event['session']['id']}")
# Konfigurácia
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("Hlasový agent je pripravený.")
async def start(self):
"""Spustí hlasového agenta."""
await self.connect()
await asyncio.gather(
self._capture_audio(),
self._process_events()
)
Modul snímania zvuku
async def _capture_audio(self):
"""Sníma vstup z mikrofónu a odosiela ho do 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 spracovania udalostí
async def _process_events(self):
"""Spracúva všetky udalosti zo servera."""
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"\nChyba: {event['error']['message']}")
finally:
player.close()
pa.terminate()
Modul správy nástrojov
Tento modul mení agenta z jednoduchého hlasového chatbota na asistenta schopného konať. Rozdiel oproti klasickému volaniu funkcií spočíva v časovom obmedzení: používateľ je na linke bez vizuálneho indikátora priebehu. Ak vykonávanie trvá viac ako sekundu alebo dve, nechaj agenta hovoriť, zatiaľ čo pracuje – „Dovoľte mi to hneď skontrolovať“ – pretože ticho v hlasovej konverzácii pôsobí ako výpadok.
async def _handle_response_done(self, event):
"""Spracúva volania funkcií v odpovedi."""
response = event["response"]
function_calls = [
o for o in response.get("output", [])
if o["type"] == "function_call"
]
if not function_calls:
print() # Nový riadok po prepise
return
for call in function_calls:
name = call["name"]
args = json.loads(call["arguments"])
call_id = call["call_id"]
print(f"\n→ {name}({args})")
# Vykonaj funkciu (prispôsob svojej obchodnej logike)
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)
}
}))
# Požiadaj model o pokračovanie
await self.ws.send(json.dumps({"type": "response.create"}))
async def _execute_function(self, name: str, args: dict) -> dict:
"""Smeruje volanie funkcie."""
# Implementuj podľa svojej obchodnej logiky
return {"error": f"Funkcia {name} nie je implementovaná"}
Spustenie agenta
async def main():
agent = VoiceAgent(
api_key="sk-...",
instructions=(
"Si hlasový asistent pre Corsen AI. "
"Pomáhaš používateľom spravovať ich stretnutia "
"a získavať informácie o našich službách. "
"Odpovedaj po francúzsky, stručne a profesionálne."
),
tools=[
{
"type": "function",
"name": "check_availability",
"description": "Skontroluje dostupnosť časového slotu",
"parameters": {
"type": "object",
"properties": {
"date": {"type": "string"},
"service": {"type": "string"}
},
"required": ["date"]
}
}
]
)
await agent.start()
asyncio.run(main())
Kľúčové poznatky
- Kompletný hlasový agent kombinuje štyri moduly: audio, reláciu, nástroje a správu stavu
- Trieda
VoiceAgentzapuzdruje celú logiku za jednoduché rozhranie asyncio.gatherumožňuje paralelné snímanie mikrofónu a spracovanie udalostí- Spracovanie prerušení (zrušenie odpovede, keď používateľ začne hovoriť) je nevyhnutné
- Nástroje menia agenta z jednoduchého hlasového chatbota na asistenta schopného konať