Ibni aġent vokali sħiħ
F'din il-paġna
Aġġornat fit-2 ta’ Novembru, 2026 — Mudelli awdjo. Diversi mudelli f’dan il-kors huma skaduti:
tts-1,tts-1-hd, ugpt-4o-mini-ttsse jieqfu fis-6 ta’ Jannar, 2027 (suċċessur:gpt-realtime-2.1-mini, li l-gwida TTS ta’ OpenAI tiddikjara li mhux appoġġjata minn/v1/audio/speech: il-migrazzjoni tas-sinteżi tal-kelma tmur lejn l-API Realtime);gpt-realtime,gpt-4o-realtime, u mudelli awdjo antiki fis-20 ta’ Jannar, 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribe, u/v1/audio/translationsfis-26 ta’ Frar, 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Għal-leħen full-duplex, GPT-Live 1 kien disponibbli fl-API mill-10 ta’ Settembru, 2026.
Imsewwi fit-3 ta’ Novembru, 2026. It-traskrizzjoni tal-input użat
gpt-live-transcribe, li taħdem biss f’sessjoni ta’ traskrizzjoni u ma tappoġġjaxserver_vadjewsemantic_vad. F’sessjoni ta’ konversazzjoni bħal din, fejn il-VAD jivvalida kull dawra, id-dokumentazzjoni tispeċifikagpt-transcribe, li tittraskrivi d-dawriet ivvalidati u tuża d-dawriet preċedenti bħala kuntest. Sorsi: Traskrizzjoni Realtime · GPT-Transcribe · GPT-Live-Transcribe.
Ibni aġent vokali sħiħ
Din il-lezzjoni tiġbor flimkien il-kunċetti kollha koperti sa issa biex tibni aġent vokali funzjonali komplet minn tarf għal tarf. Se toħloq assistent li jisma’ lill-utent, jifhem it-talba tiegħu, jesegwixxi azzjonijiet, u jwieġeb bil-leħen—kollox f’ħin reali permezz tal-API Realtime.
Arkitettura tal-aġent
Erba’ moduli, u fuq kollox restrizzjoni waħda li tmexxi l-arkitettura kollha: kollox irid iseħħ fl-istess ħin. Il-mikrofonu jaqbad waqt li l-mudell iwieġeb, l-avvenimenti jaslu waqt li l-awdjo jindaqq, u l-utent jista’ jinterrompi f’kull mument. Aġent vokali mhuwiex ċiklu ta’ mistoqsija u tweġiba; huwa sistema fejn flussi multipli javvanzaw parallellament—għalhekk niddependu ħafna fuq asyncio f’dak li ġej.
Il-klassi VoiceAgent
Il-klassi tiġbor l-istat li dawn il-flussi paralleli għandhom jaqsmu: il-konnessjoni, is-sessjoni attwali, u t-tweġiba li qed tintlagħab bħalissa. Preċiżament għaliex kompiti multipli jaċċessaw dan l-istat simultanjament, oġġett huwa preferibbli għal sett ta’ varjabbli globali—meta jkollok bżonn tikkanċella tweġiba għaddejja, trid tkun taf li teżisti waħda.
import asyncio
import json
import base64
import websockets
import sounddevice as sd
import numpy as np
import pyaudio
class VoiceAgent:
"""Aġent vokali sħiħ ibbażat fuq l-API Realtime."""
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):
"""Tistabbilixxi l-konnessjoni u tikkonfigura s-sessjoni."""
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)
# Stenna session.created
event = json.loads(await self.ws.recv())
print(f"Sessjoni: {event['session']['id']}")
# Ikkonfigura
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("L-aġent vokali lest.")
async def start(self):
"""Jibda l-aġent vokali."""
await self.connect()
await asyncio.gather(
self._capture_audio(),
self._process_events()
)
Modulu tal-qbid tal-awdjo
async def _capture_audio(self):
"""Jaqbad l-input tal-mikrofonu u jibgħatu lill-API Realtime."""
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
}))
Modulu tal-ipproċessar tal-avvenimenti
async def _process_events(self):
"""Jipproċessa l-avvenimenti kollha mis-server."""
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"\nŻball: {event['error']['message']}")
finally:
player.close()
pa.terminate()
Modulu tal-ġestjoni tal-għodod
Dan il-modulu jibdel l-aġent minn chatbot vokali sempliċi għal assistent kapaċi jieħu azzjoni. Id-differenza mis-sejħa tal-funzjoni klassika tinsab fir-restrizzjoni tal-ħin: l-utent huwa fuq il-linja mingħajr l-ebda indikatur viżiv tal-progress. Jekk l-eżekuzzjoni tieħu aktar minn sekonda jew tnejn, agħmel l-aġent jitkellem waqt li jaħdem—“Ħa niċċekkja dik għalik issa”—għax is-skiet f’konversazzjoni vokali jidher bħala ħsara.
async def _handle_response_done(self, event):
"""Jimmaniġġja s-sejħiet tal-funzjonijiet fit-tweġiba."""
response = event["response"]
function_calls = [
o for o in response.get("output", [])
if o["type"] == "function_call"
]
if not function_calls:
print() # Linja ġdida wara t-traskrizzjoni
return
for call in function_calls:
name = call["name"]
args = json.loads(call["arguments"])
call_id = call["call_id"]
print(f"\n→ {name}({args})")
# Eżegwixxi l-funzjoni (addatta għal-loġika tan-negozju tiegħek)
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)
}
}))
# Itlob lill-mudell biex ikompli
await self.ws.send(json.dumps({"type": "response.create"}))
async def _execute_function(self, name: str, args: dict) -> dict:
"""Jiddistribwixxi s-sejħa tal-funzjoni."""
# Implimenta skont il-loġika tan-negozju tiegħek
return {"error": f"Funsjoni {name} mhux implimentata"}
Neddi l-aġent
async def main():
agent = VoiceAgent(
api_key="sk-...",
instructions=(
"Int assistent vokali għal Corsen AI. "
"Tgħin lill-utenti jimmaniġġjaw l-appuntamenti tagħhom "
"u jiksbu informazzjoni dwar is-servizzi tagħna. "
"Wieġeb bil-Franċiż, b'mod konċiż u professjonali."
),
tools=[
{
"type": "function",
"name": "check_availability",
"description": "Jiċċekkja d-disponibbiltà għal ħin partikolari",
"parameters": {
"type": "object",
"properties": {
"date": {"type": "string"},
"service": {"type": "string"}
},
"required": ["date"]
}
}
]
)
await agent.start()
asyncio.run(main())
Punti Ewlenin
- Aġent vokali sħiħ jgħaqqad erba’ moduli: awdjo, sessjoni, għodod, u ġestjoni tal-istat
- Il-klassi
VoiceAgenttinkapsula l-loġika kollha wara interfaċċa sempliċi asyncio.gatherjippermetti l-qbid tal-mikrofonu u l-ipproċessar tal-avvenimenti paralleli- L-immaniġġjar tal-interruzzjonijiet (li tikkanċella tweġiba meta l-utent jitkellem) huwa essenzjali
- L-għodod ibiddlu l-aġent minn chatbot vokali sempliċi għal assistent kapaċi jieħu azzjoni