# 语音交互

语音交互把麦克风输入接入当前设备会话，识别文本会按设备规格完成查询或控制；语音通道只处理音频、识别文本和播报，真实设备上线、命令执行和状态上报仍通过 MQTT 或设备 SDK 完成。

## 使用前准备

启用语音前，需要先完成以下准备：

- 已创建设备智能体，并为目标设备定义好设备规格。语音请求最终会落到这些命令、遥测字段和事件上。
- 目标设备已通过 MQTT 或设备 SDK 接入，并能接收命令、返回结果和上报状态。
- 已准备可用的语音识别和语音合成服务商凭证。
- 控制台使用需要浏览器麦克风权限；SDK/设备端接入需要设备端能采集麦克风音频并播放合成音频。

## 配置语音服务

在 **配置** 中启用语音能力，并选择语音服务商。当前支持：

| 服务商 | 能力 |
| --- | --- |
| 火山引擎 | 语音识别和语音合成 |
| 阿里云百炼 DashScope | 语音识别和语音合成 |
| AWS | Transcribe 语音识别和 Polly 语音合成 |
| ElevenLabs | 语音识别和语音合成 |

常用配置包括：

- 是否启用语音。
- 语音 WebSocket 的监听地址和端口，默认端口为 `3001`。
- 浏览器访问的语音 WebSocket 地址。
- 语音区域、识别采样率、服务商凭证、识别模型、合成模型和音色。
- 如需远程浏览器访问或生产部署，可配置语音 TLS。

保存后，页面会展示客户端可访问的语音 WebSocket 地址，默认是 `ws://127.0.0.1:3001/ws/voice`。完整配置项见 [配置](../operate-reference/configuration.md)。

![语音服务配置](../images/docs/usage/voice/zh/01-voice-settings.png)

## 控制台使用和 SDK 接入

语音交互有两条使用路径。通常先用控制台验证识别质量和控制链路，再接入 SDK 到真实设备。

| 路径 | 适用场景 | 需要完成 |
| --- | --- | --- |
| 控制台使用 | 开发调试、演示、验证设备规格是否适合语音控制 | 启用语音配置，选中设备后用浏览器麦克风发起请求 |
| SDK/设备端接入 | 设备本身带麦克风、扬声器或系统音频接口 | 设备端连接 `/ws/voice`，发送音频帧，播放返回的 TTS 音频 |

控制台使用适合快速确认语音识别、设备上下文和命令调用。SDK/设备端接入负责真实设备的音频采集与播放。两种方式都会进入同一个设备智能体会话，并使用同一份设备规格。

## 控制台使用

进入设备智能体工作区并选中设备，打开语音入口。后续语音请求都会绑定到这台设备。

控制台使用时可以：

- 发起一条和设备规格相关的语音指令，例如查询状态、调整参数或触发某个动作。
- 查看识别文本是否准确，并确认设备智能体是否调用了预期命令或读取了预期状态。
- 听取语音回复，必要时中断当前朗读。
- 将识别出的文本转回输入框继续编辑，用于排查识别错误或提示词问题。

如果同时开启摄像头，语音请求结束时可以携带当前画面。设备智能体会在用户询问可见内容时使用视觉能力，例如识别状态灯、读取屏幕文字或判断画面中的物体。

![语音使用入口](../images/docs/usage/voice/zh/02-voice-chat.png)

## SDK/设备端接入

生成设备 SDK 后，工程会包含语音连接信息，例如 `VOICE_CHAT_HOST`；C SDK 还包含可运行的语音聊天示例。设备端接入步骤如下：

1. 先启动设备端 MQTT 或 SDK 连接，确认设备在控制台在线。
2. 读取 SDK 工程中的语音配置，连接 Agent Gateway 的 `/ws/voice`。
3. 建立连接后发送 `hello`，带上设备 ID、会话 ID、服务商和音频参数。
4. 用户开始说话时发送 `listen`，随后持续发送 16 kHz、单声道、Int16LE PCM 音频帧。
5. 用户结束说话时发送 `stop`。如需结合摄像头画面，可在结束时带上视觉帧引用。
6. 监听识别文本、设备智能体回复和 TTS 音频帧，把音频帧接到设备扬声器或系统音频播放。

不使用生成 SDK 时，可以直接按 WebSocket 协议接入。协议消息、Header 和 `hello` 示例见 [API 参考](../operate-reference/api.md#websocket)。

语音请求触发设备控制时，真实设备仍然通过 MQTT 或 SDK 收到命令并返回响应。设备端不需要维护额外的“语音命令”分支，以免和设备规格中的命令定义不一致。

如需生成带麦克风、扬声器或系统音频接口适配逻辑的设备端代码，可以在 [SDK 接入](../device-access/sdk-generation.md) 中使用智能体适配和增强 SDK。

## 验证结果

完成控制台配置或 SDK/设备端接入后，至少验证这些结果：

- 语音 WebSocket 可以连接，`hello` 能返回会话信息。
- 麦克风音频能被识别成文本，且识别文本进入当前设备的对话上下文。
- 查询类问题能读到真实设备状态，控制类指令能触发设备规格中定义的命令。
- 设备端能收到命令、返回执行结果，并在控制台或日志中看到对应记录。
- TTS 音频能在浏览器或真实设备上播放，`abort` 可以中断当前朗读。
- 远程访问或生产部署时，客户端使用的是可访问的 WebSocket 地址和 TLS 配置。

## 注意事项

语音功能需要启用通道、可访问的 WebSocket 地址、麦克风权限，以及可用的语音服务商配置。它更适合手动发起的短语音交互；长报告、复杂表格、代码、唤醒词和持续后台监听场景更适合放在语音流程之外处理。