sionrui/openspec/changes/add-siliconflow-voice-provider/specs/voice-clone/spec.md

ADDED Requirements

Requirement: SiliconFlow 语音克隆支持

系统 MUST 支持使用硅基流动（SiliconFlow）作为语音克隆供应商，允许用户上传参考音频并生成可复用的音色 ID。

Scenario: 成功使用硅基流动克隆音色

• GIVEN 用户已上传参考音频文件并获得文件 URL
• AND 参考音频已成功转录为文本
• AND 硅基流动供应商已启用并配置有效的 API Key
• WHEN 用户通过 API 发起语音克隆请求，指定 providerType 为 siliconflow
• THEN 系统应当下载参考音频文件并转换为 base64 格式
• AND 调用硅基流动 /v1/uploads/audio/voice API，使用 IndexTeam/IndexTTS-2 模型
• AND 将返回的 uri（格式如 speech:customName:xxx:xxx）存储为 voiceId
• AND 返回克隆成功的响应，包含生成的 voiceId

Scenario: 硅基流动 API 调用失败

• GIVEN 硅基流动供应商已启用
• WHEN 调用硅基流动 API 时发生网络错误或认证失败
• THEN 系统应当记录详细的错误日志
• AND 返回统一错误码 VOICE_TTS_FAILED，不暴露底层技术细节

Scenario: 硅基流动供应商未配置

• GIVEN 硅基流动供应商未启用或 API Key 未配置
• WHEN 用户尝试使用硅基流动进行语音克隆
• THEN 系统应当返回友好的错误提示，要求管理员先配置硅基流动

---

Requirement: SiliconFlow 文本转语音支持

系统 MUST 支持使用硅基流动进行文本转语音合成，允许用户使用已克隆的音色 ID 或系统默认音色合成语音。

Scenario: 使用克隆音色合成语音

• GIVEN 用户已通过硅基流动成功克隆音色，获得 voiceId
• AND 硅基流动供应商已启用
• WHEN 用户发起 TTS 请求，指定 providerType 为 siliconflow 和有效的 voiceId
• THEN 系统应当调用硅基流动 /v1/audio/speech API
• AND 使用 IndexTeam/IndexTTS-2 模型和指定的 voiceId
• AND 将返回的音频二进制数据转换为 base64 格式
• AND 返回包含音频数据、格式和采样率的响应

Scenario: 使用默认音色合成语音

• GIVEN 硅基流动供应商已启用
• AND 用户未指定 voiceId
• WHEN 用户发起 TTS 请求，指定 providerType 为 siliconflow
• THEN 系统应当使用硅基流动提供的默认音色进行合成
• AND 返回合成结果

Scenario: TTS 合成参数支持

• GIVEN 硅基流动供应商已启用
• WHEN 用户发起 TTS 请求，包含可选参数（语速、采样率、音频格式）
• THEN 系统应当将这些参数适配为硅基流动 API 格式
• AND 支持的参数包括：speed（0.25-4.0）、sample_rate、response_format（mp3/wav/pcm）

---

Requirement: 供应商动态切换

系统 SHALL 支持在请求时动态指定语音供应商，无需重启服务。

Scenario: 通过 providerType 切换供应商

• GIVEN 系统已配置 CosyVoice 和 SiliconFlow 两个供应商
• AND 默认供应商为 cosyvoice
• WHEN 用户在 API 请求中指定 providerType 为 siliconflow
• THEN 系统应当使用 SiliconFlowProvider 处理请求
• AND 不影响其他使用默认供应商的请求

Scenario: 不支持的供应商类型

• GIVEN 系统仅配置了 CosyVoice 和 SiliconFlow 供应商
• WHEN 用户指定 providerType 为不存在的值（如 other）
• THEN 系统应当返回错误提示 "不支持的语音克隆供应商: other"

---

Requirement: SiliconFlow 配置管理

系统 MUST 支持通过配置文件管理硅基流动供应商的启用状态和连接参数。

Scenario: 配置硅基流动供应商

• GIVEN 管理员希望在系统中启用硅基流动
• WHEN 管理员在 application.yaml 中配置以下参数：

  yudao:
    voice:
      providers:
        siliconflow:
          enabled: true
          api-key: sk-xxxxx
          base-url: https://api.siliconflow.cn
          default-model: IndexTeam/IndexTTS-2
  

• THEN 系统应当在启动时注册 SiliconFlowProvider
• AND 用户可以通过指定 providerType 为 siliconflow 使用该供应商

Scenario: 禁用硅基流动供应商

• GIVEN 硅基流动供应商已配置
• WHEN 管理员将 enabled 设置为 false 或移除配置
• THEN 系统启动时不应注册 SiliconFlowProvider
• AND 用户请求硅基流动服务时应当返回错误提示

Scenario: 向后兼容旧配置

• GIVEN 系统已从旧版本升级，存在 yudao.cosyvoice.* 配置
• WHEN 系统启动时检测到旧配置
• THEN 系统应当自动将旧配置迁移到 yudao.voice.providers.cosyvoice.* 结构
• AND 优先使用新配置，旧配置作为 fallback