Izgradi celovitega glasovnega agenta
Na tej strani
Posodobljeno 2. novembra 2026 — Zvočni modeli. Več modelov v tem tečaju je zastarelih:
tts-1,tts-1-hdingpt-4o-mini-ttsbodo 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-realtimein stari zvočni modeli 20. januarja 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribein/v1/audio/translations26. 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 nitiserver_vadnitisemantic_vad. V pogovorni seji, kot je ta, kjer VAD potrjuje vsak obrat, dokumentacija določagpt-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.
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
VoiceAgentencapsulira vso logiko za preprostim vmesnikom asyncio.gatheromogoč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