Open in
Χρησιμοποιήστε το ThunderPhone με προγράμματα-πελάτες OpenAI Realtime
Κατευθύνετε ένα πρόγραμμα-πελάτη διακομιστή συμβατό με OpenAI Realtime στο ThunderPhone, χρησιμοποιώντας είτε έναν αποθηκευμένο πράκτορα είτε ενσωματωμένη διαμόρφωση συνεδρίας.
Το ThunderPhone υλοποιεί ένα στοχευμένο υποσύνολο του μοντέλου συμβάντων OpenAI Realtime. Ένας υπάρχων client στην πλευρά του διακομιστή μπορεί να διατηρεί τη ροή συμβάντων WebSocket, ήχου, συνεδρίας και απόκρισης, ενώ χρησιμοποιεί έναν φωνητικό πράκτορα ThunderPhone.
Πριν συνδεθείτε
Χρειάζεστε ένα μυστικό κλειδί API οργανισμού ThunderPhone και ένα περιβάλλον εκτέλεσης διακομιστή που μπορεί να ανοίγει WebSockets. Μην συνδέεστε από κώδικα προγράμματος περιήγησης και μην εκθέτετε το κλειδί σε πρόγραμμα περιήγησης. Για να χρησιμοποιήσετε έναν αποθηκευμένο πράκτορα, αναπτύξτε τον πρώτα και αντιγράψτε το αριθμητικό αναγνωριστικό πράκτορά του.
Συνδεθείτε στο:
wss://api.thunderphone.com/v1/realtimeΠραγματοποιήστε έλεγχο ταυτότητας για την αναβάθμιση WebSocket από τον διακομιστή σας:
Authorization: Bearer sk_live_YOUR_API_KEYΟ έλεγχος ταυτότητας μέσω συμβολοσειράς ερωτήματος είναι διαθέσιμος για clients που δεν μπορούν να ορίσουν κεφαλίδες χειραψίας, αλλά οι διευθύνσεις URL διαρρέουν ευκολότερα σε αρχεία καταγραφής.
Επιλέξτε ποιος διαχειρίζεται τη ρύθμιση παραμέτρων
| Λειτουργία | Επιλέξτε τη με | Πηγή διαμόρφωσης |
|---|---|---|
| Αποθηκευμένος πράκτορας | session.prompt.id στο πρώτο session.update ή ?agent_id=12 | Αναπτυγμένο prompt, φωνή, προϊόν, γλώσσες, γνώση και συμβατά εργαλεία που εκτελούνται στον διακομιστή, καθώς και οι οδηγίες και οι μεταβλητές αυτής της συνεδρίας |
| Ενσωματωμένη | Καμία από τις δύο | Το πρώτο αποδεκτό session.update από τον πελάτη σας |
Αποθηκευμένος πράκτορας
Διατηρήστε όσα μοιράζεται κάθε κλήση σε έναν αποθηκευμένο πράκτορα, όπου διαθέτει εκδόσεις και σύνολα δοκιμών, και στείλτε όσα αλλάζουν ανά συνεδρία στο πρώτο session.update:
το session.prompt.id επιλέγει τον αναπτυγμένο πράκτορα, το session.instructions περιέχει τη σύντομη περιγραφή αυτής της συνεδρίας και το session.prompt.variables συμπληρώνει τα δεσμευτικά θέσης {{name}} στην προτροπή του πράκτορα.
{
"type": "session.update",
"session": {
"type": "realtime",
"prompt": {
"id": "12",
"variables": { "user_name": "Ada Park" }
},
"instructions": "Ada is a Costco member in Mountain View. Call the store and ask for today's opening hours.",
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 } },
"output": { "format": { "type": "audio/pcm", "rate": 24000 } }
}
}
}Οι οδηγίες γίνονται το περιβάλλον της κλήσης,
οι οποίες προστίθενται μετά την προτροπή του πράκτορα μόνο για αυτή την κλήση. Οι επιλογές της ίδιας της συνεδρίας
(telephony, outbound, ivr_mode, call_events, placeholders) και η
γλώσσα με την οποία ξεκινά (primary_language) τοποθετούνται στο session.config, όπως σε μια
ενσωματωμένη συνεδρία. Η φωνή, το προϊόν και τα εργαλεία του πράκτορα προέρχονται από την αναπτυγμένη
διαμόρφωσή του: μια φωνή, μια άλλη ρύθμιση πράκτορα ή ένα πεδίο μόνο για OpenAI, όπως
ένα μη προεπιλεγμένο tool_choice στην ενημέρωση, παράγει ένα συμβάν error και αγνοείται, ενώ
τα εργαλεία που εκτελεί ο πελάτης σας απορρίπτονται (τα εργαλεία που εκτελούνται από τον πελάτη χρειάζονται
ενσωματωμένη συνεδρία). Το prompt.version γίνεται δεκτό και αγνοείται. Δείτε το Χρήση αποθηκευμένου
πράκτορα για κάθε κανόνα.
Η σύνδεση με ?agent_id=12 εκκινεί αντίθετα τον πράκτορα καθώς συνδέεται η υποδοχή,
επομένως δεν απαιτείται session.update, αλλά η διαμόρφωση της συνεδρίας του είναι
τότε σταθερή: οδηγίες, μεταβλητές και επιλογές συνεδρίας (outbound,
ivr_mode, telephony, placeholders, call_events) που αποστέλλονται μετά από αυτό
απορρίπτονται με συμβάν error. Προσθέστε
&wait_for_session_update=1 στο URL για να τον εκκινήσετε αντίθετα στο πρώτο σας
session.update, το οποίο στη συνέχεια μεταφέρει οδηγίες, μεταβλητές και επιλογές
συνεδρίας με τον ίδιο τρόπο· μια εξερχόμενη συνεδρία το χρειάζεται αυτό. Μέχρι να φτάσει εκείνη η ενημέρωση, ο ήχος του καλούντος διατηρείται, άλλα συμβάντα
απορρίπτονται και η υποδοχή κλείνει αν δεν φτάσει καμία εντός 10 δευτερολέπτων.
Ο χαιρετισμός παραμένει διαθέσιμος, αλλά το Realtime απενεργοποιεί τους φωνητικούς
ελέγχους σιωπής του πράκτορα και προσφέρει τα transfer_call και send_keypad_input μόνο με
call_events. Άλλα συμβατά εργαλεία εκτελούνται στο ThunderPhone· τα εργαλεία που εκτελούνται από τον πελάτη χρειάζονται ενσωματωμένη συνεδρία. Οι μορφές ήχου και οι οδηγίες και μεταβλητές της συνεδρίας δεν μπορούν
να αλλάξουν μετά την έναρξη της κλήσης.
Ενσωματωμένη συνεδρία
Χωρίς αποθηκευμένο πράκτορα, περιμένετε το session.created και, στη συνέχεια, στείλτε session.update:
{
"type": "session.update",
"session": {
"type": "realtime",
"instructions": "Answer questions clearly and keep responses brief.",
"audio": {
"input": {
"format": { "type": "audio/pcm", "rate": 24000 }
},
"output": {
"format": { "type": "audio/pcm", "rate": 24000 },
"voice": "olivia"
}
},
"config": {
"product": "bolt"
}
}
}Η πρώτη αποδεκτή ενημέρωση προετοιμάζει την κλήση. Το session.updated σημαίνει ότι η συνεδρία είναι ενεργή. Οι οδηγίες, η φωνή, το προϊόν, τα εργαλεία και οι μορφές ήχου δεν μπορούν να αλλάξουν μετά από αυτό το σημείο. Για να διατηρήσετε σταθερές τις οδηγίες και να μεταβάλλετε μόνο ονομασμένες τιμές, γράψτε σε αυτές placeholders {{name}} και στείλτε τις τιμές στο session.config.variables.
Οι ενσωματωμένες συνεδρίες δεν έχουν αυτόματο χαιρετισμό ή προφορικούς ελέγχους σιωπής. Για να
κάνετε τον πράκτορα να μιλήσει πρώτος, προσθέστε ένα μήνυμα συστήματος ή χρήστη και στείλτε
response.create. Μια εντελώς ανενεργή συνεδρία εξακολουθεί να τερματίζεται στο όριο σιωπηλής κλήσης της πλατφόρμας, που είναι 600 δευτερόλεπτα από προεπιλογή.
Χρησιμοποιήστε το επίσημο SDK της OpenAI
Περάστε ένα βασικό URL WebSocket που τελειώνει σε /v1; το SDK προσθέτει το /realtime. Η
τιμή model είναι όνομα συμβατότητας και δεν επιλέγει το προϊόν ThunderPhone.
Επιλέξτε το προϊόν στη διαμόρφωση συνεδρίας ή στον αποθηκευμένο πράκτορα.
Αυτός ο έλεγχος σύνδεσης δημιουργεί μια ενσωματωμένη συνεδρία Bolt, εκτυπώνει συμβάντα μέχρι το
πρώτο session.updated και κλείνει. Χρησιμοποιήστε τον ελάχιστο πελάτη
Python για ροή ήχου.
import asyncio
import os
from openai import AsyncOpenAI
async def main():
client = AsyncOpenAI(
api_key=os.environ["THUNDERPHONE_API_KEY"],
websocket_base_url="wss://api.thunderphone.com/v1",
)
async with client.realtime.connect(
model="thunderphone-realtime"
) as connection:
await connection.session.update(session={
"type": "realtime",
"instructions": "Listen to the caller and help them complete the call.",
"config": {"product": "bolt"},
})
async for event in connection:
print(event.type)
if event.type == "session.updated":
break
if __name__ == "__main__":
asyncio.run(main())Διατηρήστε τον υπάρχοντα χειρισμό σας για προσθήκη ήχου εισόδου, δέλτα ήχου απόκρισης, διακοπές, κλήσεις συναρτήσεων, σφάλματα και καθαρό κλείσιμο υποδοχής. Οι ενσωματωμένες προσαρμοσμένες συναρτήσεις εκτελούνται στον πελάτη σας· επιστρέψτε τα αποτελέσματά τους μέσω του πρωτοκόλλου Realtime. Τα εργαλεία αποθηκευμένων πρακτόρων εκτελούνται στο ThunderPhone.
Κύκλος ζωής συνεδρίας και αποτυχίες
Ένα WebSocket αντιστοιχεί σε μία κλήση. Ένα μη έγκυρο αναγνωριστικό πράκτορα ή μια
απορριφθείσα ενσωματωμένη διαμόρφωση παράγει ένα συμβάν error. Περιμένετε το
session.updated πριν θεωρήσετε τη συνεδρία ενεργή. Δηλώστε τις πραγματικές μορφές
εισόδου και εξόδου και τους ρυθμούς δειγματοληψίας: μια ασυμφωνία ρυθμού PCM
αναπαράγει ήχο υπερβολικά γρήγορα ή αργά αντί να παράγει σφάλμα επικύρωσης.
Αφού ξεκινήσει η συνεδρία, κλείστε καθαρά το socket όταν ολοκληρωθεί η εφαρμογή σας. Οι ενσωματωμένες συνεδρίες μπορούν να χρησιμοποιούν συναρτήσεις που εκτελούνται από τον πελάτη. Οι συνεδρίες αποθηκευμένων πρακτόρων χρησιμοποιούν συμβατά εργαλεία που εκτελούνται από το ThunderPhone και προσφέρουν το transfer_call (καθώς και το send_keypad_input σε εξερχόμενες συνεδρίες) μόνο με call_events; ο πελάτης σας εκτελεί αυτά τα συμβάντα call.*.
Δοκιμάστε την ενσωμάτωση
Ξεκινήστε με τον ελάχιστο πελάτη Python WAV και ένα μονοφωνικό PCM16 WAV στον δηλωμένο ρυθμό του. Επαληθεύστε τα εξής:
- Ο διακομιστής αποδέχεται τη διαμόρφωση και στέλνει
session.updated. - Η είσοδος παράγει συμβάντα απομαγνητοφώνησης και ήχου απόκρισης στην αναμενόμενη ταχύτητα.
- Η διακοπή και η ακύρωση απόκρισης σταματούν τον υπόλοιπο ήχο εξόδου.
- Τα αποτελέσματα ενσωματωμένων συναρτήσεων ή τα αποτελέσματα εργαλείων αποθηκευμένων πρακτόρων επιστρέφουν στο μοντέλο.
- Η μη έγκυρη είσοδος παράγει ένα συμβάν
errorπου χειρίζεται ο πελάτης σας. - Ο πελάτης σας κλείνει την υποδοχή και η κλήση εμφανίζεται στο Ιστορικό κλήσεων.
Η αναφορά Realtime WebSocket παραθέτει τα αποδεκτά συμβάντα, τις μορφές ήχου, τα πεδία συνεδρίας και πλήρη παραδείγματα.
Κόστος
Οι κλήσεις Realtime τιμολογούνται όπως κάθε άλλη κλήση: με βάση το κόστος των επιμέρους στοιχείων τους στις τιμές καταλόγου των παρόχων μας, συν μια χρέωση υποδομής και περιθώριο 17–25%. Η ενεργοποίηση ενημερώσεων ζωντανής απομαγνητοφώνησης προσθέτει εργασία απομαγνητοφώνησης για ολόκληρη τη συνεδρία· δείτε Ζωντανές απομαγνητοφωνήσεις και Τιμολόγηση.
Το POST /v1/realtime/sessions είναι ξεχωριστή διαχειριζόμενη διαδρομή LiveKit. Δημιουργεί ένα
δωμάτιο και διακριτικό συμμετέχοντα περιορισμένου εύρους· δεν απαιτείται για άμεση
σύνδεση WebSocket.
Για ενσωματώσεις πλαισίων, δείτε Χρησιμοποιήστε το ThunderPhone από το Pipecat και Χρησιμοποιήστε το ThunderPhone από τους LiveKit Agents.