Sukurkite išsamų balso agentą
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 2 d. — Garso modeliai. Keli šio kurso modeliai yra pasenę:
tts-1,tts-1-hdirgpt-4o-mini-ttsnustos veikti 2027 m. sausio 6 d. (įpėdinis:gpt-realtime-2.1-mini, kurio, kaip nurodo „OpenAI“ TTS gidas, nepalaiko/v1/audio/speech: kalbos sintezės migracija perkeliama į „Realtime API“);gpt-realtime,gpt-4o-realtimeir senieji garso modeliai nustos veikti 2027 m. sausio 20 d. (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribeir/v1/audio/translationsnustos veikti 2027 m. vasario 26 d. (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Pilno dublekso balsui „GPT-Live 1“ API buvo prieinamas nuo 2026 m. rugsėjo 10 d.
Ištaisyta 2026 m. lapkričio 3 d. Įvesties transkripcijai buvo naudojamas
gpt-live-transcribe, kuris veikia tik transkripcijos sesijoje ir nepalaiko neiserver_vad, neisemantic_vad. Pokalbio sesijoje, kaip ši, kurioje VAD patvirtina kiekvieną ėjimą, dokumentacijoje nurodoma naudotigpt-transcribe, kuris transkribuoja patvirtintus ėjimus ir naudoja ankstesnius ėjimus kaip kontekstą. Šaltiniai: Realtime transcription · GPT-Transcribe · GPT-Live-Transcribe.
Sukurkite išsamų balso agentą
Šioje pamokoje sujungsime visas iki šiol nagrinėtas sąvokas, kad sukurtume visiškai veikiantį balso agentą nuo pradžių iki galo. Sukursite asistentą, kuris klauso naudotojo, supranta jo prašymą, vykdo veiksmus ir atsako balsu – visa tai realiuoju laiku naudojant „Realtime API“.
Agento architektūra
Keturi moduliai ir viena pagrindinė sąlyga, lemianti visą architektūrą: viskas turi vykti vienu metu. Mikrofonas fiksuoja garsą, kol modelis atsako, įvykiai atkeliauja, kol grojamas garso įrašas, o naudotojas gali bet kada pertraukti. Balso agentas nėra klausimų ir atsakymų ciklas; tai sistema, kurioje kelios srovės juda lygiagrečiai – todėl toliau taip intensyviai remiamės asyncio.
Klasė „VoiceAgent“
Ši klasė apjungia būseną, kurią turi bendrinti šios lygiagrečios srovės: ryšį, dabartinę sesiją ir šiuo metu atkuriamą atsakymą. Būtent todėl, kad kelios užduotys vienu metu pasiekia šią būseną, objektas yra geresnis pasirinkimas nei globalių kintamųjų rinkinys – kai reikia atšaukti vykstantį atsakymą, turite žinoti, kad jis egzistuoja.
import asyncio
import json
import base64
import websockets
import sounddevice as sd
import numpy as np
import pyaudio
class VoiceAgent:
"""Išsamus balso agentas, pagrįstas „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):
"""Užmezga ryšį ir konfigūruoja sesiją."""
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)
# Laukiama session.created
event = json.loads(await self.ws.recv())
print(f"Session: {event['session']['id']}")
# Konfigūravimas
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("Balso agentas paruoštas.")
async def start(self):
"""Paleidžia balso agentą."""
await self.connect()
await asyncio.gather(
self._capture_audio(),
self._process_events()
)
Garso fiksavimo modulis
async def _capture_audio(self):
"""Fiksuoja mikrofono įvestį ir siunčia ją į „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
}))
Įvykių apdorojimo modulis
async def _process_events(self):
"""Apdoroja visus serverio įvykius."""
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"\nError: {event['error']['message']}")
finally:
player.close()
pa.terminate()
Įrankių valdymo modulis
Šis modulis paverčia agentą iš paprasto balso pokalbių roboto į asistentą, pajėgų imtis veiksmų. Skirtumas nuo klasikinio funkcijų kvietimo slypi laiko apribojime: naudotojas yra linijoje be jokio vizualaus progreso indikatoriaus. Jei vykdymas trunka ilgiau nei sekundę ar dvi, leiskite agentui kalbėti dirbant – „Leiskite man tai patikrinti dabar pat“, nes tyla balso pokalbyje skamba kaip gedimas.
async def _handle_response_done(self, event):
"""Tvarko funkcijų kvietimus atsakyme."""
response = event["response"]
function_calls = [
o for o in response.get("output", [])
if o["type"] == "function_call"
]
if not function_calls:
print() # Nauja eilutė po transkripcijos
return
for call in function_calls:
name = call["name"]
args = json.loads(call["arguments"])
call_id = call["call_id"]
print(f"\n→ {name}({args})")
# Vykdyti funkciją (pritaikykite savo verslo logikai)
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)
}
}))
# Paprašyti modelio tęsti
await self.ws.send(json.dumps({"type": "response.create"}))
async def _execute_function(self, name: str, args: dict) -> dict:
"""Nukreipia funkcijos kvietimą."""
# Įgyvendinkite pagal savo verslo logiką
return {"error": f"Function {name} not implemented"}
Agento paleidimas
async def main():
agent = VoiceAgent(
api_key="sk-...",
instructions=(
"You are a voice assistant for Corsen AI. "
"You help users manage their appointments "
"and get information about our services. "
"Respond in French, concisely and professionally."
),
tools=[
{
"type": "function",
"name": "check_availability",
"description": "Checks availability for a time slot",
"parameters": {
"type": "object",
"properties": {
"date": {"type": "string"},
"service": {"type": "string"}
},
"required": ["date"]
}
}
]
)
await agent.start()
asyncio.run(main())
Svarbiausi punktai
- Išsamus balso agentas sujungia keturis modulius: garso, sesijos, įrankių ir būsenos valdymo
- Klasė
VoiceAgentapgaubia visą logiką už paprastos sąsajos asyncio.gatherleidžia lygiagrečiai fiksuoti mikrofono garsą ir apdoroti įvykius- Pertraukimų valdymas (atsakymo atšaukimas, kai naudotojas pradeda kalbėti) yra esminis
- Įrankiai paverčia agentą iš paprasto balso pokalbių roboto į asistentą, pajėgų imtis veiksmų