Το ThunderPhone 2.0 είναι εδώ.Ξεκινήστε μόνοι σας, από 2¢/λεπτό.Διαβάστε την ανακοίνωση
Ξεκινήστε

Connect tools & data

View as Markdown
Open in
ClaudeChatGPTCursor

Χρησιμοποιήστε το 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 διαρρέουν ευκολότερα σε αρχεία καταγραφής.

Επιλέξτε ποιος διαχειρίζεται τη ρύθμιση παραμέτρων

ΛειτουργίαΣύνδεση μεΠηγή ρυθμίσεων
Αποθηκευμένος πράκτορας?agent_id=12Αναπτυγμένη προτροπή, φωνή, προϊόν, γλώσσες, γνώση και συμβατά εργαλεία που εκτελούνται στον διακομιστή
ΕνσωματωμένηΧωρίς agent_idΤο πρώτο αποδεκτό session.update από τον client σας

Αποθηκευμένος πράκτορας

Συνδεθείτε με το αναπτυγμένο αναγνωριστικό πράκτορα:

wss://api.thunderphone.com/v1/realtime?agent_id=12

Ο πράκτορας ξεκινά καθώς συνδέεται το socket. Ο χαιρετισμός του παραμένει διαθέσιμος, αλλά το Realtime απενεργοποιεί τους προφορικούς ελέγχους σιωπής και παραλείπει τα transfer_call και send_keypad_input. Άλλα συμβατά εργαλεία εκτελούνται στο ThunderPhone. Μην στείλετε ενσωματωμένες οδηγίες ή εργαλεία που εκτελούνται από τον client για αυτή τη λειτουργία.

Ορίστε τον ήχο μεταφοράς πριν ξεκινήσει ο πράκτορας με τις παραμέτρους ερωτήματος input_audio_format, output_audio_format, input_rate και output_rate. Δεν μπορείτε να αλλάξετε την αποθηκευμένη ρύθμιση παραμέτρων ή τις μορφές ήχου μετά τη σύνδεση.

Ενσωματωμένη συνεδρία

Χωρίς agent_id, περιμένετε το 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 σημαίνει ότι η συνεδρία είναι ενεργή. Οι οδηγίες, η φωνή, το προϊόν, τα εργαλεία και οι μορφές ήχου δεν μπορούν να αλλάξουν μετά από αυτό το σημείο.

Οι ενσωματωμένες συνεδρίες δεν έχουν αυτόματο χαιρετισμό ή προφορικούς ελέγχους σιωπής. Για να κάνετε τον πράκτορα να μιλήσει πρώτος, προσθέστε ένα μήνυμα συστήματος ή χρήστη και στείλτε 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 αναπαράγει ήχο υπερβολικά γρήγορα ή αργά αντί να παράγει σφάλμα επικύρωσης.

Αφού ξεκινήσει η συνεδρία, κλείστε καθαρά την υποδοχή όταν ολοκληρωθεί η εφαρμογή σας. Οι ενσωματωμένες συνεδρίες μπορούν να χρησιμοποιούν συναρτήσεις που εκτελούνται από τον πελάτη. Οι συνεδρίες αποθηκευμένων πρακτόρων χρησιμοποιούν συμβατά εργαλεία που εκτελούνται από το ThunderPhone και δεν προσφέρουν μεταφορά ή είσοδο πληκτρολογίου.

Δοκιμάστε την ενσωμάτωση

Ξεκινήστε με τον ελάχιστο πελάτη Python WAV και ένα μονοφωνικό PCM16 WAV στον δηλωμένο ρυθμό του. Επαληθεύστε τα εξής:

  1. Ο διακομιστής αποδέχεται τη διαμόρφωση και στέλνει session.updated.
  2. Η είσοδος παράγει συμβάντα απομαγνητοφώνησης και ήχου απόκρισης στην αναμενόμενη ταχύτητα.
  3. Η διακοπή και η ακύρωση απόκρισης σταματούν τον υπόλοιπο ήχο εξόδου.
  4. Τα αποτελέσματα ενσωματωμένων συναρτήσεων ή τα αποτελέσματα εργαλείων αποθηκευμένων πρακτόρων επιστρέφουν στο μοντέλο.
  5. Η μη έγκυρη είσοδος παράγει ένα συμβάν error που χειρίζεται ο πελάτης σας.
  6. Ο πελάτης σας κλείνει την υποδοχή και η κλήση εμφανίζεται στο Ιστορικό κλήσεων.

Η αναφορά Realtime WebSocket παραθέτει τα αποδεκτά συμβάντα, τις μορφές ήχου, τα πεδία συνεδρίας και πλήρη παραδείγματα.

Κόστος

Οι κλήσεις Realtime χρησιμοποιούν την κανονική ανά λεπτό χρέωση του επιλεγμένου προϊόντος. Η ενεργοποίηση δέλτα ζωντανής απομαγνητοφώνησης προσθέτει μια ανά λεπτό επιβάρυνση για ολόκληρη τη συνεδρία· δείτε τις Ζωντανές απομαγνητοφωνήσεις για τη χρέωση και την Τιμολόγηση για τις χρεώσεις προϊόντων.

Το POST /v1/realtime/sessions είναι ξεχωριστή διαχειριζόμενη διαδρομή LiveKit. Δημιουργεί ένα δωμάτιο και διακριτικό συμμετέχοντα περιορισμένου εύρους· δεν απαιτείται για άμεση σύνδεση WebSocket.

Για ενσωματώσεις πλαισίων, δείτε Χρησιμοποιήστε το ThunderPhone από το Pipecat και Χρησιμοποιήστε το ThunderPhone από τους LiveKit Agents.