Rakenna täydellinen puheagentti
Tällä sivulla
Päivitetty 2. marraskuuta 2026 — Äänimallit. Useat tämän kurssin malleista on vanhentumassa:
tts-1,tts-1-hdjagpt-4o-mini-ttslakkaavat toimimasta 6. tammikuuta 2027 (seuraaja:gpt-realtime-2.1-mini, jonka OpenAI:n TTS-opas ilmoittaa ei tukevan/v1/audio/speech: puheentuotto siirtyy Realtime API:n piiriin);gpt-realtime,gpt-4o-realtimeja vanhat äänimallit 20. tammikuuta 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeja/v1/audio/translations26. helmikuuta 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Täysdupleksista puheenvuoroa varten GPT-Live 1 on ollut saatavilla rajapinnassa 10. syyskuuta 2026 lähtien.
Korjattu 3. marraskuuta 2026. Syötteen litterointi käytti mallia
gpt-live-transcribe, joka toimii vain litterointi-istunnossa eikä tueserver_vad- eikäsemantic_vad-toimintoja. Tämän kaltaisessa keskusteluistunnossa, jossa VAD vahvistaa jokaisen vuoron, dokumentaatio määrää käyttämään malliagpt-transcribe, joka litteroi vahvistetut vuorot ja hyödyntää aiempia vuoroja kontekstina. Lähteet: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.
Rakenna täydellinen puheagentti
Tässä oppitunnissa yhdistämme kaikki tähän mennessä käsitellyt konseptit toimivan, päästä päähän ulottuvan puheagentin rakentamiseksi. Luot assistentin, joka kuuntelee käyttäjää, ymmärtää pyynnöt, suorittaa toimintoja ja vastaa äänellä – kaikki reaaliajassa Realtime API:n kautta.
Agentin arkkitehtuuri
Neljä moduulia ja ennen kaikkea yksi rajoite, joka ohjaa koko arkkitehtuuria: kaiken on tapahduttava samanaikaisesti. Mikrofoni tallentaa mallin vastatessa, tapahtumat saapuvat äänen toistuessa, ja käyttäjä voi keskeyttää milloin tahansa. Puheagentti ei ole kysymys-vastaus-silmukka; se on järjestelmä, jossa useat virrat etenevät rinnakkain – minkä vuoksi nojaamme seuraavassa vahvasti asyncio:hon.
VoiceAgent-luokka
Luokka kokoaa yhteen tilan, jota näiden rinnakkaisten virtojen on jaettava: yhteyden, nykyisen istunnon ja parhaillaan toistettavan vastauksen. Juuri siksi, että useat tehtävät käyttävät tätä tilaa samanaikaisesti, olio on parempi vaihtoehto kuin joukko globaaleja muuttujia – kun sinun on peruutettava käynnissä oleva vastaus, sinun on tiedettävä sellaisen olevan olemassa.
import asyncio
import json
import base64
import websockets
import sounddevice as sd
import numpy as np
import pyaudio
class VoiceAgent:
"""Täydellinen puheagentti Realtime API:n pohjalta."""
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):
"""Muodostaa yhteyden ja määrittää istunnon."""
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)
# Odota session.created-tapahtumaa
event = json.loads(await self.ws.recv())
print(f"Istunto: {event['session']['id']}")
# Määritä
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("Puheagentti valmiina.")
async def start(self):
"""Käynnistää puheagentin."""
await self.connect()
await asyncio.gather(
self._capture_audio(),
self._process_events()
)
Äänen sieppausmoduuli
async def _capture_audio(self):
"""Sieppaa mikrofonisyötteen ja lähettää sen Realtime API:lle."""
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
}))
Tapahtumien käsittelymoduuli
async def _process_events(self):
"""Käsittelee kaikki palvelimelta tulevat tapahtumat."""
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"\nVirhe: {event['error']['message']}")
finally:
player.close()
pa.terminate()
Työkalujen hallintamoduuli
Tämä moduuli muuttaa agentin yksinkertaisesta puhekeskustelubotista toimia pystyväksi assistentiksi. Ero perinteiseen funktiokutsuun liittyy aikarajoitteeseen: käyttäjä on linjalla ilman visuaalista edistymisindikaattoria. Jos suoritus kestää yli sekunnin tai kaksi, saa agentin puhumaan työn aikana – “Tarkistan tämän sinulle heti” – sillä hiljaisuus puhekeskustelussa kuulostaa katkokselta.
async def _handle_response_done(self, event):
"""Käsittelee vastauksen funktiokutsut."""
response = event["response"]
function_calls = [
o for o in response.get("output", [])
if o["type"] == "function_call"
]
if not function_calls:
print() # Uusi rivi litteroinnin jälkeen
return
for call in function_calls:
name = call["name"]
args = json.loads(call["arguments"])
call_id = call["call_id"]
print(f"\n→ {name}({args})")
# Suorita funktio (sovita liiketoimintalogiikkaasi)
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)
}
}))
# Pyydä mallia jatkamaan
await self.ws.send(json.dumps({"type": "response.create"}))
async def _execute_function(self, name: str, args: dict) -> dict:
"""Ohjaa funktiokutsun eteenpäin."""
# Toteuta liiketoimintalogiikkasi mukaan
return {"error": f"Funktiota {name} ei ole toteutettu"}
Käynnistä agentti
async def main():
agent = VoiceAgent(
api_key="sk-...",
instructions=(
"Olet Corsen AI:n puheassistentti. "
"Autat käyttäjiä hallitsemaan tapaamisiaan "
"ja saamaan tietoa palveluistamme. "
"Vastaa ranskaksi, ytimekkäästi ja ammattimaisesti."
),
tools=[
{
"type": "function",
"name": "check_availability",
"description": "Tarkistaa saatavuuden aikavälille",
"parameters": {
"type": "object",
"properties": {
"date": {"type": "string"},
"service": {"type": "string"}
},
"required": ["date"]
}
}
]
)
await agent.start()
asyncio.run(main())
Keskeiset asiat
- Täydellinen puheagentti yhdistää neljä moduulia: äänen, istunnon, työkalut ja tilanhallinnan
VoiceAgent-luokka kapseloi koko logiikan yksinkertaisen käyttöliittymän taakseasyncio.gathermahdollistaa mikrofonin sieppauksen ja tapahtumien käsittelyn rinnakkain- Keskeytysten käsittely (vastauksen peruuttaminen käyttäjän puhuessa) on välttämätöntä
- Työkalut muuttavat agentin yksinkertaisesta puhekeskustelubotista toimia pystyväksi assistentiksi