5.9 KiB
5.9 KiB
MiniMax WebSocket TTS 流式语音合成使用说明
概述
已成功集成 MiniMax WebSocket API 实现流式文本转语音（TTS），相比传统 HTTP API 速度更快，支持实时流式返回音频数据。
技术架构
前端 → 后端 HTTP/WebSocket → 后端 WebSocket 客户端 → MiniMax WebSocket API
- 传统方式 (
minimax): 使用 HTTP REST API，需要等待完整音频生成后返回（慢） - 新方式 (
minimax-ws): 使用 WebSocket，边生成边返回音频流（快）
快速开始
1. 数据库配置
在 sys_config 表中配置 TTS 服务：
-- 更新现有配置或插入新配置
UPDATE sys_config
SET provider = 'minimax-ws' -- 使用 WebSocket 版本
WHERE config_id = YOUR_CONFIG_ID;
-- 或者插入新配置
INSERT INTO sys_config (provider, api_key, config_name, config_type)
VALUES (
'minimax-ws', -- 使用 WebSocket 版本
'your_minimax_api_key',
'MiniMax WebSocket TTS',
'TTS'
);
Provider 选项对比：
minimax- HTTP REST API（旧版，慢）minimax-ws- WebSocket 流式 API（新版，快）✅ 推荐
2. 后端使用示例
方式一：普通 TTS（保存文件）
@Resource
private TtsServiceFactory ttsServiceFactory;
public String generateSpeech(String text) {
// 从数据库获取配置
SysConfig config = configService.getConfig(configId);
// 获取 TTS 服务（会自动使用 WebSocket 版本）
TtsService ttsService = ttsServiceFactory.getTtsService(config, voiceName);
// 生成语音文件
String audioFilePath = ttsService.textToSpeech(text);
return audioFilePath;
}
方式二：流式 TTS（实时返回）
@Resource
private TtsServiceFactory ttsServiceFactory;
public void generateSpeechStream(String text, Consumer<byte[]> callback) throws Exception {
SysConfig config = new SysConfig()
.setProvider("minimax-ws")
.setApiKey("your_api_key");
MiniMaxTtsWebSocketService service = (MiniMaxTtsWebSocketService)
ttsServiceFactory.getTtsService(config, voiceName);
// 流式生成，每收到一个音频块就调用 callback
service.textToSpeechStream(text, null, audioChunk -> {
// 可以立即发送给前端
callback.accept(audioChunk);
});
}
3. 前端调用
HTTP 方式（现有接口）
前端调用现有的 /voice-chat 接口，只需要在数据库中将 provider 改为 minimax-ws 即可，前端代码无需修改。
const result = await voiceAPI.voiceChat(audioFile, {
sessionId: conversationId,
modelId: 10,
templateId: 6,
ttsConfigId: YOUR_CONFIG_ID, // 使用配置了 minimax-ws 的配置
});
WebSocket 方式（流式传输，待实现）
如果需要前端实时接收音频流，可以创建新的 WebSocket 端点：
const ws = new WebSocket('ws://localhost:8091/ws/tts/stream');
ws.onopen = () => {
ws.send(JSON.stringify({
text: '你好，这是流式语音合成测试',
voiceName: 'Chinese (Mandarin)_BashfulGirl',
configId: YOUR_CONFIG_ID
}));
};
ws.onmessage = (event) => {
// 接收音频流数据
const audioChunk = event.data;
// 可以立即播放，无需等待完整文件
playAudioChunk(audioChunk);
};
API 参考
MiniMaxTtsWebSocketService
public class MiniMaxTtsWebSocketService implements TtsService {
/**
* 标准 TTS 接口 - 生成完整音频文件
*/
public String textToSpeech(String text) throws Exception;
/**
* 流式 TTS 接口 - 支持回调
* @param text 要转换的文本
* @param outputFilePath 输出文件路径（可为 null，不保存文件）
* @param streamCallback 音频流回调（可为 null）
*/
public void textToSpeechStream(
String text,
String outputFilePath,
Consumer<byte[]> streamCallback
) throws Exception;
}
配置参数
T2AWsRequest.VoiceSetting voiceSetting = new T2AWsRequest.VoiceSetting()
.setVoiceId("Chinese (Mandarin)_BashfulGirl") // 音色 ID
.setSpeed(1.0) // 语速 (0.5-2.0)
.setVol(1.0) // 音量 (0.1-1.5)
.setPitch(0); // 音调 (-12到12)
T2AWsRequest.AudioSetting audioSetting = new T2AWsRequest.AudioSetting()
.setSampleRate(32000) // 采样率
.setBitrate(128000) // 比特率
.setFormat("mp3") // 格式 (mp3/wav/pcm)
.setChannel(1); // 声道数
性能对比
| 方式 | 平均延迟 | 首字节延迟 | 适用场景 |
|---|---|---|---|
HTTP REST (minimax) |
2-5秒 | 2-5秒 | 离线生成、批量处理 |
WebSocket (minimax-ws) |
0.5-1秒 | 200-500ms | 实时对话、流式播放 |
常见问题
Q: 如何切换到 WebSocket 版本？
A: 在数据库 sys_config 表中将 provider 字段改为 minimax-ws 即可，代码无需修改。
Q: 是否支持同时使用 HTTP 和 WebSocket？
A: 支持。可以为不同的配置设置不同的 provider：
- 配置 1:
provider = 'minimax'(HTTP) - 配置 2:
provider = 'minimax-ws'(WebSocket)
Q: 是否需要修改前端代码？
A: 不需要。只需在数据库中修改配置即可。
Q: 遇到连接超时怎么办？
A: 检查：
- API Key 是否正确
- 网络是否可以访问
wss://api.minimax.io - 文本长度是否超过限制
- 查看后端日志中的详细错误信息
日志说明
WebSocket 服务会输出详细的调试日志：
🔗 MiniMax WebSocket 连接已建立
📤 已发送请求: {...}
🎵 收到音频数据块，大小: 4096 bytes
✅ 语音合成完成，共收到 15 个音频块
💾 音频文件已保存: audio/tts_xxx.mp3
参考文档
- MiniMax WebSocket API 官方文档: https://platform.minimax.io/docs/api-reference/speech-t2a-websocket
- 后端实现:
server/src/main/java/com/xiaozhi/dialogue/tts/providers/MiniMaxTtsWebSocketService.java
更新记录
- 2024-11-29: 初版发布，支持 MiniMax WebSocket TTS