fix: CosyVoice全量重写 - 适配DashScope百炼API #212

Merged

xiaoxia merged 2 commits from fix/cosyvoice-full-rewrite into develop 2026-07-10 22:52:22 +08:00

Conversation 2 Commits 2 Files Changed 9

+943 -913

xiaoxia commented 2026-07-10 22:17:53 +08:00

Owner

Copy Link

Copy Source

背景

CosyVoice原有实现基于旧版接口，导致音色克隆和TTS合成持续失败（401认证失败、task can not be null等错误）。本次全量重写以适配正确的DashScope百炼API。

变更内容

配置更新

• cosyvoice_base_url 改为 https://dashscope.aliyuncs.com/api/v1
• cosyvoice_model 改为 cosyvoice-v3.5-plus
• 新增 cosyvoice_clone_model = "voice-enrollment"

音色克隆

• 路径：POST /services/audio/tts/customization
• model：voice-enrollment
• action：create_voice
• body：{action, target_model, prefix, url}
• 返回 voice_id（替代旧的 task_id）

状态查询

• 同路径 POST /services/audio/tts/customization
• action：query_voice
• 返回状态：DEPLOYING / OK / UNDEPLOYED

语音合成

• 路径：POST /services/audio/tts/SpeechSynthesizer
• 非流式同步接口，直接返回 audio_url
• 无需轮询任务状态

OSS音频预签名

• 新增 audio_url_signer 钩子参数
• 对私有bucket的音频URL进行预签名（slash_safe=True）
• 确保CosyVoice服务器能下载到训练音频

Workflow适配

• voice_clone：voice_id 替代 task_id，status=OK 标记ready
• tts_job：同步接口直接返回，异常时自动重新合成兜底

两端注入

• API端 dependencies.py：注入OSS预签名函数
• Worker端 voice_clone.py：注入OSS预签名函数

测试

• test_cosyvoice_service.py：36个测试，全部通过
• test_voice_clone_workflow.py：18个测试，全部通过

涉及文件（8个）

• packages/shared/config.py
• packages/application/cosyvoice_service.py
• packages/application/voice_clone/workflow.py
• packages/application/tts_job/workflow.py
• apps/api/app/dependencies.py
• apps/worker/worker_app/tasks/voice_clone.py
• tests/unit/test_cosyvoice_service.py
• tests/unit/test_voice_clone_workflow.py

## 背景 CosyVoice原有实现基于旧版接口，导致音色克隆和TTS合成持续失败（401认证失败、task can not be null等错误）。本次全量重写以适配正确的DashScope百炼API。 ## 变更内容 ### 配置更新 - `cosyvoice_base_url` 改为 `https://dashscope.aliyuncs.com/api/v1` - `cosyvoice_model` 改为 `cosyvoice-v3.5-plus` - 新增 `cosyvoice_clone_model = "voice-enrollment"` ### 音色克隆 - 路径：`POST /services/audio/tts/customization` - model：`voice-enrollment` - action：`create_voice` - body：`{action, target_model, prefix, url}` - 返回 `voice_id`（替代旧的 `task_id`） ### 状态查询 - 同路径 `POST /services/audio/tts/customization` - action：`query_voice` - 返回状态：`DEPLOYING` / `OK` / `UNDEPLOYED` ### 语音合成 - 路径：`POST /services/audio/tts/SpeechSynthesizer` - 非流式同步接口，直接返回 `audio_url` - 无需轮询任务状态 ### OSS音频预签名 - 新增 `audio_url_signer` 钩子参数 - 对私有bucket的音频URL进行预签名（slash_safe=True） - 确保CosyVoice服务器能下载到训练音频 ### Workflow适配 - voice_clone：`voice_id` 替代 `task_id`，`status=OK` 标记ready - tts_job：同步接口直接返回，异常时自动重新合成兜底 ### 两端注入 - API端 `dependencies.py`：注入OSS预签名函数 - Worker端 `voice_clone.py`：注入OSS预签名函数 ## 测试 - `test_cosyvoice_service.py`：36个测试，全部通过 - `test_voice_clone_workflow.py`：18个测试，全部通过 ## 涉及文件（8个） - `packages/shared/config.py` - `packages/application/cosyvoice_service.py` - `packages/application/voice_clone/workflow.py` - `packages/application/tts_job/workflow.py` - `apps/api/app/dependencies.py` - `apps/worker/worker_app/tasks/voice_clone.py` - `tests/unit/test_cosyvoice_service.py` - `tests/unit/test_voice_clone_workflow.py`

xiaoxia added 1 commit 2026-07-10 22:17:53 +08:00

fix: CosyVoice全量重写 - 适配DashScope百炼API ... 506eae98f1

- 配置更新：base_url改为api/v1，model改为cosyvoice-v3.5-plus，新增clone_model=voice-enrollment
- 音色克隆：适配customization接口 + voice-enrollment模型 + create_voice action
- 状态查询：适配同路径query_voice action（POST），返回DEPLOYING/OK/UNDEPLOYED
- 语音合成：适配SpeechSynthesizer非流式同步接口，直接返回audio_url
- 新增audio_url_signer钩子：对私有bucket音频URL预签名（slash_safe=True）
- voice_clone workflow适配：voice_id替代task_id，status=OK标记ready
- tts_job workflow适配：同步接口直接返回，无task_id时自动重新合成兜底
- API端+Worker端依赖注入OSS预签名函数
- 单元测试：36个service测试 + 18个workflow测试，全部通过

xiaoxia commented 2026-07-10 22:28:31 +08:00

Author

Owner

Copy Link

Copy Source

代码审计报告 — PR #212 CosyVoice全量重写

结论：🔴 不通过（存在 P0 级语法错误）

---

🔴 P0 — TTS workflow 文件语法错误（阻断）

位置：packages/application/tts_job/workflow.py 第312行 process_synthesis_failure 方法

问题：docstring 被错误地单行闭合

# 错误写法（PR #212 引入）
def process_synthesis_failure(self, job_id: str, error_message: str) -> TTSJob:
    """处理合成失败结果。"""   # ← 这里单行闭合了

    Args:                    # ← 这行变成了代码，语法错误！
        job_id: TTSJob ID
    ...
    """                      # ← 这个变成了独立字符串

影响：

• 整个 tts_job/workflow.py 文件无法 import
• 所有 TTS 相关功能完全不可用
• 所有依赖该模块的测试全部无法收集

修复方案：把第一行的 """处理合成失败结果。""" 改回 """处理合成失败结果。（去掉末尾的 """），保持多行 docstring 结构不变。

---

🟡 P1 — 重合成兜底路径丢失 speed/volume 参数

位置：_resynthesize_and_complete() 方法

问题：重新调用 submit_synthesize_task 时只传了 text、voice_id、sample_rate、format，没有传 speed 和 volume，导致兜底合成的语速音量与原始请求不一致。

修复建议：从 job 对象中读取 speed/volume（如果 metadata 里有存的话），或者在 job 实体上增加这两个字段。

---

🟡 P1 — 旧分段任务走到轮询路径会直接抛异常

位置：_poll_segment_tasks() 方法第506行

问题：

• 新 CosyVoice 接口是同步的，poll_synthesize_task() 会直接抛 CosyVoiceError("同步接口无需轮询")
• 如果有旧版分段任务（metadata 含 segment_task_ids），走到这里会直接失败
• 虽然旧接口本来就不能用，存量有效任务为0，但代码设计上有隐患

修复建议：在 _poll_segment_tasks 中检测到 task_id 为空或新接口模式时，改为直接重新同步合成（与单段兜底逻辑一致）。

---

🟢 P2 — 音色克隆 payload 结构需验证

位置：submit_clone_task() 的 payload

问题：当前音色克隆 payload 只有 model + input，没有 parameters 字段。百炼 Voice Design API 的格式是 input + parameters 双层结构，音色克隆（voice-enrollment）是否同样需要 parameters 层需 staging 验证。

建议：先上 staging 实测，如果报参数错误再调整结构。

---

🟢 P3 — 兼容层命名易混淆

• check_task_status(task_id)：参数名是 task_id，实际传的是 voice_id，容易误导后续维护者。建议加 type hint 注释或直接重命名。
• poll_synthesize_task()：直接抛异常太粗暴，建议加 DeprecationWarning 或在 docstring 标注 deprecated。

---

✅ 已验证正确的项

项	状态
语音合成 payload 结构（全在 input 里）	✅ 与官方文档一致
语音合成 API 路径 SpeechSynthesizer	✅ 正确
音色克隆 API 路径 customization	✅ 正确
URL 拼接（base_url + path）	✅ 正确
base_url / model / clone_model 配置	✅ 完整
API 端 audio_url_signer 注入	✅ 正确
Worker 端 audio_url_signer 注入	✅ 正确
start_synthesis 同步完成路径	✅ 原有逻辑可用
分段合成同步路径	✅ 正确
voice_clone 轮询兼容	✅ 正确
400/401/500 错误处理	✅ 完善
重试逻辑	✅ 指数退避
prefix 清洗（字母数字+10字符限制）	✅ 正确

---

📊 测试覆盖

• test_cosyvoice_service.py：36 个测试，全部通过 ✅
• test_voice_clone_workflow.py：18 个测试，全部通过 ✅
• test_tts_*.py：因 P0 语法错误无法收集测试 ❌

---

📋 修复优先级

1. 立即修 P0：docstring 单行闭合问题（1 分钟能改好）
2. 建议修 P1：重合成丢参数 + 分段轮询异常
3. staging 测 P2：音色克隆 payload 结构验证

修完 P0 后我再复审一次。

## 代码审计报告 — PR #212 CosyVoice全量重写 **结论：🔴 不通过（存在 P0 级语法错误）** --- ### 🔴 P0 — TTS workflow 文件语法错误（阻断） **位置**：`packages/application/tts_job/workflow.py` 第312行 `process_synthesis_failure` 方法 **问题**：docstring 被错误地单行闭合 ```python # 错误写法（PR #212 引入） def process_synthesis_failure(self, job_id: str, error_message: str) -> TTSJob: """处理合成失败结果。""" # ← 这里单行闭合了 Args: # ← 这行变成了代码，语法错误！ job_id: TTSJob ID ... """ # ← 这个变成了独立字符串 ``` **影响**： - 整个 `tts_job/workflow.py` 文件无法 import - 所有 TTS 相关功能完全不可用 - 所有依赖该模块的测试全部无法收集 **修复方案**：把第一行的 `"""处理合成失败结果。"""` 改回 `"""处理合成失败结果。`（去掉末尾的 `"""`），保持多行 docstring 结构不变。 --- ### 🟡 P1 — 重合成兜底路径丢失 speed/volume 参数 **位置**：`_resynthesize_and_complete()` 方法 **问题**：重新调用 `submit_synthesize_task` 时只传了 `text`、`voice_id`、`sample_rate`、`format`，没有传 `speed` 和 `volume`，导致兜底合成的语速音量与原始请求不一致。 **修复建议**：从 `job` 对象中读取 speed/volume（如果 metadata 里有存的话），或者在 job 实体上增加这两个字段。 --- ### 🟡 P1 — 旧分段任务走到轮询路径会直接抛异常 **位置**：`_poll_segment_tasks()` 方法第506行 **问题**： - 新 CosyVoice 接口是同步的，`poll_synthesize_task()` 会直接抛 `CosyVoiceError("同步接口无需轮询")` - 如果有旧版分段任务（metadata 含 segment_task_ids），走到这里会直接失败 - 虽然旧接口本来就不能用，存量有效任务为0，但代码设计上有隐患 **修复建议**：在 `_poll_segment_tasks` 中检测到 task_id 为空或新接口模式时，改为直接重新同步合成（与单段兜底逻辑一致）。 --- ### 🟢 P2 — 音色克隆 payload 结构需验证 **位置**：`submit_clone_task()` 的 payload **问题**：当前音色克隆 payload 只有 `model + input`，没有 `parameters` 字段。百炼 Voice Design API 的格式是 `input + parameters` 双层结构，音色克隆（`voice-enrollment`）是否同样需要 `parameters` 层需 staging 验证。 **建议**：先上 staging 实测，如果报参数错误再调整结构。 --- ### 🟢 P3 — 兼容层命名易混淆 - `check_task_status(task_id)`：参数名是 task_id，实际传的是 voice_id，容易误导后续维护者。建议加 type hint 注释或直接重命名。 - `poll_synthesize_task()`：直接抛异常太粗暴，建议加 `DeprecationWarning` 或在 docstring 标注 deprecated。 --- ### ✅ 已验证正确的项 | 项 | 状态 | |----|------| | 语音合成 payload 结构（全在 input 里） | ✅ 与官方文档一致 | | 语音合成 API 路径 SpeechSynthesizer | ✅ 正确 | | 音色克隆 API 路径 customization | ✅ 正确 | | URL 拼接（base_url + path） | ✅ 正确 | | base_url / model / clone_model 配置 | ✅ 完整 | | API 端 audio_url_signer 注入 | ✅ 正确 | | Worker 端 audio_url_signer 注入 | ✅ 正确 | | start_synthesis 同步完成路径 | ✅ 原有逻辑可用 | | 分段合成同步路径 | ✅ 正确 | | voice_clone 轮询兼容 | ✅ 正确 | | 400/401/500 错误处理 | ✅ 完善 | | 重试逻辑 | ✅ 指数退避 | | prefix 清洗（字母数字+10字符限制） | ✅ 正确 | --- ### 📊 测试覆盖 - `test_cosyvoice_service.py`：36 个测试，全部通过 ✅ - `test_voice_clone_workflow.py`：18 个测试，全部通过 ✅ - `test_tts_*.py`：因 P0 语法错误无法收集测试 ❌ --- ### 📋 修复优先级 1. **立即修 P0**：docstring 单行闭合问题（1 分钟能改好） 2. **建议修 P1**：重合成丢参数 + 分段轮询异常 3. **staging 测 P2**：音色克隆 payload 结构验证 修完 P0 后我再复审一次。

xiaoxia referenced this issue from a commit 2026-07-10 22:41:26 +08:00

fix: PR #212 P0+P1 问题修复

xiaoxia added 1 commit 2026-07-10 22:41:26 +08:00

fix: PR #212 P0+P1 问题修复 ... 1d2aaad52f

- P0: 修复 process_synthesis_failure docstring 语法错误（三引号位置错误）
- P1: _resynthesize_and_complete 补上 speed/volume 参数传递（从metadata读取）
- P1: _poll_segment_tasks 适配新同步接口，缺失分段重新同步合成而非轮询
  - 移除 time 依赖（不再轮询）
  - 并发重新合成缺失 audio_url 的分段
  - 已有 audio_url 的分段直接复用
- 新增 1 个分段复用测试用例

xiaoxia commented 2026-07-10 22:47:33 +08:00

Author

Owner

Copy Link

Copy Source

代码审计复审 — PR #212 CosyVoice全量重写（第二轮）

结论：✅ 通过，可合并

---

修复验证

问题	等级	修复状态
process_synthesis_failure docstring 语法错误	P0	✅ 已修复
_resynthesize_and_complete 丢失 speed/volume 参数	P1	✅ 已修复
_poll_segment_tasks 抛异常（同步接口无需轮询）	P1	✅ 已修复

---

详细验证

✅ P0 — docstring 语法错误已修复

process_synthesis_failure 方法的 docstring 已恢复多行结构，Args/Returns/Raises 正确包含在三引号内。文件语法检查通过，所有 TTS 测试可正常收集运行。

✅ P1-1 — 兜底路径补上 speed/volume

_resynthesize_and_complete 方法从 job.metadata 读取 speed 和 volume 参数（默认值 1.0/50），传入 submit_synthesize_task。虽然当前主路径也未将 speed 写入 metadata（历史遗留），但兜底路径与主路径行为保持一致，且为未来支持 speed 参数铺路。

✅ P1-2 — 分段任务路径适配同步接口

_poll_segment_tasks 完全重写，移除了轮询逻辑和 time 依赖：

• 已有 audio_url 的分段直接复用
• 缺失音频的分段并发重新同步合成
• 合成失败走 _handle_segment_failure 正常标记 failed
• 新增 test_partial_audio_urls_reuse_existing 测试用例

---

📊 测试覆盖

测试文件	数量	结果
test_cosyvoice_service.py	36	✅ 全部通过
test_voice_clone_workflow.py	18	✅ 全部通过
test_tts_segment_synthesis.py	24	✅ 全部通过（新增 1 个分段复用用例）
合计	78	✅ 全部通过

---

⚪ 未修复项（不阻断合并）

• P2 — 音色克隆 payload 结构：需 staging 环境实测验证，不在本次代码修复范围
• P3 — 兼容层命名优化：check_task_status 参数名、poll_synthesize_task 废弃标记，低优先级建议

---

📌 备注

主路径（start_synthesis / _start_segment_synthesis）同样没有传递 speed/volume 到 CosyVoice，这是历史遗留问题（API 层有 speed 字段但未下传），非 PR #212 引入。建议后续迭代中将 speed 写入 metadata 并在 workflow 层透传。

整体结论：P0/P1 全部清零，78 个测试全绿，可合并。

## 代码审计复审 — PR #212 CosyVoice全量重写（第二轮） **结论：✅ 通过，可合并** --- ### 修复验证 | 问题 | 等级 | 修复状态 | |------|------|----------| | process_synthesis_failure docstring 语法错误 | P0 | ✅ 已修复 | | _resynthesize_and_complete 丢失 speed/volume 参数 | P1 | ✅ 已修复 | | _poll_segment_tasks 抛异常（同步接口无需轮询） | P1 | ✅ 已修复 | --- ### 详细验证 #### ✅ P0 — docstring 语法错误已修复 `process_synthesis_failure` 方法的 docstring 已恢复多行结构，Args/Returns/Raises 正确包含在三引号内。文件语法检查通过，所有 TTS 测试可正常收集运行。 #### ✅ P1-1 — 兜底路径补上 speed/volume `_resynthesize_and_complete` 方法从 `job.metadata` 读取 `speed` 和 `volume` 参数（默认值 1.0/50），传入 `submit_synthesize_task`。虽然当前主路径也未将 speed 写入 metadata（历史遗留），但兜底路径与主路径行为保持一致，且为未来支持 speed 参数铺路。 #### ✅ P1-2 — 分段任务路径适配同步接口 `_poll_segment_tasks` 完全重写，移除了轮询逻辑和 `time` 依赖： - 已有 `audio_url` 的分段直接复用 - 缺失音频的分段并发重新同步合成 - 合成失败走 `_handle_segment_failure` 正常标记 failed - 新增 `test_partial_audio_urls_reuse_existing` 测试用例 --- ### 📊 测试覆盖 | 测试文件 | 数量 | 结果 | |----------|------|------| | test_cosyvoice_service.py | 36 | ✅ 全部通过 | | test_voice_clone_workflow.py | 18 | ✅ 全部通过 | | test_tts_segment_synthesis.py | 24 | ✅ 全部通过（新增 1 个分段复用用例） | | **合计** | **78** | **✅ 全部通过** | --- ### ⚪ 未修复项（不阻断合并） - **P2 — 音色克隆 payload 结构**：需 staging 环境实测验证，不在本次代码修复范围 - **P3 — 兼容层命名优化**：`check_task_status` 参数名、`poll_synthesize_task` 废弃标记，低优先级建议 --- ### 📌 备注 主路径（`start_synthesis` / `_start_segment_synthesis`）同样没有传递 speed/volume 到 CosyVoice，这是历史遗留问题（API 层有 speed 字段但未下传），非 PR #212 引入。建议后续迭代中将 speed 写入 metadata 并在 workflow 层透传。 **整体结论：P0/P1 全部清零，78 个测试全绿，可合并。**

xiaoxia merged commit 3db13fc1da into develop 2026-07-10 22:52:22 +08:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#212