استخدم ThunderPhone مع عملاء OpenAI Realtime

وجّه عميلاً خادماً متوافقاً مع OpenAI Realtime إلى ThunderPhone باستخدام وكيل محفوظ أو إعداد جلسة مضمن.

يطبّق ThunderPhone مجموعة فرعية مركّزة من نموذج أحداث OpenAI Realtime. يمكن لعميل خادمي موجود أن يحتفظ بتدفق أحداث WebSocket والصوت والجلسة والاستجابة مع استخدام وكيل صوتي من ThunderPhone.

قبل الاتصال#

تحتاج إلى مفتاح API سري خاص بمؤسسة ThunderPhone وبيئة تشغيل خادمية يمكنها فتح اتصالات WebSocket. لا تتصل من رمز المتصفح ولا تكشف المفتاح للمتصفح. لاستخدام وكيل محفوظ، انشره أولًا وانسخ معرّف الوكيل الرقمي الخاص به.

اتصل بـ:

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

صادِق ترقية WebSocket من خادمك:

Authorization: Bearer sk_live_YOUR_API_KEY

تتوفر مصادقة سلسلة الاستعلام للعملاء الذين لا يمكنهم تعيين ترويسات المصافحة، لكن من الأسهل تسرّب عناوين URL إلى السجلات.

اختر الجهة المالكة للإعدادات#

وكيل محفوظ#

اتصل باستخدام معرّف الوكيل المنشور:

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

يبدأ الوكيل أثناء اتصال المقبس. تظل تحيته متاحة، لكن Realtime يعطّل رسائل التحقق المنطوقة أثناء الصمت ويحذف transfer_call وsend_keypad_input. تعمل الأدوات المتوافقة الأخرى على ThunderPhone. لا ترسل تعليمات مضمّنة أو أدوات ينفّذها العميل لهذا الوضع.

عيّن صوت النقل قبل بدء الوكيل باستخدام معامِلات الاستعلام 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 ثانية افتراضيًا.

استخدم حزمة OpenAI SDK الرسمية#

مرّر عنوان 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 المصغر وملف WAV أحادي القناة بترميز PCM16 ومعدل العينة المعلن فيه. تحقّق مما يلي:

1. يقبل الخادم التهيئة ويرسل session.updated.
2. ينتج الإدخال أحداث النص المفرغ وصوت الاستجابة بالسرعة المتوقعة.
3. توقف المقاطعة وإلغاء الاستجابة الصوت الناتج المتبقي.
4. تعود نتائج الدوال المضمنة أو نتائج أدوات الوكيل المحفوظ إلى النموذج.
5. ينتج الإدخال غير الصالح حدث error يعالجه عميلك.
6. يغلق عميلك المقبس وتظهر المكالمة في سجل المكالمات.

يسرد مرجع Realtime عبر WebSocket الأحداث المقبولة، وتنسيقات الصوت، وحقول الجلسة، والأمثلة الكاملة.

التكلفة#

تستخدم مكالمات Realtime المعدل العادي لكل دقيقة للمنتج المحدد. يؤدي تفعيل فروق النص المفرغ المباشر إلى إضافة تكلفة لكل دقيقة للجلسة كاملة؛ راجع النصوص المفرغة المباشرة لمعرفة المعدل والأسعار لمعرفة معدلات المنتجات.

POST /v1/realtime/sessions هو مسار LiveKit مُدار منفصل. ينشئ غرفة ورمز مشارك محدود النطاق؛ ولا يكون مطلوبًا لاتصال WebSocket مباشر.

لتكاملات الأطر، راجع استخدم ThunderPhone من Pipecat واستخدم ThunderPhone من وكلاء LiveKit.