Open in
ใช้ ThunderPhone กับไคลเอนต์ OpenAI Realtime
กำหนดให้ไคลเอนต์เซิร์ฟเวอร์ที่รองรับ OpenAI Realtime เชื่อมต่อกับ ThunderPhone โดยใช้เอเจนต์ที่บันทึกไว้หรือการกำหนดค่าเซสชันแบบอินไลน์
ThunderPhone รองรับชุดย่อยที่มุ่งเน้นของโมเดลเหตุการณ์ OpenAI Realtime ไคลเอนต์ฝั่งเซิร์ฟเวอร์ที่มีอยู่สามารถคงโฟลว์เหตุการณ์ WebSocket เสียง เซสชัน และ การตอบกลับไว้ได้ ขณะใช้งานเอเจนต์เสียง ThunderPhone
ก่อนเชื่อมต่อ
คุณต้องมีคีย์ API ลับขององค์กร ThunderPhone และรันไทม์ของเซิร์ฟเวอร์ที่ สามารถเปิด WebSocket ได้ ห้ามเชื่อมต่อจากโค้ดเบราว์เซอร์หรือเปิดเผยคีย์ให้ เบราว์เซอร์ หากต้องการใช้เอเจนต์ที่บันทึกไว้ ให้ปรับใช้ก่อนแล้วคัดลอก ID เอเจนต์แบบตัวเลข
เชื่อมต่อไปยัง:
wss://api.thunderphone.com/v1/realtimeตรวจสอบสิทธิ์การอัปเกรด WebSocket จากเซิร์ฟเวอร์ของคุณ:
Authorization: Bearer sk_live_YOUR_API_KEYมีการตรวจสอบสิทธิ์ผ่านสตริงคำค้นหาสำหรับไคลเอนต์ที่ไม่สามารถตั้งค่าส่วนหัว ของการจับมือได้ แต่ URL รั่วไหลไปยังบันทึกได้ง่ายกว่า
เลือกผู้ที่เป็นเจ้าของการกำหนดค่า
| โหมด | เลือกด้วย | แหล่งการกำหนดค่า |
|---|---|---|
| เอเจนต์ที่บันทึกไว้ | session.prompt.id ใน session.update แรก หรือ ?agent_id=12 | พรอมป์ต์ เสียง ผลิตภัณฑ์ ภาษา ความรู้ และเครื่องมือที่รันบนเซิร์ฟเวอร์ที่เข้ากันได้ซึ่งปรับใช้แล้ว รวมถึงคำสั่งและตัวแปรของเซสชันนี้ |
| อินไลน์ | ไม่มี | 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 หมายความว่าเซสชันพร้อมใช้งานแล้ว หลังจากนั้นจะไม่สามารถเปลี่ยนคำสั่ง เสียง ผลิตภัณฑ์ เครื่องมือ และรูปแบบเสียงได้ หากต้องการคงคำสั่งไว้และเปลี่ยนเฉพาะค่าที่มีชื่อ ให้เขียนตัวยึดตำแหน่ง {{name}} ลงในคำสั่ง แล้วส่งค่าใน session.config.variables
เซสชันอินไลน์ไม่มีคำทักทายอัตโนมัติหรือการทักตรวจสอบความเงียบด้วยเสียง หากต้องการ
ให้เอเจนต์พูดก่อน ให้เพิ่มข้อความระบบหรือข้อความผู้ใช้ แล้วส่ง
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 หนึ่งรายการแทนหนึ่งสาย การระบุ ID เอเจนต์ไม่ถูกต้องหรือการกำหนดค่า
อินไลน์ถูกปฏิเสธจะสร้างเหตุการณ์ error รอ session.updated ก่อนถือว่า
เซสชันพร้อมใช้งาน ระบุรูปแบบและอัตราการสุ่มตัวอย่างของอินพุตและเอาต์พุตจริง:
อัตรา PCM ไม่ตรงกันจะเล่นเสียงเร็วหรือช้าเกินไป แทนที่จะสร้างข้อผิดพลาด
การตรวจสอบความถูกต้อง
หลังจากเริ่มเซสชันแล้ว ให้ปิดซ็อกเก็ตอย่างถูกต้องเมื่อแอปพลิเคชันของคุณทำงานเสร็จสิ้น เซสชันแบบอินไลน์สามารถใช้ฟังก์ชันที่ไคลเอ็นต์ดำเนินการได้ เซสชันเอเจนต์ที่บันทึกไว้ใช้เครื่องมือที่เข้ากันได้ซึ่ง ThunderPhone เรียกใช้ และมี transfer_call (รวมถึง send_keypad_input สำหรับเซสชันขาออก) ได้เฉพาะเมื่อใช้ call_events เท่านั้น โดยไคลเอ็นต์ของคุณจะดำเนินการอีเวนต์ call.* เหล่านั้น
ทดสอบการผสานรวม
เริ่มต้นด้วย ไคลเอนต์ Python WAV ขั้นต่ำ และไฟล์ WAV PCM16 โมโน ที่มีอัตราตามที่ระบุ ตรวจสอบว่า:
- เซิร์ฟเวอร์ยอมรับการกำหนดค่าและส่ง
session.updated - อินพุตสร้างเหตุการณ์ข้อความถอดเสียงและเสียงการตอบกลับด้วยความเร็วที่คาดไว้
- การขัดจังหวะและการยกเลิกการตอบกลับหยุดเสียงเอาต์พุตที่เหลือ
- ผลลัพธ์ของฟังก์ชันอินไลน์หรือผลลัพธ์เครื่องมือของเอเจนต์ที่บันทึกไว้ส่งกลับไปยังโมเดล
- อินพุตที่ไม่ถูกต้องสร้างเหตุการณ์
errorที่ไคลเอนต์ของคุณจัดการ - ไคลเอนต์ของคุณปิดซ็อกเก็ตและสายปรากฏในประวัติ สาย
ข้อมูลอ้างอิง Realtime WebSocket แสดงรายการเหตุการณ์ รูปแบบเสียง ฟิลด์เซสชัน และตัวอย่างฉบับสมบูรณ์ที่ยอมรับ
ค่าใช้จ่าย
การโทร Realtime มีราคาเช่นเดียวกับการโทรอื่น: ต้นทุนของส่วนประกอบตามราคาปลีกของผู้ให้บริการของเรา บวกค่าบริการโครงสร้างพื้นฐานและมาร์จิน 17–25% การเปิดใช้เดลต้าของการถอดเสียงแบบสดจะเพิ่มงานถอดเสียงตลอดทั้งเซสชัน โปรดดู การถอดเสียงแบบสด และ ราคา
POST /v1/realtime/sessions เป็นเส้นทาง LiveKit ที่มีการจัดการแยกต่างหาก
ซึ่งสร้างห้องและโทเค็นผู้เข้าร่วมแบบกำหนดขอบเขต โดยไม่จำเป็นสำหรับการเชื่อมต่อ
WebSocket โดยตรง
สำหรับการผสานรวมกับเฟรมเวิร์ก ดูใช้ ThunderPhone จาก Pipecat และใช้ ThunderPhone จาก LiveKit Agents