A ThunderPhone használata OpenAI Realtime kliensekkel

Irányítson egy OpenAI Realtime-kompatibilis szerverklienset a ThunderPhone-ra mentett ügynök vagy beágyazott munkamenet-konfiguráció használatával.

A ThunderPhone az OpenAI Realtime eseménymodelljének célzott részhalmazát valósítja meg. Egy meglévő szerveroldali kliens megtarthatja a WebSocket-, hang-, munkamenet- és válaszesemény-folyamatát, miközben ThunderPhone hangalapú AI-ügynököt használ.

Csatlakozás előtt#

Szüksége van egy ThunderPhone-szervezeti titkos API-kulcsra és egy olyan szerverkörnyezetre, amely képes WebSocketeket megnyitni. Ne csatlakozzon böngészőkódból, és ne tegye elérhetővé a kulcsot böngésző számára. Mentett ügynök használatához először telepítse azt, majd másolja ki a numerikus ügynökazonosítóját.

Csatlakozzon ehhez:

wss://api.thunderphone.com/v1/realtime

Hitelesítse a WebSocket-frissítést a szerveréről:

Authorization: Bearer sk_live_YOUR_API_KEY

A lekérdezési karakterláncos hitelesítés elérhető azokhoz a kliensekhez, amelyek nem tudnak kézfogási fejléceket beállítani, de az URL-ek könnyebben kiszivárognak a naplókba.

Válassza ki, ki kezeli a konfigurációt#

Mentett ügynök#

Csatlakozzon a telepített ügynökazonosítóval:

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

Az ügynök a kapcsolat létrejötte közben elindul. A köszönése továbbra is elérhető, de a Realtime letiltja a kimondott csendellenőrzéseit, és kihagyja a transfer_call és send_keypad_input eszközöket. Más kompatibilis eszközök a ThunderPhone-on futnak. Ehhez a módhoz ne küldjön beágyazott utasításokat vagy kliens által végrehajtott eszközöket.

Az ügynök indulása előtt állítsa be az átviteli hangot az input_audio_format, output_audio_format, input_rate és output_rate lekérdezési paraméterekkel. A mentett konfigurációt és a hangformátumokat a csatlakozás után nem módosíthatja.

Beágyazott munkamenet#

agent_id nélkül várja meg a session.created eseményt, majd küldje el a session.update üzenetet:

{
  "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"
    }
  }
}

Az első elfogadott frissítés létrehozza a hívást. A session.updated azt jelenti, hogy a munkamenet aktív. Az utasítások, a hang, a termék, az eszközök és a hangformátumok ezt követően nem módosíthatók.

A beágyazott munkamenetekhez nem tartozik automatikus köszönés vagy kimondott csendellenőrzés. Ha azt szeretné, hogy az ügynök szólaljon meg először, fűzzön hozzá egy rendszer- vagy felhasználói üzenetet, és küldje el a response.create üzenetet. A teljesen inaktív munkamenet továbbra is a platform néma hívási korlátjánál ér véget, amely alapértelmezés szerint 600 másodperc.

Használja a hivatalos OpenAI SDK-t#

Adjon meg egy /v1 végződésű WebSocket-alap URL-t; az SDK hozzáfűzi a /realtime útvonalat. A model érték kompatibilitási név, és nem választja ki a ThunderPhone terméket. Válassza ki a terméket a munkamenet-konfigurációban vagy a mentett ügynökben.

Ez a kapcsolatellenőrzés beágyazott Bolt-munkamenetet hoz létre, eseményeket ír ki az első session.updated eseményig, majd bezárja a kapcsolatot. Hang streameléséhez használja a minimális Python klienst.

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())

Őrizze meg meglévő kezelését a bemeneti hang hozzáfűzéséhez, a válaszhang-deltákhoz, megszakításokhoz, függvényhívásokhoz, hibákhoz és a socket tiszta lezárásához. A beágyazott egyéni függvények az Ön kliensében futnak; eredményeiket a Realtime protokollon keresztül küldje vissza. A mentett ügynök eszközei a ThunderPhone-on futnak.

Munkamenet-életciklus és hibák#

Egy WebSocket egy hívást képvisel. Érvénytelen ügynökazonosító vagy elutasított beágyazott konfiguráció error eseményt eredményez. Várja meg a session.updated eseményt, mielőtt aktívként kezelné a munkamenetet. Adja meg a tényleges bemeneti és kimeneti formátumokat, valamint mintavételi frekvenciákat: a nem egyező PCM-mintavételi frekvencia túl gyorsan vagy túl lassan játssza le a hangot, nem pedig validálási hibát eredményez.

A munkamenet indulása után zárja le tisztán a socketet, amikor az alkalmazása befejezte a műveletet. A beágyazott munkamenetek kliensoldalon végrehajtott függvényeket használhatnak. A mentett ügynökös munkamenetek kompatibilis, ThunderPhone által futtatott eszközöket használnak, és nem kínálnak hívásátirányítást vagy billentyűzetes bevitelt.

Az integráció tesztelése#

Kezdje a minimális Python WAV klienssel és egy monó PCM16 WAV-fájllal a megadott mintavételi frekvencián. Ellenőrizze a következőket:

1. A szerver elfogadja a konfigurációt, és elküldi a session.updated eseményt.
2. A bemenet a várt sebességgel generál átírási és válaszhang-eseményeket.
3. A megszakítás és a válasz megszakítása leállítja a fennmaradó kimeneti hangot.
4. A beágyazott függvények eredményei vagy a mentett ügynök eszközeinek eredményei visszakerülnek a modellhez.
5. Az érvénytelen bemenet olyan error eseményt eredményez, amelyet a kliense kezel.
6. A kliense lezárja a socketet, és a hívás megjelenik a Híváselőzményekben.

A Realtime WebSocket referencia felsorolja az elfogadott eseményeket, hangformátumokat, munkamenetmezőket és teljes példákat.

Költség#

A Realtime hívások a kiválasztott termék normál percdíját használják. Az élő átiratdelták engedélyezése a teljes munkamenetre percdíjas felárat számít fel; a díjért lásd az Élő átiratok, a termékdíjakért pedig az Árak oldalt.

A POST /v1/realtime/sessions különálló, felügyelt LiveKit útvonal. Szobát és hatókörhöz kötött résztvevői tokent hoz létre; közvetlen WebSocket-kapcsolathoz nincs rá szükség.

Keretrendszer-integrációkhoz lásd a ThunderPhone használata Pipecatből és a ThunderPhone használata LiveKit Agentsből útmutatót.