1
This commit is contained in:
771
keyBoard/Class/AiTalk/websocket-api.md
Normal file
771
keyBoard/Class/AiTalk/websocket-api.md
Normal file
@@ -0,0 +1,771 @@
|
||||
# 实时语音对话 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 | 初始版本 |
|
||||
|
||||
Reference in New Issue
Block a user