LiveKit 語音代理整合架構

本文件說明 MaiAgent 平台如何整合 LiveKit 實現即時語音通話功能,包括 WebRTC 連線管理、Socket.IO 命名空間隔離、以及音訊資料串流處理。

1. 什麼是 LiveKit？

LiveKit 是一個開源的即時通訊基礎設施,提供低延遲、高品質的音訊和視訊通訊能力。MaiAgent 使用 LiveKit 實現 AI 語音代理功能,讓使用者可以透過語音與 AI 助理進行自然對話。

1.1 核心技術優勢

技術面向	傳統電話系統	LiveKit + MaiAgent
延遲	200-500ms	< 100ms,接近真人對話體驗
音質	受限於電話網路編碼	支援 Opus 高音質編碼,可調整位元率
擴展性	需要專用語音閘道器	基於 WebRTC,可輕鬆水平擴展
成本	需支付電話系統租用費	基於網際網路,成本更低
整合性	與數位系統整合困難	原生整合 Web 應用,可嵌入任何頁面

1.2 常見應用場景

• AI 語音客服: 客戶透過網頁或 App 直接與 AI 助理語音通話

• 語音助理: 企業內部使用語音指令操作系統,如查詢資料、建立工單

• 遠端協助: AI 助理透過語音引導使用者操作,如設備安裝、故障排除

• 多語言支援: 結合語音辨識和翻譯,實現跨語言即時溝通

---

2. MaiAgent LiveKit 整合架構

2.1 核心元件說明

• LiveKit SFU (Selective Forwarding Unit): 負責音訊/視訊資料的路由和轉發,支援多人同時通話

• Socket.IO Server: 處理控制訊號,如通話開始/結束、狀態同步等

• Voice Agent Service: 協調語音辨識、LLM 推論、語音合成的完整流程

• WebRTC: 在瀏覽器端建立點對點的媒體連線,傳輸音訊資料

2.2 連線建立流程

---

3. Socket.IO 命名空間隔離

3.1 為何需要專用命名空間？

MaiAgent 原本的 Socket.IO 主要用於一般聊天訊息的即時推送。語音通話需求有以下特殊性:

• 高頻率資料傳輸: 音訊資料需要以 20-60ms 的間隔持續傳輸

• 低延遲要求: 任何延遲都會明顯影響通話體驗

• 獨立錯誤處理: 語音連線中斷不應影響一般聊天功能

• 不同的 CORS 政策: 語音功能可能需要允許更多來源網域

3.2 命名空間隔離架構

MaiAgent 為 Voice Agent 建立了獨立的 Socket.IO 伺服器，與一般聊天訊息的 Socket.IO 完全分離。Voice Agent 使用專用的命名空間，並配置獨立的 CORS 策略。

隔離帶來的優勢:

1. 效能隔離: 語音資料的高頻傳輸不會影響一般聊天訊息的處理

2. 獨立擴展: 可針對語音流量單獨增加伺服器資源

3. 安全性增強: 不同功能使用不同的 CORS 政策和驗證機制

4. 故障隔離: Voice Agent 的問題不會影響其他功能

3.3 跨來源資源共用 (CORS) 配置

Voice Agent 的 CORS 設定獨立於一般聊天功能，僅允許授權的網域來源進行連線，確保語音通話的安全性。

---

4. 音訊資料串流處理

4.1 音訊資料格式

LiveKit 傳輸的音訊資料使用以下規格:

• 格式: PCM (Pulse-Code Modulation)

• 取樣率: 16kHz 或 48kHz

• 位元深度: 16-bit

• 聲道: 單聲道 (Mono)

• 資料傳輸: Base64 編碼後透過 Socket.IO 傳輸

4.2 audioData 事件處理

音訊優先處理機制:

MaiAgent 針對音訊資料傳輸進行了優化，確保音訊資料:

• 不進入一般訊息佇列: 避免被其他訊息阻塞

• 優先處理: 音訊資料可以插隊,減少延遲

• 獨立路由: 直接轉發到語音處理模組

4.3 連線斷開處理

MaiAgent 實作了優雅的連線斷開機制:

斷線處理機制:

• 心跳檢測: 定期發送 ping/pong 訊息檢查連線狀態

• 自動重連: 短暫斷線時自動嘗試重連,無需使用者介入

• 資源清理: 確保 LiveKit 房間和伺服器資源被正確釋放

• 狀態同步: 斷線後重連時恢復對話上下文

---

5. 詳細日誌記錄

MaiAgent 實作了完善的日誌記錄機制,便於除錯和監控:

5.1 日誌類型

日誌類型	記錄內容	用途
連線日誌	Socket.IO 連線/斷開事件,來源 IP	追蹤使用者會話
音訊日誌	音訊資料傳輸頻率、資料大小	分析通話品質
錯誤日誌	異常堆疊、錯誤訊息、上下文	問題排查
效能日誌	處理延遲、佇列長度、CPU 使用率	效能優化

5.2 日誌範例

[2025-12-23 14:30:15] INFO - Voice Agent Socket.IO Configuration:
  - Namespace: /voice-agent
  - Allowed Origins: ['https://maiagent.ai', ...]
  - Max Connections: 1000
  - Ping Timeout: 60s

[2025-12-23 14:30:45] INFO - Client connected:
  - Socket ID: a1b2c3d4e5f6
  - User ID: user_12345
  - Origin: https://admin.maiagent.ai

[2025-12-23 14:31:02] DEBUG - Audio data received:
  - Size: 3200 bytes
  - Format: PCM 16kHz mono
  - Latency: 45ms

[2025-12-23 14:32:15] WARNING - Connection lost:
  - Socket ID: a1b2c3d4e5f6
  - Reason: Network timeout
  - Duration: 90s
  - Attempting reconnection...

---

6. MaiAgent LiveKit 整合的技術優勢

6.1 效能優勢

• 低延遲通訊: WebRTC 點對點傳輸,延遲可低於 100ms

• 高音質: 支援 Opus 編碼,可動態調整位元率適應網路狀況

• 命名空間隔離: 語音和一般訊息分開處理,避免相互干擾

• 音訊佇列優化: ignore_queue 參數確保音訊資料優先處理

6.2 可靠性優勢

• 自動重連: 網路波動時自動恢復連線

• 資源清理: 連線斷開時確保 LiveKit 房間被正確釋放

• 錯誤隔離: Voice Agent 的問題不影響其他功能

• 詳細日誌: 完整的日誌記錄便於問題追蹤

6.3 擴展性優勢

• 水平擴展: 可輕鬆增加 LiveKit SFU 節點處理更多並行通話

• 分散式架構: Socket.IO 和 LiveKit 可部署在不同伺服器

• 負載均衡: 支援多個 Socket.IO 實例背後使用負載均衡器

6.4 安全性優勢

• Token 驗證: 每個 LiveKit 連線都需要有時效性的 JWT Token

• 端到端加密: WebRTC 使用 DTLS/SRTP 加密傳輸

• CORS 保護: 嚴格控制允許連線的來源網域

• 連線追蹤: 記錄所有連線的來源和使用者資訊

---

7. 相關文檔

• 語音客服 - 使用者指南

• IVR 客服意圖辨識

• 語音通話摘要

參考連結

• LiveKit Documentation

• WebRTC Specification

• Socket.IO Documentation

• Opus Codec