Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Δημιουργία ενός πλήρους φωνητικού πράκτορα

Μάθημα 14 / 18 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Δημιουργία ενός πλήρους φωνητικού πράκτορα
  2. Αρχιτεκτονική πράκτορα
  3. Η κλάση VoiceAgent
  4. Ενότητα καταγραφής ήχου
  5. Ενότητα επεξεργασίας γεγονότων
  6. Ενότητα διαχείρισης εργαλείων
  7. Εκκίνηση του πράκτορα
  8. Βασικά σημεία

Ενημερώθηκε στις 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 στη συνέχεια.

Audio
Capture and playback
Session
WebSocket and config
Tools
Business actions
State
Conversation management

Η κλάση 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())

Βασικά σημεία

  • Ένας πλήρης φωνητικός πράκτορας συνδυάζει τέσσερις ενότητες: ήχο, συνεδρία, εργαλεία και διαχείριση κατάστασης
  • Η κλάση VoiceAgent encapsulates όλη τη λογική πίσω από μια απλή διεπαφή
  • Το asyncio.gather επιτρέπει την παράλληλη καταγραφή από το μικρόφωνο και την επεξεργασία γεγονότων
  • Ο χειρισμός των διακοπών (ακύρωση μιας απόκρισης όταν μιλάει ο χρήστης) είναι απαραίτητος
  • Τα εργαλεία μετατρέπουν τον πράκτορα από έναν απλό φωνητικό chatbot σε έναν βοηθό ικανό για δράση