fix(#1898): TTS 情绪映射修正为 CosyVoice v3 官方英文枚举（P1 更正） #1933

Merged

xiaoxia merged 1 commits from fix/p1-tts-emotion-enum into develop 2026-09-15 15:08:55 +08:00

Conversation 4 Commits 1 Files Changed 5

+259 -156

xiaoxia commented 2026-09-15 14:23:39 +08:00

Owner

Copy Link

Copy Source

背景

之前 PR#1932 错误地将 normalize_emotion 映射到中文描述词（如"开心愉快""悲伤难过"），但对照阿里云百炼官方文档（https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list）确认：

• CosyVoice v3 instruction 格式严格为 你说话的情感是<情感值>。（结尾中文句号不可省略）
• 情感值必须是 7 种英文枚举之一：neutral/happy/sad/angry/surprised/fearful/disgusted
• 官方示例："你说话的情感是neutral。"

改动

• packages/application/cosyvoice_service.py
  • EMOTION_MAP value 改为英文枚举自身（不再是中文描述词）
  • 新增前端中文 7 标签（中立/开心/难过/生气/惊讶/恐惧/厌恶）→ 英文枚举
  • 旧英文 4 枚举归并到最接近的标准值：natural→neutral, excited→happy, calm→neutral, friendly→happy
  • 常见中文别名（自然/愉快/高兴/快乐/兴奋/悲伤/愤怒/惊奇/害怕/讨厌）也正确映射
  • normalize_emotion：空串/None/纯空白返回空（调用方不传 instruction 走默认自然）；未知值默认 neutral（不返回空，保证合成不中断，打 warning 日志）
  • instruction 拼接注释更新为官方格式说明
• apps/api/app/schemas/lipsync.py、routes/voice_clones.py：description 更新，preview 白名单加入中文 7 标签和常见别名

测试

• tests/unit/test_cosyvoice_emotion.py（重写，89 用例）
  • 7 英文枚举参数化：映射到自身、大小写不敏感、strip 前后空白
  • 前端中文 7 标签 → 正确英文枚举
  • 中文别名、旧英文 4 枚举 → 正确归并
  • 空/None/空白 → 空串；未知值 → neutral + warning
  • instruction 格式严格断言：前缀"你说话的情感是"、结尾单中文句号、中间是纯 ASCII 英文枚举、对照官方示例格式
• tests/unit/test_ai_avatar_emotion_tts_lipsync.py：修正旧断言为英文枚举值，新增中文标签/未知值断言
• tests/unit/test_voice_clone_preview.py：非法 emotion 用例保留

验证

• 本地：15333 passed, 28 skipped
• ruff/black 全过

关联

• 修正 PR#1932 的映射方向错误
• 修复 fix: 配音库AI配音弹窗增加情绪/语言选择，参数真实可用 (#1898)

## 背景 之前 PR#1932 错误地将 normalize_emotion 映射到中文描述词（如"开心愉快""悲伤难过"），但对照阿里云百炼官方文档（https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list）确认： - CosyVoice v3 instruction 格式严格为 `你说话的情感是<情感值>。`（结尾中文句号不可省略） - **情感值必须是 7 种英文枚举之一**：`neutral`/`happy`/`sad`/`angry`/`surprised`/`fearful`/`disgusted` - 官方示例："你说话的情感是neutral。" ## 改动 - `packages/application/cosyvoice_service.py` - EMOTION_MAP value 改为英文枚举自身（不再是中文描述词） - 新增前端中文 7 标签（中立/开心/难过/生气/惊讶/恐惧/厌恶）→ 英文枚举 - 旧英文 4 枚举归并到最接近的标准值：natural→neutral, excited→happy, calm→neutral, friendly→happy - 常见中文别名（自然/愉快/高兴/快乐/兴奋/悲伤/愤怒/惊奇/害怕/讨厌）也正确映射 - normalize_emotion：空串/None/纯空白返回空（调用方不传 instruction 走默认自然）；**未知值默认 neutral**（不返回空，保证合成不中断，打 warning 日志） - instruction 拼接注释更新为官方格式说明 - `apps/api/app/schemas/lipsync.py`、`routes/voice_clones.py`：description 更新，preview 白名单加入中文 7 标签和常见别名 ## 测试 - `tests/unit/test_cosyvoice_emotion.py`（重写，89 用例） - 7 英文枚举参数化：映射到自身、大小写不敏感、strip 前后空白 - 前端中文 7 标签 → 正确英文枚举 - 中文别名、旧英文 4 枚举 → 正确归并 - 空/None/空白 → 空串；未知值 → neutral + warning - **instruction 格式严格断言**：前缀"你说话的情感是"、结尾单中文句号、中间是纯 ASCII 英文枚举、对照官方示例格式 - `tests/unit/test_ai_avatar_emotion_tts_lipsync.py`：修正旧断言为英文枚举值，新增中文标签/未知值断言 - `tests/unit/test_voice_clone_preview.py`：非法 emotion 用例保留 ## 验证 - 本地：**15333 passed, 28 skipped** - ruff/black 全过 ## 关联 - 修正 PR#1932 的映射方向错误 - 修复 #1898

xiaoxia added 1 commit 2026-09-15 14:23:41 +08:00

fix(#1898): TTS 情绪映射修正为 CosyVoice v3 官方英文枚举（P1 更正） ... 74200949b9

关键修复（对照阿里云百炼官方文档 https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list）：
- instruction 格式严格为 "你说话的情感是<情感值>。"，结尾中文句号不可省略
- 情感值必须是 7 种英文枚举之一：neutral/happy/sad/angry/surprised/fearful/disgusted
- 之前 PR#1932 错误地映射成了中文描述词（如"开心愉快"），本次修正为英文枚举

改动：
- EMOTION_MAP value 从中文描述词改为英文枚举自身；新增前端中文 7 标签（中立/开心/难过/生气/惊讶/恐惧/厌恶）→英文枚举；旧英文 4 枚举归并到最接近的标准值（natural→neutral, excited/friendly→happy, calm→neutral）
- normalize_emotion 未知值默认 neutral（不返回空，保证合成不中断），仅空串/None/纯空白返回空（调用方不传 instruction 走默认自然）
- schemas/router 描述更新，voice_clones preview 白名单加入中文 7 标签
- 单测重写：89 个用例断言 instruction 情感值为纯英文 ASCII 枚举；修正旧测试中的中文描述词断言为英文枚举；未知值断言改为默认 neutral

验证：
- 15333 passed, 28 skipped（覆盖 7 英文枚举、中文 7 标签、中文别名、旧英文、大小写、空白、未知值、instruction 格式、白名单）
- ruff/black 全过

gitea-actions bot commented 2026-09-15 14:26:16 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1933
预览链接	https://pr-1933.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1933 | | 预览链接 | [https://pr-1933.preview.xiaoxiajianji.com](https://pr-1933.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

xiaoxia reviewed 2026-09-15 15:05:41 +08:00

xiaoxia left a comment

Author

Owner

Copy Link

Copy Source

CI green, verified instruction format against CosyVoice v3 official docs (emotion values must be English enums: neutral/happy/sad/angry/surprised/fearful/disgusted)

CI green, verified instruction format against CosyVoice v3 official docs (emotion values must be English enums: neutral/happy/sad/angry/surprised/fearful/disgusted)

xiaoxia reviewed 2026-09-15 15:05:56 +08:00

xiaoxia left a comment

Author

Owner

Copy Link

Copy Source

CI green, fixes emotion mapping to official English enums

CI green, fixes emotion mapping to official English enums

xiaoxia merged commit 81180d16e5 into develop 2026-09-15 15:08:55 +08:00

gitea-actions bot commented 2026-09-15 15:09:36 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1933 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1933 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

xiaoxia referenced this issue from a commit 2026-09-15 17:07:01 +08:00

fix(#1894): rebase title library merge on latest develop

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot frontend-dev xiaoxia

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1933