Δημιουργία ενός πλήρους φωνητικού πράκτορα
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 2 Νοεμβρίου 2026 — Μοντέλα ήχου. Αρκετά μοντέλα σε αυτό το μάθημα έχουν καταργηθεί: τα
tts-1,tts-1-hdκαιgpt-4o-mini-ttsθα σταματήσουν να λειτουργούν στις 6 Ιανουαρίου 2027 (διάδοχος:gpt-realtime-2.1-mini, το οποίο ο οδηγός OpenAI TTS αναφέρει ότι δεν υποστηρίζεται από το/v1/audio/speech: η μετάβαση στη σύνθεση ομιλίας μεταφέρεται στο Realtime API)· ταgpt-realtime,gpt-4o-realtimeκαι τα παλαιότερα μοντέλα ήχου στις 20 Ιανουαρίου 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5)· ταwhisper-1,gpt-4o-transcribeκαι το/v1/audio/translationsστις 26 Φεβρουαρίου 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Για επικοινωνία πλήρους διπλής κατεύθυνσης (full-duplex), το GPT-Live 1 είναι διαθέσιμο στο API από τις 10 Σεπτεμβρίου 2026.
Διορθώθηκε στις 3 Νοεμβρίου 2026. Η μεταγραφή εισόδου χρησιμοποιούσε το
gpt-live-transcribe, το οποίο λειτουργεί μόνο σε συνεδρία μεταγραφής και δεν υποστηρίζει ούτεserver_vadούτεsemantic_vad. Σε μια συνεδρία συνομιλίας όπως αυτή, όπου το VAD επικυρώνει κάθε στροφή, η τεκμηρίωση ορίζει τη χρήση τουgpt-transcribe, το οποίο μεταγράφει επικυρωμένες στροφές και χρησιμοποιεί προηγούμενες στροφές ως πλαίσιο. Πηγές: Μεταγραφή σε πραγματικό χρόνο · GPT-Transcribe · GPT-Live-Transcribe.
Δημιουργία ενός πλήρους φωνητικού πράκτορα
Αυτό το μάθημα συνδυάζει όλες τις έννοιες που καλύφθηκαν έως τώρα για τη δημιουργία ενός πλήρως λειτουργικού φωνητικού πράκτορα από άκρο σε άκρο. Θα δημιουργήσετε έναν βοηθό που ακούει τον χρήστη, κατανοεί το αίτημά του, εκτελεί ενέργειες και απαντά φωνητικά—όλα σε πραγματικό χρόνο μέσω του Realtime API.
Αρχιτεκτονική πράκτορα
Τέσσερις ενότητες και, πάνω απ’ όλα, ένας περιορισμός που καθοδηγεί ολόκληρη την αρχιτεκτονική: όλα πρέπει να συμβαίνουν ταυτόχρονα. Το μικρόφωνο καταγράφει ενώ το μοντέλο απαντά, τα γεγονότα φτάνουν ενώ αναπαράγεται ο ήχος και ο χρήστης μπορεί να διακόψει οποιαδήποτε στιγμή. Ένας φωνητικός πράκτορας δεν είναι ένας βρόχος ερώτησης-απάντησης· είναι ένα σύστημα όπου πολλαπλές ροές προχωρούν παράλληλα—γι’ αυτό βασιζόμαστε έντονα στο asyncio στη συνέχεια.
Η κλάση VoiceAgent
Η κλάση συγκεντρώνει την κατάσταση που πρέπει να κοινοποιούν αυτές οι παράλληλες ροές: τη σύνδεση, την τρέχουσα συνεδρία και την απόκριση που αναπαράγεται εκείνη τη στιγμή. Ακριβώς επειδή πολλαπλές εργασίες αποκτούν πρόσβαση σε αυτή την κατάσταση ταυτόχρονα, ένα αντικείμενο είναι προτιμότερο από ένα σύνολο καθολικών μεταβλητών—όταν χρειάζεται να ακυρώσετε μια ongoing απόκριση, πρέπει να γνωρίζετε ότι υπάρχει.
import asyncio
import json
import base64
import websockets
import sounddevice as sd
import numpy as np
import pyaudio
class VoiceAgent:
"""Complete voice agent based on the 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):
"""Establishes the connection and configures the session."""
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)
# Wait for session.created
event = json.loads(await self.ws.recv())
print(f"Session: {event['session']['id']}")
# Configure
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("Voice agent ready.")
async def start(self):
"""Starts the voice agent."""
await self.connect()
await asyncio.gather(
self._capture_audio(),
self._process_events()
)
Ενότητα καταγραφής ήχου
async def _capture_audio(self):
"""Captures microphone input and sends it to the 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
}))
Ενότητα επεξεργασίας γεγονότων
async def _process_events(self):
"""Processes all events from the 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"\nError: {event['error']['message']}")
finally:
player.close()
pa.terminate()
Ενότητα διαχείρισης εργαλείων
Αυτή η ενότητα μετατρέπει τον πράκτορα από έναν απλό φωνητικό chatbot σε έναν βοηθό ικανό να αναλαμβάνει δράση. Η διαφορά από την κλασική κλήση συναρτήσεων έγκειται στον χρονικό περιορισμό: ο χρήστης βρίσκεται στη γραμμή χωρίς οπτική ένδειξη προόδου. Εάν η εκτέλεση διαρκεί περισσότερο από ένα ή δύο δευτερόλεπτα, κάντε τον πράκτορα να μιλήσει ενώ εργάζεται—«Ας το ελέγξω αυτό για εσάς αμέσως»—επειδή η σιωπή σε μια φωνητική συνομιλία ακούγεται σαν δυσλειτουργία.
async def _handle_response_done(self, event):
"""Handles function calls in the response."""
response = event["response"]
function_calls = [
o for o in response.get("output", [])
if o["type"] == "function_call"
]
if not function_calls:
print() # New line after transcription
return
for call in function_calls:
name = call["name"]
args = json.loads(call["arguments"])
call_id = call["call_id"]
print(f"\n→ {name}({args})")
# Execute the function (adapt to your business logic)
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)
}
}))
# Ask the model to continue
await self.ws.send(json.dumps({"type": "response.create"}))
async def _execute_function(self, name: str, args: dict) -> dict:
"""Dispatches the function call."""
# Implement according to your business logic
return {"error": f"Function {name} not implemented"}
Εκκίνηση του πράκτορα
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())
Βασικά σημεία
- Ένας πλήρης φωνητικός πράκτορας συνδυάζει τέσσερις ενότητες: ήχο, συνεδρία, εργαλεία και διαχείριση κατάστασης
- Η κλάση
VoiceAgentencapsulates όλη τη λογική πίσω από μια απλή διεπαφή - Το
asyncio.gatherεπιτρέπει την παράλληλη καταγραφή από το μικρόφωνο και την επεξεργασία γεγονότων - Ο χειρισμός των διακοπών (ακύρωση μιας απόκρισης όταν μιλάει ο χρήστης) είναι απαραίτητος
- Τα εργαλεία μετατρέπουν τον πράκτορα από έναν απλό φωνητικό chatbot σε έναν βοηθό ικανό για δράση