CosyVoice模型调优

适用场景

• 品牌 / IP 形象的高还原度音色定制：已积累同一发音人（品牌代言人、虚拟主播、IP 形象等）的多条 / 数小时高质量录音，希望在单条音频复刻的基础上进一步抬高对该发音人的还原度上限。

• 长篇有声内容的稳定音色生产：有声书、播客、纪录片解说、企业培训课件等场景，需要在数十小时合成中保持音色、语气与节奏稳定，且对该发音人已有充足的录音素材。

调优规格

• 支持的调优方式：SFT 高效微调（efficient_sft），暂不支持 CPT、DPO 等其他训练方式。

• 支持调优的模型：cosyvoice-v3-flash。

• 支持的地域：CosyVoice 模型调优服务仅支持华北2（北京）地域。

调优产物

调优产物是一个独立部署的新模型，而不是基础模型下的音色 ID；该模型仅承载训练习得的单一音色，调用时 voice 参数必须固定为 default，无法切换至其他音色。

能力边界

以下能力由基础模型 cosyvoice-v3-flash 决定，无法通过调优新增、扩展或改变：

• 语种支持：训练数据语种必须为基础模型已支持的语种。使用基础模型不支持的语种（例如保加利亚语）训练，模型仍无法合成该语种的语音。

• 请求级控制接口：调优产物支持 SSML 与 LaTeX（请求中精细控制语速、语调、停顿、音量、发音等）与 LaTeX（数学公式朗读），不支持指令控制功能，调用时不可传入 instruction 参数。

• 声音复刻 / 声音设计：调优产物为单音色独立模型（voice="default" 锁死），不再提供声音复刻、声音设计能力。如需创建新的音色 ID，请使用基础模型的声音复刻或声音设计。

训练费用

按训练消耗的 Token 数计费，单价为 0.2 元 / 千 Tokens。

单次任务的 Token 消耗按下式估算：

$$\text{消耗 Tokens}=(lm\_max\_epoch+fm\_max\_epoch)\times 25\times \text{训练集总时长(秒)}$$

其中 lm_max_epoch 与 fm_max_epoch 为超参数中设置的 LM 与 FM 训练轮次；训练集总时长为调优数据集中全部音频文件的总秒数。提高任一轮次或扩大训练集均会线性增加 Token 消耗。

部署费用

调优后的模型部署后按模型单元的使用时长计费，公式为：$$\text{费用}=\text{使用时长（小时）}\times \text{模型单元数量}\times \text{模型单元单价}$$。

其中，$$\text{模型单元数量}=\text{单副本模型单元}\times \text{部署副本数}$$，可选的模版及对应的模型单元类型参见部署模版；各模型单元类型的单价、计费起止时刻请参见模型部署。

音频规格要求

目录结构

将训练样本组织为以下目录结构，并将整个目录打包为 .zip 压缩包后上传：

user_data/
├── data.jsonl           # 训练样本列表（必需）
└── train/               # 训练音频目录（所有训练 wav 放在这里）
    ├── 100001.wav
    ├── 100002.wav
    └── ...

data.jsonl 格式

data.jsonl 文件每行一个训练样本：

{"wav_fn": "train/100001.wav", "text": "你好。"}
{"wav_fn": "train/100002.wav", "text": "我明白了。"}

字段说明

文本写法建议：

• 无需归一化：数字、英文 / 中文混排、标点符号等无需做特殊归一化处理，按音频中的自然念法书写即可。

• 去除特殊符号：建议提前去除文本中不发音的特殊符号（如 emoji、装饰符号、控制字符等），仅保留与音频实际发音对应的内容。

• 禁止包含标记语言：text 字段必须为纯文本，不得包含 SSML 标签、LaTeX 公式、指令控制语句或情感标注；调优阶段不解析这些标记，写入只会作为字符序列被错误地学进文本到语音的映射。请求级标记语言（SSML / LaTeX）应在调用调优产物时使用；调优产物对各请求级控制接口的支持范围详见能力边界中的请求级控制接口条目。

数据量建议

• 推荐数据量：训练音频总时长在 1~10 小时 之间即可获得较好效果，超过 10 小时收益不明显。

• 样本条数：建议训练音频不少于 150 条，以保证调优效果稳定；算法侧与平台侧对 data.jsonl 内的样本条数均无明确上限，可按总时长目标自由组织。

超参数说明

CosyVoice 调优涉及两个子网络：LM（Language Model，将文本转为离散语音 token 的自回归语言模型，对韵律影响较大）与 FM（Flow Matching，将语音 token 还原为 Mel 谱的流匹配模型，对音色还原度影响较大），两者已解耦、可独立调整，训练超参分别以 lm_* 与 fm_* 前缀区分。超参数决定训练轮次与 Checkpoint 保存策略，直接影响调优耗时、Token 消耗与最终模型效果。

建议先用以下推荐值跑通一次完整流程，根据效果再决定是否调整：

• LM 网络：lm_max_epoch=60，lm_step=5，lm_num=3，lm_batch_size=1000。

• FM 网络：fm_max_epoch=100，fm_step=10，fm_num=3，fm_batch_size=2000。

其中 *_max_epoch 为训练总轮次，*_step 为保存 Checkpoint 的步长，*_num 为最多保留的 Checkpoint 个数，*_batch_size 为训练批次大小。各字段的完整取值范围请参见 CosyVoice 语音合成模型 hyper_parameters。

实测对照：以下为一次实操样本数据，便于您在开工前对耗时与费用建立预期，实际数值随数据量、超参与队列等待时间不同而变化。

模型产出（Checkpoint）

单次调优任务可能产出多个 Checkpoint（候选模型，可通过列举 Checkpoint接口查看），具体数量与排序由超参数中的 lm_num、fm_num 与 *_step 共同决定。

1. 选模型：分别从 LM、FM 的最大轮次往回数，每隔 *_step 选一个，共选 *_num 个。

2. 组合：LM 与 FM 的选择做全排列，候选 Checkpoint 数量 = lm_num × fm_num。

3. 排序：按 LM 轮次 × FM 轮次 从大到小排序（乘积越大代表双端训练越充分，越靠前）。

4. 截断：在上一步降序排序结果上从前往后截取，最多保留 10 个；候选不足 10 个时全部输出。

5. 命名：checkpoint-{LM 轮次 4 位补零}{FM 轮次 4 位补零}，例如 LM 4 / FM 4 输出为 checkpoint-00040004。

示例：以参数 lm_max_epoch=4, lm_step=1, lm_num=2, fm_max_epoch=4, fm_step=2, fm_num=2 为例：

• LM 选出：4、3（从 4 开始，每次减 lm_step=1，共 lm_num=2 个）。

• FM 选出：4、2（从 4 开始，每次减 fm_step=2，共 fm_num=2 个）。

• 全排列得到 4 个候选，按乘积降序输出：

查询任务详情

使用创建任务时返回的 job_id 查询任务状态。

curl --location 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

响应中 output.status 字段表示当前阶段：PENDING（待开始）→ QUEUING（排队中，平台同一时刻仅运行一个训练任务）→ RUNNING（训练进行中）→ SUCCEEDED（训练成功）。异常终止状态包括 FAILED（训练失败）、CANCELING（取消中）与 CANCELED（已取消）。状态字段的完整定义请参见查询调优任务详情。

获取训练日志

当任务长时间停留在某一状态、或进入 FAILED 状态时，可拉取训练日志辅助排查。

curl --location 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>/logs?offset=0&line=1000' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

通过 offset 控制起始位置，line 控制最多返回的行数（示例每次拉取 1000 行）。响应字段说明请参见查询调优日志。

部署模版

模型单元（Model Unit，MU）是阿里云百炼平台衡量推理算力的最小单位，不同模型单元类型对应不同的算力与单价；单副本模型单元则表示部署一个副本所占用的模型单元个数。部署费用直接由实际占用的模型单元数量决定。

部署模版：预置了一组部署规格（包括模型单元类型与单副本模型单元），定义了单个副本所占用的算力资源；选择不同模版，意味着选择不同的推理性能与单位成本组合。下表模型单元类型列中的 V/II 为模型单元规格的罗马数字标识，对应 API 响应中 model_unit_spec 字段的 MU5/MU2。CosyVoice 调优模型当前提供以下两种部署模版：

计费方式：部署费用与模型单元数量（即总模型单元）直接相关，按以下公式计算：$$\text{模型单元数量}=\text{单副本模型单元}\times \text{部署副本数}$$。

因此选择不同模版、设置不同副本数都会直接改变计费金额，请在部署前结合业务负载与预算评估。完整费用公式与各模型单元类型的单价，请参见部署费用。

方式一：通过控制台部署（推荐日常使用）

操作入口：前往阿里云百炼控制台的我的模型页面，找到调优成功的模型并提交部署。完整操作步骤请参见模型部署。

关键参数：仅需选择以下两项，其余字段由模版与副本数自动决定：

• 部署模版：从 单机部署、单机部署-旗舰级复杂推理 中二选一，二者区别见部署模版。

• 部署副本数：实例个数，按业务并发吞吐需求设置（≥ 1 的整数）。

完成后状态：控制台展示部署实例 ID 及状态变化（PENDING → DEPLOYING → RUNNING），状态变为 RUNNING 即可调用。

方式二：通过 API 部署（推荐自动化集成）

API 部署需按以下顺序调用三个接口；各字段完整的取值约束请参见模型部署。

1. 查询可部署的模型（GET /api/v1/deployments/models）：获取后续创建部署所需的 model_name、template_id 与 capacity_unit_per_instance：

   curl 'https://dashscope.aliyuncs.com/api/v1/deployments/models?page_no=1&page_size=100&version=v1.0&model_source=custom' \
       --header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
       --header 'Content-Type: application/json'

   响应样例（节选关键字段）：

   {
     "output": {
       "models": [
         {
           "model_name": "cosyvoice-v3-flash-ft-202605271743-dd2a",
           "plans": [
             {
               "plan": "mu",
               "templates": [
                 {
                   "template_name": "单机部署",
                   "template_id": "dps-20260521172224-1vabse",
                   "template_desc": "高性价比部署方案，...",
                   "roles": {
                     "unified": {
                       "model_unit_spec": "MU5",
                       "capacity_unit_per_instance": 1
                     }
                   }
                 },
                 {
                   "template_name": "单机部署-旗舰级复杂推理",
                   "template_id": "MU2",
                   "template_desc": "高复杂负载，超大模型 + 长上下文。",
                   "roles": {
                     "unified": {
                       "model_unit_spec": "MU2",
                       "capacity_unit_per_instance": 8
                     }
                   }
                 }
               ]
             }
           ]
         }
       ]
     }
   }

   定位本次要部署的模型：响应中 output.models 为所有可部署模型的列表，从中找到 model_name 等于创建调优任务返回的 finetuned_output 的那条记录，其下的 plans[].templates 即该模型可用的部署模版列表。

2. 创建部署任务（POST /api/v1/deployments）：使用上一步获取的参数提交部署请求。下方示例选用 单机部署 模版，部署 1 个副本：

   curl --location 'https://dashscope.aliyuncs.com/api/v1/deployments' \
   --header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
   --header 'Content-Type: application/json' \
   --data '{
       "model_name": "<MODEL_NAME>",
       "plan": "mu",
       "deploy_spec": "<TEMPLATE_ID>",
       "capacity": 1,
       "billing_method": "POST_PAY"
   }'

   请求结果：响应中 output.deployed_model 即为部署实例 ID，后续调用模型时需将其作为 model 参数传入。

   关键参数（占位符 <MODEL_NAME>、<TEMPLATE_ID> 均取自上一步响应）：

   • model_name：填写上一步响应中匹配 finetuned_output 的那条记录的 model_name。

   • plan：当前固定为 "mu"（按模型单元的使用时长计费）。

   • deploy_spec：填写上一步响应中所选模版的 template_id，例如 单机部署 当前为 dps-20260521172224-1vabse、单机部署-旗舰级复杂推理 为 MU2。请始终以上一步的实时返回值为准，不要硬编码。

   • capacity：本次部署占用的总模型单元数量，与计费直接挂钩。取值必须是上一步中 capacity_unit_per_instance 的整数倍；$$\text{实际部署的副本数}=\frac{capacity}{capacity\_unit\_per\_instance}$$。

     取值示例：

     • 单机部署（capacity_unit_per_instance = 1）：capacity=1 → 1 个副本；capacity=4 → 4 个副本。

     • 单机部署-旗舰级复杂推理（capacity_unit_per_instance = 8）：capacity=8 → 1 个副本；capacity=16 → 2 个副本；capacity=1 会被拒绝（不是 8 的整数倍）。

   • billing_method：当前支持 "POST_PAY"（后付费）。

   API 字段与控制台部署页面的对应关系：

   API 字段	控制台对应
   model_name	在我的模型页面选定的调优模型
   deploy_spec	在 部署模版 处选择 单机部署 或 单机部署-旗舰级复杂推理
   capacity	总模型单元（控制台按$$\text{总模型单元}=\text{单副本模型单元}\times \text{部署副本数}$$自动计算并展示）

   plan、billing_method 在控制台无对应字段（控制台部署默认即按模型单元用时计费的后付费方式）。

   重要

   capacity 不是部署副本数，而是总模型单元数量；提交前请按上方公式与示例核对。

3. 查询部署状态（GET /api/v1/deployments/<deployed_model>）：部署任务将经历 PENDING → DEPLOYING → RUNNING 多个阶段，可调用以下接口轮询状态：

   curl --location 'https://dashscope.aliyuncs.com/api/v1/deployments/<替换为 deployed_model 字段值>' \
   --header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
   --header 'Content-Type: application/json'

   当响应中 status 字段值为 RUNNING 时，表示该模型已可供调用。更多模型部署相关的操作（如扩缩容、下线等）请参见模型部署。

调用观测与问题定位

每一次调用都建议落入业务日志，以便事后追溯异常请求与诊断性能问题。重点采集以下三类信息：

• 请求 ID（request_id）：WebSocket SDK 通过 synthesizer.get_last_request_id() 获取（参见前文 实时（Python WebSocket） 示例）；HTTP 调用方式下的获取位置请参考语音合成。排查异常或回溯问题时请始终保留该 ID。

• 首包延迟：WebSocket SDK 通过 synthesizer.get_first_package_delay() 获取首个音频包到达时延（毫秒），是衡量实时合成体感的核心指标，前文 实时（Python WebSocket） 示例代码已演示其打印用法。

• 错误码与错误信息：错误响应中的 code、message 字段用于区分鉴权失败、配额耗尽、模型未就绪、文本超限等不同失败原因，建议按错误码分别设置告警与排查路径。

采集字段对照（建议入库的最小集合）：

建议在业务日志中将 request_id 与业务侧请求 ID 关联存储，并保留至少与 SLA 一致的时间窗口，以便后续核查。

选用更优的 Checkpoint

默认部署的 finetuned_output 仅对应模型产出（Checkpoint）中排序最靠前的 Checkpoint，但该 Checkpoint 不一定是主观听感最佳。正式上线前建议人工评测排序前 2~3 名的 Checkpoint，从中挑选最贴近目标音色的版本。

切换部署到其他 Checkpoint 的步骤：

1. 通过 GET /api/v1/fine-tunes/{job_id}/checkpoints 拉取本次任务全部 Checkpoint，从响应 output[*].model_name 字段获取每个 Checkpoint 对应的模型 ID（仅在 status=SUCCEEDED 时返回）。完整字段说明请参见查询调优任务 Checkpoint 列表。

2. 将选中的 model_name 作为方式二：通过 API 部署（推荐自动化集成）中“创建部署任务”步骤的入参，得到独立的 deployed_model。不同 Checkpoint 必须使用各自独立的部署实例，无法在已有部署上原地切换底层模型。

3. 同一时间存在多个评测部署会按各自占用的模型单元数量累加计费，请参考部署费用预估并发评测成本，对比完成后及时下线落选实例（参见及时下线不再使用的部署）。

及时下线不再使用的部署

在以下场景中，部署实例不再承载业务流量，应立即下线以停止计费：完成多 Checkpoint 评测后落选的实例、被新版本替换的旧实例、临时压测或验证使用的实例、创建失败需要重建的实例等。

下线方法：调用 DELETE /api/v1/deployments/{deployed_model}，响应中 output.status 变为 DELETING 即表示受理。完整字段说明请参见删除部署。

副本数规划与扩缩容

当业务并发上量、整体吞吐不足或活动期需要弹性扩容时，需要调整部署的副本数。不同部署模版（单机部署 与 单机部署-旗舰级复杂推理）对应的单副本算力与适用场景不同，详见部署模版，请结合业务并发反推副本数。

扩缩容方法：调用 PUT /api/v1/deployments/{deployed_model}/scale，请求体传入新的 capacity。注意 capacity 是总模型单元数量而非副本数，且必须为该模版 capacity_unit_per_instance 的整数倍，取值示例参见取值示例。完整字段说明请参见部署扩缩容。

副本数线性影响计费金额，扩容前请按部署费用的公式估算成本变化。

重新调优后的版本切换

当补充新数据或调整超参时，推荐始终从基础模型 cosyvoice-v3-flash 重新训练，不建议在已调优产物上做增量训练。重新调优产出的是新的 finetuned_output，不是同一模型的新版本，必须创建新的部署实例，无法在旧 deployed_model 上原地替换底层模型。

推荐切换流程：

1. 用新模型 model_name 走方式二：通过 API 部署（推荐自动化集成），创建独立部署，得到新的 deployed_model。不要直接对旧实例做扩缩容或修改设置，这两种操作都不会更换其底层模型。

2. 业务侧通过灰度或影子流量并行调用新旧两个 deployed_model，对比音质、首包延迟与错误率。

3. 验证通过后切流量到新部署，再下线旧部署（参见及时下线不再使用的部署），完成版本替换。