# 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
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
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
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
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/)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/tech/advanced-genai-tech/livekit-voice-agent.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.