# 语音配置

Device Agent 的语音通道负责语音识别（ASR）和语音合成（TTS）。语音请求会进入当前设备会话；真实设备上线、命令执行和状态上报仍通过 MQTT 或设备 SDK 完成。

## 控制台配置

打开控制台 `http://127.0.0.1:3000`，进入 **设置 → 语音**，配置以下内容：

| 字段 | 说明 |
| --- | --- |
| 启用语音 | 控制 `/ws/voice` 语音通道是否可用。 |
| 语音 WebSocket 地址 | 页面只读展示，默认 `ws://127.0.0.1:3001/ws/voice`。浏览器或设备端需要能访问这个地址。 |
| 语音服务商 | 选择 `volcengine`、`aliyun`、`aws` 或 `elevenlabs`。 |
| 区域 | 支持 `cn`、`us`、`eu`、`global`，会影响可用服务商。 |
| 语音识别 | ASR 模型、语言或资源 ID，字段随服务商不同而变化。 |
| 语音合成 | TTS 模型、音色和采样率，字段随服务商不同而变化。 |
| 服务商密钥 | API Key、Access Key、AWS Key 等服务商凭证。 |

修改服务商、模型、音色和密钥后可以直接保存。启用状态、监听地址、端口或 TLS 变化需要重启服务。

## 语音服务商

| 服务商 | 适用区域 | 主要配置 |
| --- | --- | --- |
| 火山引擎（`volcengine`） | `cn`、`global` | `VOLCENGINE_SPEECH_APP_ID`、`VOLCENGINE_SPEECH_ACCESS_KEY`，以及 ASR/TTS 资源 ID、语言、音色和采样率。 |
| 阿里云 DashScope（`aliyun`） | `cn`、`global` | `ALIYUN_DASHSCOPE_API_KEY` 或 `QWEN_API_KEY`，以及 ASR 模型、TTS 模型、音色和采样率。 |
| AWS（`aws`） | `us`、`eu`、`global` | `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、`AWS_REGION`，以及 Transcribe 语言和 Polly 音色。 |
| ElevenLabs（`elevenlabs`） | `us`、`eu`、`global` | `ELEVENLABS_API_KEY`、API Endpoint、ASR 模型、TTS 模型、音色和采样率。 |

`VOICE_REGION=cn` 使用火山引擎或阿里云；`us` 使用 AWS 或 ElevenLabs；`eu` 要求 AWS `eu-*` 区域或 ElevenLabs EU residency endpoint；`global` 不限制服务商。

## `.env` 配置

首次启动、容器部署或无 UI 环境可以用 `.env` 写入语音配置；后续也可以在控制台 **设置 → 语音** 中切换。

阿里云 DashScope：

```bash
VOICE_ENABLED=true
VOICE_REGION=cn
ALIYUN_DASHSCOPE_API_KEY=sk-...
ALIYUN_ASR_MODEL=paraformer-realtime-v2
ALIYUN_TTS_MODEL=cosyvoice-v3-flash
ALIYUN_TTS_VOICE=longanyang
```

火山引擎：

```bash
VOICE_ENABLED=true
VOICE_REGION=cn
VOLCENGINE_SPEECH_APP_ID=...
VOLCENGINE_SPEECH_ACCESS_KEY=...
VOLCENGINE_TTS_VOICE=zh_female_shuangkuaisisi_moon_bigtts
```

AWS：

```bash
VOICE_ENABLED=true
VOICE_REGION=us
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1
AWS_TRANSCRIBE_LANGUAGE_CODE=en-US
AWS_POLLY_VOICE=Joanna
```

ElevenLabs：

```bash
VOICE_ENABLED=true
VOICE_REGION=us
ELEVENLABS_API_KEY=...
ELEVENLABS_TTS_MODEL_ID=eleven_multilingual_v2
ELEVENLABS_TTS_VOICE=UgBBYS2sOqTuMpoF3BR0
```

## 监听地址和 TLS

语音服务默认监听 `127.0.0.1:3001`。需要从局域网或服务器外部访问时，设置：

```bash
VOICE_HOST=0.0.0.0
VOICE_PORT=3001
```

生产环境或 HTTPS 控制台访问语音通道时，可以启用 TLS：

```bash
VOICE_TLS_ENABLED=true
VOICE_TLS_CERT_FILE=/path/to/cert.pem
VOICE_TLS_KEY_FILE=/path/to/key.pem
```

配置完成后，控制台会展示客户端应使用的语音 WebSocket 地址。

使用流程见 [语音交互](../../usage/voice.md)。协议消息见 [API 参考](../api.md#websocket)。