# 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 整合架構

{% @mermaid/diagram content="flowchart TB
subgraph Client\["瀏覽器/客戶端"]
Web\["Web UI"]
WebRTC\["WebRTC SDK"]
end

```
subgraph MaiAgent["MaiAgent 平台"]
    Django["Django Backend"]
    SIO_Main["Socket.IO Server<br/>(主命名空間)"]
    SIO_Voice["Socket.IO Server<br/>(Voice Agent 專用)"]
    VoiceService["Voice Agent Service"]
end

subgraph LiveKit["LiveKit 基礎設施"]
    SFU["LiveKit SFU<br/>(Selective Forwarding Unit)"]
    Room["虛擬房間"]
end

subgraph AI["AI 處理層"]
    STT["語音辨識<br/>(Speech-to-Text)"]
    LLM["語言模型"]
    TTS["語音合成<br/>(Text-to-Speech)"]
end

Web <--> WebRTC
WebRTC <-. "WebRTC 媒體流" .-> SFU
Web <-. "Socket.IO 控制" .-> SIO_Voice
SIO_Voice <--> VoiceService
VoiceService <--> SFU
VoiceService --> STT
STT --> LLM
LLM --> TTS
TTS -.-> SFU

Django --> SIO_Main
Django --> SIO_Voice" %}
```

### 2.1 核心元件說明

* **LiveKit SFU (Selective Forwarding Unit)**: 負責音訊/視訊資料的路由和轉發,支援多人同時通話
* **Socket.IO Server**: 處理控制訊號,如通話開始/結束、狀態同步等
* **Voice Agent Service**: 協調語音辨識、LLM 推論、語音合成的完整流程
* **WebRTC**: 在瀏覽器端建立點對點的媒體連線,傳輸音訊資料

### 2.2 連線建立流程

{% @mermaid/diagram content="sequenceDiagram
participant User as 使用者
participant Browser as 瀏覽器
participant Django as Backend
participant SocketIO as Voice Agent Socket
participant LiveKit as LiveKit SFU

```
User->>Browser: 點擊「開始通話」
Browser->>Django: 請求建立語音會話
Django->>LiveKit: 建立虛擬房間
LiveKit-->>Django: 返回房間資訊和 Token
Django-->>Browser: 返回連線參數

Browser->>SocketIO: 建立 Socket.IO 連線
SocketIO-->>Browser: 連線確認

Browser->>LiveKit: WebRTC 連線請求
LiveKit-->>Browser: ICE Candidates 交換
Browser->>LiveKit: 建立 DTLS/SRTP 加密通道
LiveKit-->>Browser: 加密通道建立完成

Note over Browser,LiveKit: 音訊串流開始傳輸

Browser->>SocketIO: 傳送 PCM 音訊資料
SocketIO->>LiveKit: 轉發音訊至 AI 處理" %}
```

***

## 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 事件處理

{% @mermaid/diagram content="sequenceDiagram
participant Browser as 瀏覽器
participant SocketIO as Socket.IO Server
participant Queue as 音訊佇列
participant STT as 語音辨識

```
loop 持續傳輸
    Browser->>SocketIO: 傳送音訊資料
    Note over SocketIO: 優先處理，略過一般訊息佇列
    SocketIO->>Queue: 加入語音處理佇列
end

Queue->>STT: 批次處理音訊片段
STT-->>Queue: 返回識別文字
Queue->>SocketIO: 回傳辨識結果
SocketIO->>Browser: 顯示即時字幕" %}
```

**音訊優先處理機制**:

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

* **不進入一般訊息佇列**: 避免被其他訊息阻塞
* **優先處理**: 音訊資料可以插隊,減少延遲
* **獨立路由**: 直接轉發到語音處理模組

### 4.3 連線斷開處理

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

{% @mermaid/diagram content="flowchart TD
A\["偵測到連線斷開"] --> B{"斷線原因?"}
B -- "使用者主動掛斷" --> C\["正常清理資源"]
B -- "網路問題" --> D\["嘗試重連"]
B -- "伺服器錯誤" --> E\["記錄錯誤日誌"]

```
C --> F["釋放 LiveKit 房間"]
D --> G{"重連成功?"}
E --> F

G -- "是" --> H["恢復通話"]
G -- "否" --> I["通知使用者<br/>並清理資源"]

F --> J["關閉 Socket.IO 連線"]
H --> K["繼續通話"]
I --> J
J --> L["完成"]" %}
```

**斷線處理機制**:

* **心跳檢測**: 定期發送 ping/pong 訊息檢查連線狀態
* **自動重連**: 短暫斷線時自動嘗試重連,無需使用者介入
* **資源清理**: 確保 LiveKit 房間和伺服器資源被正確釋放
* **狀態同步**: 斷線後重連時恢復對話上下文

***

## 5. 詳細日誌記錄

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

### 5.1 日誌類型

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

### 5.2 日誌範例

```log
[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. 相關文檔

* [語音客服](https://docs.maiagent.ai/application/voicecs) - 使用者指南
* [IVR 客服意圖辨識](https://docs.maiagent.ai/application/voicecs/ivr-ke-fu-yi-tu-bian-shi)
* [語音通話摘要](https://docs.maiagent.ai/application/voicecs/yu-yin-tong-hua-zhai-yao)

### 參考連結

* [LiveKit Documentation](https://docs.livekit.io/)
* [WebRTC Specification](https://www.w3.org/TR/webrtc/)
* [Socket.IO Documentation](https://socket.io/docs/v4/)
* [Opus Codec](https://opus-codec.org/)