# 实时语音对话 WebSocket API 文档

> Version: 2.0.0 (Flux)
> Last Updated: 2026-01-21
> Author: Backend Team

---

## 概述

本文档描述实时语音对话 WebSocket API，用于 iOS 客户端与后端进行实时语音交互。

**v2.0 更新**: 升级为 Deepgram Flux 模型，支持智能轮次检测和 EagerEndOfTurn 提前响应。

### 核心特性
- **智能轮次检测**: Flux 模型语义理解，自动判断用户说完（非简单静默检测）
- **EagerEndOfTurn**: 提前启动 LLM 响应，进一步降低延迟
- **实时语音识别**: 边说边识别，实时显示转写文本
- **流式响应**: AI 响应边生成边返回，无需等待完整响应
- **流式音频**: TTS 音频边合成边播放，极低延迟
- **Barge-in 支持**: 用户可以打断 AI 说话

### 性能指标
| 指标 | 目标值 | 说明 |
|------|--------|------|
| 端点检测延迟 | ~260ms | Flux 智能检测 |
| TTFA (首音频延迟) | < 300ms | EagerEndOfTurn 优化 |
| 端到端延迟 | < 1.5秒 | 完整对话周期 |
| 实时转写延迟 | < 100ms | 中间结果 |

---

## 连接信息

### WebSocket 端点

```
生产环境: wss://api.yourdomain.com/api/ws/chat?token={sa_token}
开发环境: ws://localhost:7529/api/ws/chat?token={sa_token}
```

### 认证方式

通过 URL Query 参数传递 Sa-Token：

```
ws://host:port/api/ws/chat?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
```

| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| token | String | ✅ | Sa-Token 登录令牌，通过 Apple Sign-In 获取 |

### 认证失败

如果 token 无效或过期，WebSocket 连接将被拒绝（HTTP 403）。

---

## 消息格式

### 通用规则

1. **文本消息**: JSON 格式，用于控制指令和状态通知
2. **二进制消息**: 原始字节，用于音频数据传输
3. **编码**: UTF-8

---

## 客户端 → 服务端消息

### 1. 开始会话 (session_start)

**发送时机**: 建立 WebSocket 连接后，准备开始录音前

```json
{
  "type": "session_start",
  "config": {
    "language": "en",
    "voice_id": "a5zfmqTslZJBP0jutmVY"
  }
}
```

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| type | String | ✅ | 固定值 `session_start` |
| config | Object | ❌ | 会话配置（可选） |
| config.language | String | ❌ | 语音识别语言，默认 `en` |
| config.voice_id | String | ❌ | TTS 声音 ID，默认使用服务端配置 |

**响应**: 服务端返回 `session_started` 消息

---

### 2. 音频数据 (Binary)

**发送时机**: 用户正在录音时，持续发送音频数据

**格式**: Binary WebSocket Frame，直接发送原始音频字节

**音频规格要求**:

| 参数 | 值 | 说明 |
|------|------|------|
| 编码格式 | PCM (Linear16) | 未压缩的脉冲编码调制 |
| 采样率 | 16000 Hz | 16kHz |
| 位深度 | 16-bit | 有符号整数 |
| 声道数 | 1 (Mono) | 单声道 |
| 字节序 | Little-Endian | 小端序 |

**iOS 代码示例**:

```swift
// AVAudioEngine 配置
let format = AVAudioFormat(
    commonFormat: .pcmFormatInt16,
    sampleRate: 16000,
    channels: 1,
    interleaved: true
)!

// 发送音频数据
audioEngine.inputNode.installTap(
    onBus: 0,
    bufferSize: 1024,
    format: format
) { buffer, time in
    let audioData = buffer.int16ChannelData![0]
    let byteCount = Int(buffer.frameLength) * 2  // 16-bit = 2 bytes
    let data = Data(bytes: audioData, count: byteCount)

    webSocket.write(data: data)
}
```

**发送频率**: 建议每 20-100ms 发送一次，每次 320-1600 字节

---

### 3. 结束录音 (audio_end)

**发送时机**: 用户停止录音（松开录音按钮）

```json
{
  "type": "audio_end"
}
```

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| type | String | ✅ | 固定值 `audio_end` |

**说明**: 发送此消息后，服务端将完成语音识别并开始生成 AI 响应

---

### 4. 取消会话 (cancel)

**发送时机**: 用户主动取消对话（如点击取消按钮）

```json
{
  "type": "cancel"
}
```

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| type | String | ✅ | 固定值 `cancel` |

**说明**: 服务端将停止所有处理，不再返回任何消息

---

## 服务端 → 客户端消息

### 1. 会话已启动 (session_started)

**接收时机**: 发送 `session_start` 后

```json
{
  "type": "session_started",
  "session_id": "abc123-def456-ghi789"
}
```

| 字段 | 类型 | 描述 |
|------|------|------|
| type | String | 固定值 `session_started` |
| session_id | String | 服务端分配的会话 ID |

**客户端处理**: 收到此消息后，可以开始发送音频数据

---

### 2. 轮次开始 (turn_start) 🆕

**接收时机**: 用户开始说话时（Flux 检测到语音活动）

```json
{
  "type": "turn_start",
  "turn_index": 0
}
```

| 字段 | 类型 | 描述 |
|------|------|------|
| type | String | 固定值 `turn_start` |
| turn_index | Integer | 当前轮次索引（从 0 开始） |

**客户端处理**:
- 可显示"正在听..."状态
- 准备接收转写结果

---

### 3. 中间转写结果 (transcript_interim)

**接收时机**: 用户说话过程中，实时返回

```json
{
  "type": "transcript_interim",
  "text": "Hello how are",
  "is_final": false
}
```

| 字段 | 类型 | 描述 |
|------|------|------|
| type | String | 固定值 `transcript_interim` |
| text | String | 当前识别到的文本（可能会变化） |
| is_final | Boolean | 固定为 `false` |

**客户端处理**:
- 实时更新 UI 显示转写文本
- 此文本可能会被后续消息覆盖
- 可用于显示"正在识别..."效果

---

### 3. 最终转写结果 (transcript_final)

**接收时机**: 一句话识别完成时

```json
{
  "type": "transcript_final",
  "text": "Hello, how are you?"
}
```

| 字段 | 类型 | 描述 |
|------|------|------|
| type | String | 固定值 `transcript_final` |
| text | String | 最终确定的转写文本 |

**客户端处理**:
- 用此文本替换之前的中间结果
- 此文本不会再变化

---

### 6. 提前端点检测 (eager_eot) 🆕

**接收时机**: Flux 检测到用户可能说完时（置信度达到阈值）

```json
{
  "type": "eager_eot",
  "transcript": "Hello, how are you",
  "confidence": 0.65
}
```

| 字段 | 类型 | 描述 |
|------|------|------|
| type | String | 固定值 `eager_eot` |
| transcript | String | 当前转写文本 |
| confidence | Double | 端点置信度 (0.0-1.0) |

**客户端处理**:
- 这是一个**预测性事件**，表示用户可能说完了
- 服务端已开始提前准备 LLM 响应
- 可显示"准备响应..."状态
- **注意**: 用户可能继续说话，此时会收到 `turn_resumed`

---

### 7. 轮次恢复 (turn_resumed) 🆕

**接收时机**: 收到 `eager_eot` 后，用户继续说话

```json
{
  "type": "turn_resumed"
}
```

| 字段 | 类型 | 描述 |
|------|------|------|
| type | String | 固定值 `turn_resumed` |

**客户端处理**:
- 用户继续说话，之前的 `eager_eot` 是误判
- 服务端已取消正在准备的草稿响应
- 恢复"正在听..."状态
- 继续接收 `transcript_interim` 更新

---

### 8. LLM 开始生成 (llm_start)

**接收时机**: 语音识别完成，AI 开始生成响应

```json
{
  "type": "llm_start"
}
```

| 字段 | 类型 | 描述 |
|------|------|------|
| type | String | 固定值 `llm_start` |

**客户端处理**:
- 可显示"AI 正在思考..."状态
- 准备接收 AI 响应文本和音频

---

### 5. LLM Token (llm_token)

**接收时机**: AI 生成过程中，逐 token 返回

```json
{
  "type": "llm_token",
  "token": "Hi"
}
```

| 字段 | 类型 | 描述 |
|------|------|------|
| type | String | 固定值 `llm_token` |
| token | String | AI 输出的单个 token（词或字符片段） |

**客户端处理**:
- 可选择实现打字机效果
- 逐个 token 追加显示 AI 响应文本
- 如不需要打字效果，可忽略此消息

---

### 6. 音频数据 (Binary)

**接收时机**: TTS 合成过程中，流式返回音频

**格式**: Binary WebSocket Frame，MP3 音频块

**音频规格**:

| 参数 | 值 |
|------|------|
| 格式 | MP3 |
| 采样率 | 44100 Hz |
| 比特率 | 64 kbps |
| 声道 | 单声道 |

**客户端处理**:

```swift
// 使用 AVAudioEngine 或 AudioQueue 播放流式音频
webSocket.onEvent = { event in
    switch event {
    case .binary(let data):
        // 方案1: 追加到缓冲区，使用 AVAudioPlayerNode
        audioBuffer.append(data)
        playBufferedAudio()

        // 方案2: 使用 AVAudioEngine + AVAudioCompressedBuffer
        // 方案3: 累积后使用 AVAudioPlayer
    }
}
```

**重要提示**:
- 音频是分块返回的，需要正确拼接或流式播放
- 每个二进制消息是 MP3 数据的一部分
- 收到 `complete` 消息后，音频传输完成

---

### 7. 处理完成 (complete)

**接收时机**: AI 响应生成完成，所有音频已发送

```json
{
  "type": "complete",
  "transcript": "Hello, how are you?",
  "ai_response": "Hi! I'm doing great, thanks for asking!"
}
```

| 字段 | 类型 | 描述 |
|------|------|------|
| type | String | 固定值 `complete` |
| transcript | String | 完整的用户语音转写文本 |
| ai_response | String | 完整的 AI 响应文本 |

**客户端处理**:
- 更新 UI 显示完整对话
- 可开始下一轮对话
- 建议保存对话历史

---

### 8. 错误 (error)

**接收时机**: 处理过程中发生错误

```json
{
  "type": "error",
  "code": "DEEPGRAM_ERROR",
  "message": "Speech recognition failed"
}
```

| 字段 | 类型 | 描述 |
|------|------|------|
| type | String | 固定值 `error` |
| code | String | 错误代码 |
| message | String | 错误描述 |

**错误代码列表**:

| 错误代码 | 描述 | 建议处理 |
|----------|------|----------|
| PARSE_ERROR | 消息解析失败 | 检查消息格式 |
| DEEPGRAM_ERROR | 语音识别服务错误 | 重试或提示用户 |
| DEEPGRAM_INIT_ERROR | 语音识别初始化失败 | 重新开始会话 |
| LLM_ERROR | AI 生成错误 | 重试或提示用户 |
| PIPELINE_ERROR | 处理流程错误 | 重新开始会话 |
| EMPTY_TRANSCRIPT | 未检测到语音 | 提示用户重新说话 |

**客户端处理**:
- 显示友好的错误提示
- 根据错误类型决定是否重试

---

## 完整交互流程

### 时序图

```
iOS Client                          Server
    |                                   |
    |------ WebSocket Connect --------->|
    |        ?token=xxx                 |
    |                                   |
    |<-------- Connected ---------------|
    |                                   |
    |------ session_start ------------->|
    |                                   |
    |<----- session_started ------------|
    |       {session_id: "abc"}         |
    |                                   |
    |======= 用户开始说话 ===============|
    |                                   |
    |------ Binary (audio) ------------>|
    |------ Binary (audio) ------------>|
    |<----- transcript_interim ---------|
    |       {text: "Hello"}             |
    |------ Binary (audio) ------------>|
    |<----- transcript_interim ---------|
    |       {text: "Hello how"}         |
    |------ Binary (audio) ------------>|
    |<----- transcript_final -----------|
    |       {text: "Hello, how are you?"}|
    |                                   |
    |======= 用户停止说话 ===============|
    |                                   |
    |------ audio_end ----------------->|
    |                                   |
    |<----- llm_start ------------------|
    |                                   |
    |<----- llm_token ------------------|
    |       {token: "Hi"}               |
    |<----- llm_token ------------------|
    |       {token: "!"}                |
    |<----- Binary (mp3) ---------------|
    |<----- Binary (mp3) ---------------|
    |<----- llm_token ------------------|
    |       {token: " I'm"}             |
    |<----- Binary (mp3) ---------------|
    |       ...                         |
    |<----- complete -------------------|
    |       {transcript, ai_response}   |
    |                                   |
    |======= 可以开始下一轮 =============|
    |                                   |
```

---

## iOS 代码示例

### 完整 Swift 实现

```swift
import Foundation
import Starscream  // WebSocket 库

class VoiceChatManager: WebSocketDelegate {

    private var socket: WebSocket?
    private var audioBuffer = Data()

    // MARK: - 回调
    var onSessionStarted: ((String) -> Void)?
    var onTranscriptInterim: ((String) -> Void)?
    var onTranscriptFinal: ((String) -> Void)?
    var onLLMStart: (() -> Void)?
    var onLLMToken: ((String) -> Void)?
    var onAudioChunk: ((Data) -> Void)?
    var onComplete: ((String, String) -> Void)?
    var onError: ((String, String) -> Void)?

    // MARK: - 连接
    func connect(token: String) {
        let urlString = "wss://api.yourdomain.com/api/ws/chat?token=\(token)"
        guard let url = URL(string: urlString) else { return }

        var request = URLRequest(url: url)
        request.timeoutInterval = 30

        socket = WebSocket(request: request)
        socket?.delegate = self
        socket?.connect()
    }

    func disconnect() {
        socket?.disconnect()
        socket = nil
    }

    // MARK: - 发送消息
    func startSession(language: String = "en", voiceId: String? = nil) {
        var config: [String: Any] = ["language": language]
        if let voiceId = voiceId {
            config["voice_id"] = voiceId
        }

        let message: [String: Any] = [
            "type": "session_start",
            "config": config
        ]

        sendJSON(message)
    }

    func sendAudio(_ data: Data) {
        socket?.write(data: data)
    }

    func endAudio() {
        sendJSON(["type": "audio_end"])
    }

    func cancel() {
        sendJSON(["type": "cancel"])
    }

    private func sendJSON(_ dict: [String: Any]) {
        guard let data = try? JSONSerialization.data(withJSONObject: dict),
              let string = String(data: data, encoding: .utf8) else { return }
        socket?.write(string: string)
    }

    // MARK: - WebSocketDelegate
    func didReceive(event: WebSocketEvent, client: WebSocketClient) {
        switch event {
        case .connected(_):
            print("WebSocket connected")

        case .disconnected(let reason, let code):
            print("WebSocket disconnected: \(reason) (\(code))")

        case .text(let text):
            handleTextMessage(text)

        case .binary(let data):
            // 收到 MP3 音频数据
            onAudioChunk?(data)

        case .error(let error):
            print("WebSocket error: \(error?.localizedDescription ?? "unknown")")

        default:
            break
        }
    }

    private func handleTextMessage(_ text: String) {
        guard let data = text.data(using: .utf8),
              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
              let type = json["type"] as? String else { return }

        switch type {
        case "session_started":
            if let sessionId = json["session_id"] as? String {
                onSessionStarted?(sessionId)
            }

        case "transcript_interim":
            if let text = json["text"] as? String {
                onTranscriptInterim?(text)
            }

        case "transcript_final":
            if let text = json["text"] as? String {
                onTranscriptFinal?(text)
            }

        case "llm_start":
            onLLMStart?()

        case "llm_token":
            if let token = json["token"] as? String {
                onLLMToken?(token)
            }

        case "complete":
            if let transcript = json["transcript"] as? String,
               let aiResponse = json["ai_response"] as? String {
                onComplete?(transcript, aiResponse)
            }

        case "error":
            if let code = json["code"] as? String,
               let message = json["message"] as? String {
                onError?(code, message)
            }

        default:
            print("Unknown message type: \(type)")
        }
    }
}
```

### 使用示例

```swift
class VoiceChatViewController: UIViewController {

    let chatManager = VoiceChatManager()
    let audioRecorder = AudioRecorder()  // 自定义录音类
    let audioPlayer = StreamingAudioPlayer()  // 自定义流式播放类

    override func viewDidLoad() {
        super.viewDidLoad()
        setupCallbacks()
    }

    func setupCallbacks() {
        chatManager.onSessionStarted = { [weak self] sessionId in
            print("Session started: \(sessionId)")
            // 开始录音
            self?.audioRecorder.start { audioData in
                self?.chatManager.sendAudio(audioData)
            }
        }

        chatManager.onTranscriptInterim = { [weak self] text in
            self?.transcriptLabel.text = text + "..."
        }

        chatManager.onTranscriptFinal = { [weak self] text in
            self?.transcriptLabel.text = text
        }

        chatManager.onLLMStart = { [weak self] in
            self?.statusLabel.text = "AI is thinking..."
        }

        chatManager.onLLMToken = { [weak self] token in
            self?.aiResponseLabel.text = (self?.aiResponseLabel.text ?? "") + token
        }

        chatManager.onAudioChunk = { [weak self] data in
            self?.audioPlayer.appendData(data)
        }

        chatManager.onComplete = { [weak self] transcript, aiResponse in
            self?.statusLabel.text = "Complete"
            self?.addToHistory(user: transcript, ai: aiResponse)
        }

        chatManager.onError = { [weak self] code, message in
            self?.showError(message)
        }
    }

    @IBAction func startTapped(_ sender: UIButton) {
        // 连接并开始会话
        chatManager.connect(token: AuthManager.shared.saToken)
        chatManager.onSessionStarted = { [weak self] _ in
            self?.chatManager.startSession()
        }
    }

    @IBAction func stopTapped(_ sender: UIButton) {
        audioRecorder.stop()
        chatManager.endAudio()
    }

    @IBAction func cancelTapped(_ sender: UIButton) {
        audioRecorder.stop()
        audioPlayer.stop()
        chatManager.cancel()
    }
}
```

---

## 注意事项

### 1. 音频录制
- 必须使用 PCM 16-bit, 16kHz, Mono 格式
- 建议每 20-100ms 发送一次音频数据
- 录音权限需要在 Info.plist 中声明

### 2. 音频播放
- 返回的是 MP3 格式音频块
- 需要实现流式播放或缓冲播放
- 建议使用 AVAudioEngine 实现低延迟播放

### 3. 网络处理
- 实现自动重连机制
- 处理网络切换场景
- 设置合理的超时时间

### 4. 用户体验
- 显示实时转写文本
- 显示 AI 响应状态
- 提供取消按钮
- 处理录音权限被拒绝的情况

### 5. 调试建议
- 使用 `wss://` 确保生产环境安全
- 本地开发可使用 `ws://`
- 检查 Sa-Token 是否过期

---

## 版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| 1.0.0 | 2026-01-21 | 初始版本 |