|
|
@@ -35,6 +35,110 @@ if (aliyunMatch) {
|
|
|
}
|
|
|
}
|
|
|
|
|
|
+// ========== CosyVoice 指令使用指南(权威资料,2025-07-12 从阿里云官方文档摘录) ==========
|
|
|
+// 由用户从官方页面 https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list
|
|
|
+// 整理出来的 4 个模型 + 指令规则 + 描述原则 + 示例。脚本自动随 docs 重生成。
|
|
|
+const INSTRUCTION_GUIDE = `
|
|
|
+## CosyVoice 指令使用指南(重要)
|
|
|
+
|
|
|
+> 来源:阿里云官方文档 https://help.aliyun.com/zh/model-studio/cosyvoice-voice-list,2025-07-12 摘录。
|
|
|
+> 本项目用的是 \`cosyvoice-v3-flash\`(默认)和 \`qwen3-tts-instruct-flash\`,下面的指令规则适用。
|
|
|
+
|
|
|
+### 支持的 4 个模型
|
|
|
+
|
|
|
+| 模型 | 价格层 | 推荐场景 |
|
|
|
+|------|--------|----------|
|
|
|
+| \`cosyvoice-v3.5-plus\` | 高质量 | 重点音频,情感/语速精细控制 |
|
|
|
+| \`cosyvoice-v3.5-flash\` | 快速 | 日常大批量 |
|
|
|
+| \`cosyvoice-v3-plus\` | 老款 | 兼容已有集成 |
|
|
|
+| \`cosyvoice-v3-flash\` | 快速 | **项目当前默认** |
|
|
|
+
|
|
|
+### 不同模型对指令的格式要求
|
|
|
+
|
|
|
+| 模型 | 声音复刻 / 设计音色 | 系统音色 |
|
|
|
+|------|--------------------|----------|
|
|
|
+| cosyvoice-v3.5-plus | 可输入任意指令(自由描述) | ❌ v3.5 不支持系统音色 |
|
|
|
+| cosyvoice-v3.5-flash | 可输入任意指令 | ❌ v3.5 不支持系统音色 |
|
|
|
+| cosyvoice-v3-plus | ❌ 不支持指令控制 | 指令必须固定格式(见 CosyVoice 音色列表) |
|
|
|
+| cosyvoice-v3-flash | 可输入任意指令 | 指令必须固定格式 |
|
|
|
+
|
|
|
+使用方式:通过 \`instruction\` 参数指定指令内容。
|
|
|
+
|
|
|
+### 指令支持的语言
|
|
|
+
|
|
|
+| 模型 | 声音复刻 | 系统音色 |
|
|
|
+|------|---------|----------|
|
|
|
+| v3.5-plus / v3.5-flash | 中 / 英 / 法 / 德 / 日 / 韩 / 俄 / 葡 / 泰 / 印尼 / 越南 | ❌ 不支持 |
|
|
|
+| v3-plus | 中 / 英 / 法 / 德 / 日 / 韩 / 俄 | 固定格式 |
|
|
|
+| v3-flash | 中 / 英 / 法 / 德 / 日 / 韩 / 俄 | 中文 |
|
|
|
+
|
|
|
+### 指令长度限制
|
|
|
+
|
|
|
+**不超过 100 字符**(按以下规则计数):
|
|
|
+- 汉字(简体 / 繁体 / 日文汉字 / 韩文汉字)**按 2 个字符**
|
|
|
+- 其他字符(标点 / 字母 / 数字 / 日韩假名 / 谚文等)按 1 个字符
|
|
|
+
|
|
|
+\`\`\`example
|
|
|
+"温柔知性的女性,30 岁左右,语调平和,适合有声书朗读"
|
|
|
+ 温柔=2 + 知性=2 + 的=1 + 女性=2 + ,=1 + 30=2 + 岁=1 + 左右=2 + ... ≈ 70 字符 ✅
|
|
|
+\`\`\`
|
|
|
+
|
|
|
+### 适用场景
|
|
|
+
|
|
|
+- 有声书和广播剧配音
|
|
|
+- 广告和宣传片配音
|
|
|
+- 游戏角色和动画配音
|
|
|
+- 情感化的智能语音助手
|
|
|
+- 纪录片和新闻播报
|
|
|
+
|
|
|
+### 如何编写高质量的声音描述
|
|
|
+
|
|
|
+#### 5 个核心原则
|
|
|
+
|
|
|
+1. **具体而非模糊** — 用"低沉 / 清脆 / 语速偏快"等具体特征,避免"好听 / 普通"
|
|
|
+2. **多维而非单一** — 组合"性别 + 年龄 + 情感 + 用途"等维度,只写"女声"太宽泛
|
|
|
+3. **客观而非主观** — 用"音调偏高,带有活力"代替"我最喜欢的声音"
|
|
|
+4. **原创而非模仿** — 描述声音特质,**不要**要求模仿特定人物(涉版权风险)
|
|
|
+5. **简洁而非冗余** — 每个词都有明确作用,避免重复修饰
|
|
|
+
|
|
|
+#### 7 个推荐描述维度
|
|
|
+
|
|
|
+| 维度 | 可选值 |
|
|
|
+|------|--------|
|
|
|
+| 性别 | 男性 / 女性 / 中性 |
|
|
|
+| 年龄 | 儿童(5-12) / 青少年(13-18) / 青年(19-35) / 中年(36-55) / 老年(55+) |
|
|
|
+| 音调 | 高音 / 中音 / 低音 / 偏高 / 偏低 |
|
|
|
+| 语速 | 快速 / 中速 / 缓慢 / 偏快 / 偏慢 |
|
|
|
+| 情感 | 开朗 / 沉稳 / 温柔 / 严肃 / 活泼 / 冷静 / 治愈 |
|
|
|
+| 特点 | 有磁性 / 清脆 / 沙哑 / 圆润 / 甜美 / 浑厚 / 有力 |
|
|
|
+| 用途 | 新闻播报 / 广告配音 / 有声书 / 动画角色 / 语音助手 / 纪录片 |
|
|
|
+
|
|
|
+#### 描述示例(从官方复制,微调措辞)
|
|
|
+
|
|
|
+1. **标准播音风格**:吐字清晰精准,字正腔圆
|
|
|
+2. **年轻活泼女性**:语速较快,带有明显的上扬语调,适合介绍时尚产品
|
|
|
+3. **沉稳中年男性**:语速缓慢,音色低沉有磁性,适合朗读新闻或纪录片解说
|
|
|
+4. **温柔知性女性**:30 岁左右,语调平和,适合有声书朗读
|
|
|
+5. **可爱儿童**:大约 8 岁女孩,说话略带稚气,适合动画角色配音
|
|
|
+
|
|
|
+### 项目内当前用法的指令格式
|
|
|
+
|
|
|
+代码 \`server/src/modules/tts/aliyun.provider.ts:103-105\` 给 Qwen-TTS Instruct 用的指令格式:
|
|
|
+\`\`\`ts
|
|
|
+if (params.speed !== 1) instructions.push(\`语速\${params.speed > 1 ? '较快' : '较慢'}\`);
|
|
|
+if (params.pitch !== 0) instructions.push(\`音调\${params.pitch > 0 ? '较高' : '较低'}\`);
|
|
|
+\`\`\`
|
|
|
+
|
|
|
+例如 speed=0.78 → \`"语速较慢"\`(符合 v3-flash 的指令规则,因为 speed 描述在系统音色固定格式内)。
|
|
|
+
|
|
|
+### 注意事项
|
|
|
+
|
|
|
+- **字数限制 100 字符很严**,所以\"语速较慢\"比\"语速稍微放缓一点\"更好(后者汉字太多可能超限)
|
|
|
+- **优先用声音特征描述(性别 + 年龄 + 音调)**,避免纯情绪词(\"治愈的\"),后者难以稳定生成
|
|
|
+- **不要混用语言**,指令要全中文(系统音色)或全英文/全日文(复刻音色)
|
|
|
+- **自定义音色的指令自由度更高**,可以实验长 prompt,但要测听感
|
|
|
+`;
|
|
|
+
|
|
|
const md = [];
|
|
|
md.push('# 阿里云百炼 TTS 文档');
|
|
|
md.push('');
|
|
|
@@ -190,4 +294,7 @@ md.push('');
|
|
|
md.push('A: 阿里云不会本地验证,直接发 HTTP 请求,服务端返回 400 或用默认音色(不会报错)。');
|
|
|
md.push('');
|
|
|
|
|
|
+// ========== 追加: CosyVoice 指令使用指南 ==========
|
|
|
+md.push(INSTRUCTION_GUIDE.trimStart());
|
|
|
+
|
|
|
process.stdout.write(md.join('\n'));
|
MyFramework User