Ehita täielik hääleagent
Sellel lehel
Uuendatud 2. novembril 2026 – Audiomudelid. Selles kursuses on mitu mudelit aegunud:
tts-1,tts-1-hdjagpt-4o-mini-ttslõpetavad töö 6. jaanuaril 2027 (järeltulija:gpt-realtime-2.1-mini, mida OpenAI TTS-i juhend kirjeldab kui mittetoetatud teenuse/v1/audio/speechpoolt: kõnesünteesi migratsioon liigub Realtime API-le);gpt-realtime,gpt-4o-realtimeja vanad audiomudelid 20. jaanuaril 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeja/v1/audio/translations26. veebruaril 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Täisdupleksse kõne jaoks on GPT-Live 1 olnud API-s saadaval alates 10. septembrist 2026.
Parandatud 3. novembril 2026. Sisendi transkriptsioon kasutas mudelit
gpt-live-transcribe, mis toimib ainult transkriptsiooni sessioonis ega toeta eiserver_vadegasemantic_vad. Sellises vestlussessioonis, kus VAD valideerib iga pöörde, määratleb dokumentatsioon mudeligpt-transcribe, mis transkribeerib valideeritud pöörded ja kasutab eelmisi pöördeid kontekstina. Allikad: Reaalaja transkriptsioon · GPT-Transcribe · GPT-Live-Transcribe.
Ehita täielik hääleagent
See õppetund ühendab kõik seni käsitletud mõisted, et luua täielikult toimiv ots-otsani hääleagent. Lood assistendi, kes kuulab kasutajat, mõistab tema soovi, täidab toiminguid ja vastab häälega – kõik reaalajas Realtime API kaudu.
Agendi arhitektuur
Neli moodulit ja ennenägematu piirang, mis juhib kogu arhitektuuri: kõik peab toimuma samaaegselt. Mikrofon salvestab samal ajal, kui mudel vastab, sündmused saabuvad samal ajal, kui heli mängib, ja kasutaja võib katkestada igal hetkel. Hääleagent ei ole küsimuste ja vastuste tsükkel; see on süsteem, kus mitu voogu edenevad paralleelselt – seetõttu tuginevad järgnevad lahendused tugevalt asyncio-le.
Klass VoiceAgent
See klass koondab oleku, mida need paralleelsed vood peavad jagama: ühenduse, praeguse sessiooni ja parasjagu esitatava vastuse. Just seetõttu, et mitu ülesannet pääsevad sellele olekule samaaegselt ligi, on objekt eelistatud globaalsete muutujate hulgale – kui pead tühistama käimasolevat vastust, pead teadma, et see eksisteerib.
import asyncio
import json
import base64
import websockets
import sounddevice as sd
import numpy as np
import pyaudio
class VoiceAgent:
"""Täielik hääleagent, mis põhineb Realtime API-l."""
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):
"""Loob ühenduse ja konfigureerib sessiooni."""
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)
# Oota session.created
event = json.loads(await self.ws.recv())
print(f"Sessioon: {event['session']['id']}")
# Konfigureeri
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("Hääleagent on valmis.")
async def start(self):
"""Käivitab hääleagendi."""
await self.connect()
await asyncio.gather(
self._capture_audio(),
self._process_events()
)
Audio salvestamise moodul
async def _capture_audio(self):
"""Salvestab mikrofonisisendi ja saadab selle Realtime API-le."""
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
}))
Sündmuste töötlemise moodul
async def _process_events(self):
"""Töötleb kõik serverilt saabuvad sündmused."""
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"\nViga: {event['error']['message']}")
finally:
player.close()
pa.terminate()
Tööriistade haldamise moodul
See moodul muudab agendi lihtsast häälechatbotist assistendiks, kes suudab tegutseda. Erinevus klassikalisest funktsioonide kutsumisest seisneb ajapiirangus: kasutaja on liinil ilma visuaalse edenemisnäidikuta. Kui täitmine võtab rohkem kui sekundi või kaks, pane agent rääkima töö tegemise ajal – „Kontrollin seda teie jaoks kohe“ –, sest vaikus häälevestluses kõlab nagu tõrge.
async def _handle_response_done(self, event):
"""Haldab vastuses olevaid funktsioonikutsunguid."""
response = event["response"]
function_calls = [
o for o in response.get("output", [])
if o["type"] == "function_call"
]
if not function_calls:
print() # Uus rida pärast transkriptsiooni
return
for call in function_calls:
name = call["name"]
args = json.loads(call["arguments"])
call_id = call["call_id"]
print(f"\n→ {name}({args})")
# Täida funktsioon (kohanda oma äriloogikaga)
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)
}
}))
# Palu mudelil jätkata
await self.ws.send(json.dumps({"type": "response.create"}))
async def _execute_function(self, name: str, args: dict) -> dict:
"""Suunab funktsioonikutsungi."""
# Rakenda vastavalt oma äriloogikale
return {"error": f"Funktsioon {name} on realiseerimata"}
Agendi käivitamine
async def main():
agent = VoiceAgent(
api_key="sk-...",
instructions=(
"Oled Corsen AI hääleassistent. "
"Aidad kasutajatel hallata oma kohtumisi "
"ja saada teavet meie teenuste kohta. "
"Vasta prantsuse keeles, lakooniliselt ja professionaalselt."
),
tools=[
{
"type": "function",
"name": "check_availability",
"description": "Kontrollib saadavust ajavahemiku jaoks",
"parameters": {
"type": "object",
"properties": {
"date": {"type": "string"},
"service": {"type": "string"}
},
"required": ["date"]
}
}
]
)
await agent.start()
asyncio.run(main())
Peamised punktid
- Täielik hääleagent ühendab neli moodulit: audio, sessioon, tööriistad ja olekuhaldus
- Klass
VoiceAgentkapseldab kogu loogika lihtsa liidese taha asyncio.gathervõimaldab mikrofoni salvestamist ja sündmuste töötlemist paralleelselt- Katkestuste käsitlemine (vastuse tühistamine, kui kasutaja räägib) on hädavajalik
- Tööriistad muudavad agendi lihtsast häälechatbotist tegutsemisvõimeliseks assistendiks