134 lines
3.3 KiB
Markdown
134 lines
3.3 KiB
Markdown
# Technical Design: Voice Clone Provider Refactoring
|
||
|
||
## Context
|
||
|
||
当前语音克隆功能直接依赖阿里云 CosyVoice 的 SDK 和 API。Service 层直接调用 `CosyVoiceClient`，导致：
|
||
|
||
1. **强耦合**：无法轻松切换或添加其他供应商
|
||
2. **测试困难**：难以 mock 外部依赖
|
||
3. **扩展性差**：添加新供应商需要修改 Service 层
|
||
|
||
## Goals / Non-Goals
|
||
|
||
### Goals
|
||
- 解耦 Service 层与具体供应商实现
|
||
- 支持多供应商并存和动态切换
|
||
- 保持现有功能完全兼容
|
||
- 为添加硅基流动 IndexTTS-2 打下基础
|
||
|
||
### Non-Goals
|
||
- 不改变现有 API 行为
|
||
- 不修改数据库结构
|
||
- 不改变前端交互
|
||
|
||
## Decisions
|
||
|
||
### 1. 采用策略模式 + 工厂模式
|
||
|
||
**Why**:
|
||
- 策略模式：定义统一接口，各供应商独立实现
|
||
- 工厂模式：根据配置动态获取 Provider 实例
|
||
- 符合开闭原则，扩展时无需修改现有代码
|
||
|
||
**架构**:
|
||
```
|
||
VoiceCloneProvider (interface)
|
||
├── CosyVoiceProvider (impl) - 阿里云 CosyVoice (DashScope)
|
||
├── SiliconFlowProvider (impl) - 阶段二：硅基流动 IndexTTS-2
|
||
└── VoiceCloneProviderFactory
|
||
```
|
||
|
||
**说明**:
|
||
- `CosyVoiceProvider` 对应阿里云 DashScope 的语音服务
|
||
- 默认模型：`cosyvoice-v3-flash`
|
||
- 扩展时添加新的 Provider 实现
|
||
|
||
### 2. 统一 DTO 设计
|
||
|
||
**Why**: 屏蔽不同供应商的 API 差异
|
||
|
||
```java
|
||
// 统一请求
|
||
VoiceCloneRequest {
|
||
String audioUrl; // 音频 URL
|
||
String prefix; // 音色前缀
|
||
String targetModel; // 目标模型
|
||
}
|
||
|
||
// 统一响应
|
||
VoiceCloneResult {
|
||
String voiceId; // 生成的音色 ID
|
||
String requestId; // 请求 ID
|
||
}
|
||
```
|
||
|
||
### 3. 配置结构设计
|
||
|
||
**新配置结构**:
|
||
```yaml
|
||
yudao:
|
||
voice:
|
||
# 默认供应商
|
||
default-provider: cosyvoice
|
||
|
||
# 供应商配置
|
||
providers:
|
||
cosyvoice: # 阿里云 CosyVoice
|
||
enabled: true
|
||
api-key: ${DASHSCOPE_API_KEY}
|
||
default-model: cosyvoice-v3-flash
|
||
# ... 其他配置
|
||
|
||
siliconflow: # 阶段二添加
|
||
enabled: false
|
||
api-key: ${SILICONFLOW_API_KEY}
|
||
base-url: https://api.siliconflow.cn
|
||
default-model: indextts-2
|
||
```
|
||
|
||
**向后兼容**:
|
||
- 读取旧配置 `yudao.cosyvoice.*` 并合并到新结构
|
||
- 优先使用新配置，旧配置作为 fallback
|
||
|
||
### 4. 错误处理策略
|
||
|
||
- Provider 调用失败时，记录详细日志
|
||
- 返回统一的业务异常 `VOICE_TTS_FAILED`
|
||
- 不暴露底层供应商的技术细节
|
||
|
||
## Risks / Trade-offs
|
||
|
||
| Risk | Mitigation |
|
||
|------|------------|
|
||
| 破坏现有功能 | 充分测试，保持 DTO 兼容 |
|
||
| 配置迁移复杂 | 支持旧配置自动映射 |
|
||
| 性能开销 | 工厂缓存 Provider 实例 |
|
||
|
||
## Migration Plan
|
||
|
||
### 阶段一：CosyVoice 重构
|
||
1. 创建接口和工厂
|
||
2. 重构 CosyVoice 为 Provider 实现
|
||
3. 更新 Service 层使用接口
|
||
4. 测试验证
|
||
|
||
### 阶段二：添加 SiliconFlow
|
||
1. 实现 SiliconFlowProvider
|
||
2. 添加配置支持
|
||
3. 集成测试
|
||
|
||
### 回滚方案
|
||
- 保留原有配置支持
|
||
- Feature Flag 控制新逻辑
|
||
|
||
## Open Questions
|
||
|
||
1. **Q**: 是否需要支持运行时动态切换供应商？
|
||
**A**: 初期不支持，通过配置切换即可
|
||
|
||
2. **Q**: 是否需要 Provider 健康检查？
|
||
**A**: 阶段二考虑添加
|
||
|
||
3. **Q**: DTO 字段差异如何处理？
|
||
**A**: 使用公共字段，扩展字段放 `Map<String, Object> extensions`
|