创建调优任务

创建一个新的模型微调训练任务。

Windows CMD 请将${DASHSCOPE_API_KEY}替换为%DASHSCOPE_API_KEY%，PowerShell请替换为 $env:DASHSCOPE_API_KEY

curl --location --request POST "https://dashscope-intl.aliyuncs.com/api/v1/fine-tunes" \
      --header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
      --header 'Content-Type: application/json' \
      --data '{
          "model":"qwen3-14b",
          "training_file_ids":[
              "86a9fe7f-dd77-43b0-9834-2170e12339ec",
              "03ead352-6190-4328-8016-61821c23d4fc"
          ],
          "hyper_parameters":{
              "n_epochs":3,
              "batch_size":32,
              "max_length":8192,
              "learning_rate":"1.6e-5",
              "lr_scheduler_type":"linear",
              "split":0.9
          },
          "training_type":"sft",
          "finetuned_output_suffix":"suffix"
      }'

输入参数

字段	必选	类型	传参方式	参数说明
training_file_ids	是	Array	Body	调优集文件ID列表，文件ID由文件管理 API 产生。
validation_file_ids	否	Array	Body	测试集文件ID列表，文件ID由文件管理 API 产生。
model	是	String	Body	用于调优的基础模型 ID；或其他调优任务产出的模型ID（对已经调优了的模型进行再次调优）。
hyper_parameters	否	Map	Body	调优时的超参列表。不同模型支持的参数集合及其默认值不同，请在控制台选择相同的模型和调优方式查看实际默认值。文本生成 / 视觉理解等模型：使用 `n_epochs`（循环次数）、`batch_size`（批次大小）、`max_length`（序列长度）等参数，其中 `n_epochs`、`batch_size`、`max_length` 影响调优费用，必须填写。各参数详情请参见 hyper_parameters 参数说明。 CosyVoice 语音合成模型（仅 `cosyvoice-v3-flash`）：8 个 LM / FM 超参全部必填。各参数详情请参见下方「CosyVoice 语音合成模型 hyper_parameters」。
training_type	否	String	Body	调优方法，可选值为：`sft`、`efficient_sft`。
job_name	否	String	Body	调优任务名称
model_name	否	String	Body	调优完成后的模型名称

`hyper_parameters`内支持的设置

参数名称	默认设置	推荐设置	类型	超参作用
`n_epochs` （循环次数）	1	结合调优效果调整	Integer	模型遍历训练的次数，请根据模型调优实际使用经验进行调整。模型训练循环次数越多，训练时间越长，训练费用越高。
`learning_rate` （学习率）	`sft`: 1e-5 量级 `efficient_sft`:1e-4 量级具体数值随模型选择变化。	使用百炼推荐的默认值	Float	控制模型修正权重的强度。学习率设置得太高，模型参数会剧烈变化，导致调优后的模型表现不一定更好，甚至变差；学习率太低，调优后的模型表现不会有太大变化。
`freeze_vit` （是否冻结视觉主干网络）	true	根据需求调整	Boolean	用于冻结视觉主干网络的参数，使其在训练过程中不更新权重。仅适用于千问-VL（视觉理解）模型。
`batch_size` （批次大小）	具体数值随模型选择变化。模型越大，默认 batch_size 越小。	使用百炼推荐的默认值	Integer	一次性送入模型进行训练的数据条数，参数过小会显著延长训练时间，推荐使用默认值。
`eval_steps` （验证步数）	50	根据需求调整	Integer	训练阶段针对模型的验证间隔步长，用于阶段性评估模型训练准确率、训练损失。该参数影响模型调优进行时的 Validation Loss 和 Validation Token Accuracy 的显示频率。
`logging_steps` （日志显示步数）	5	根据需求调整	Integer	调优日志打印的步数。
`lr_scheduler_type` （学习率调整策略）	`cosine`	推荐`linear`/`Inverse_sqrt`	String	在模型训练中动态调整学习率的策略。支持设置为：
`max_length` （序列长度）	2048	8192	Integer	指的是单条训练数据 token 支持的最大长度。如果单条数据 token 长度超过设定值，调优会直接丢弃该条数据，不进行训练。
`max_split_val_dataset_sample` （验证集数据最大数量）	1000	使用百炼推荐的默认值	Integer	当不设置`"validation_file_ids"`时，阿里云百炼自动分割的验证集最多只有1000条。当设置了`"validation_file_ids"`时，该参数无效。
`split` （训练集在训练文件中占比）	0.8	使用百炼推荐的默认值	Float	当不设置`"validation_file_ids"`时，阿里云百炼会自动把训练文件中的80%作为训练集，20%作为验证集。当设置了`"validation_file_ids"`时，该参数无效。
`warmup_ratio` （学习率预热比例）	0.05	使用百炼推荐的默认值	Float	学习率预热占用总的训练过程的比例。学习率预热是指学习率在训练开始后由一个较小值线性递增至学习率设定值。该参数主要是限制模型参数在训练初始阶段的变化幅度，从而帮助模型更稳定地进行训练。比例过大效果与过低的学习率相同，会导致调优后的模型表现不会有太大变化。比例过小效果与过高的学习率相同，可能导致调优后的模型表现不一定更好，甚至变差。该参数仅对学习率调整策略“Constant”无效。
`weight_decay` （权重衰减）	0.1	使用百炼推荐的默认值	Float	L2正则化强度。L2正则化能在一定程度上保持模型的通用能力。数值过大会导致模型调优效果不明显。
高效微调（支持`efficient_sft`）参数说明当对一个已经高效微调后的模型进行二次高效微调时，`lora_rank`、`lora_alpha`、`lora_dropout`三个参数必须保持一致。
`lora_rank` （LoRA秩值）	8	64	Integer	LoRA训练中的低秩矩阵的秩大小。秩越大调优效果越好，但训练会略慢。
`lora_alpha` （LoRA阿尔法）	32	使用百炼推荐的默认值	Integer	用于控制原模型权重与LoRA的低秩修正项之间的结合缩放系数。较大的Alpha值会给予LoRA修正项更多权重，使得模型更加依赖于微调任务的特定信息；而较小的Alpha值则会让模型更倾向于保留原始预训练模型的知识。
`lora_dropout` （LoRA丢弃率）	0.1	使用百炼推荐的默认值	Float	LoRA训练中的低秩矩阵值的丢弃率。使用推荐数值能增强模型通用化能力。数值过大会导致模型微调效果不明显。
模型参数快照发布参数
`save_strategy` （快照存储策略）	`epoch`	可以设置为 `epoch`或`steps`。设置为`steps`时，可以通过设置`save_steps`参数，调整保存间隔。	String	设置调优过程中，保存模型参数快照（Checkpoint）的保存间隔和保存数量上限。
`save_steps` （存储步数）	50	如果需要手动修改，建议设置为`eval_steps`参数的整数倍。	Integer	设置每训练多少步保存一次模型参数快照（Checkpoint）。
`save_total_limit` （快照存储数量上限）	1	10	Integer	限制最多保存多少个模型参数快照（Checkpoint）用于导出。

CosyVoice 语音合成模型 hyper_parameters

仅适用于 cosyvoice-v3-flash 模型，与文本生成模型的 n_epochs、batch_size、max_length 不可混用。

参数	必选	推荐	取值范围	说明
lm_max_epoch	是	60	[1, 2147483647]	LM 调优轮次（epoch 数）。
lm_step	是	5	[1, 2147483647]	LM 保存 checkpoint 的步长（每多少个 epoch 保存一次）。
lm_num	是	3	[1, 2147483647]	LM 保留的 checkpoint 数量上限。
lm_batch_size	是	1000	[1, 2147483647]	LM 批次大小（batch size）。
fm_max_epoch	是	100	[1, 2147483647]	FM 调优轮次（epoch 数）。
fm_step	是	10	[1, 2147483647]	FM 保存 checkpoint 的步长（每多少个 epoch 保存一次）。
fm_num	是	3	[1, 2147483647]	FM 保留的 checkpoint 数量上限。
fm_batch_size	是	2000	[1, 2147483647]	FM 批次大小（batch size）。

返回样例

{
          "request_id": "9654e55a-d74b-4113-aee1-fa19c9384fcc",
          "output": {
              "job_id": "ft-202410291653-1c7f",
              "job_name": "ft-202410291653-1c7f",
              "status": "PENDING",
              "model": "qwen3-14b",
              "base_model": "qwen3-14b",
              "training_file_ids": [
                  "976bd01a-f30b-4414-86fd-50c54486e3ef"
              ],
              "validation_file_ids": [
      
              ],
              "hyper_parameters": {
                  "n_epochs": 3,
                  "batch_size": 32,
                  "max_length": 8192,
                  "learning_rate": "1.6e-5",
                  "lr_scheduler_type": "linear",
                  "split": 0.9
              },
              "training_type": "sft",
              "create_time": "2024-10-29 16:53:53",
              "workspace_id":"llm-v71tlv***",
              "user_identity": "1396993924585947",
              "modifier": "1396993924585947",
              "creator": "1396993924585947",
              "group": "llm"
          }
      }

返回参数

参数名称	类型	参数说明
request_id	String	本次请求的ID。
output	Object	本次调优任务的详细信息。
output.job_id	String	本次调优的任务ID，可用于查询训练任务详情、查询训练日志、取消训练任务、删除训练任务等接口。生成规则：`ft-{yyyyMMddHHmm}-{4位uuid}`。
output.jobs_name	String	同`output.job_id`。
output.status	String	本次调优任务的状态。
output.model	String	调优任务使用的模型ID。
output.base_model	String	调优任务使用的模型对应的基础模型ID。比如：调优任务`ft-202410291653-1c7f`使用的基础模型是`qwen3-14b`。
output.training_file_ids	Array	调优文件ID列表。
output.validation_file_ids	Array	验证文件ID列表。
output.hyper_parameters	Object	显性声明过的超参表。
output.training_type	String	调优方法。
output.create_time	String	调优任务创建时间。
output.workspace_id	String	调优任务所属的业务空间ID。
output.user_identity	String	该调优任务隶属的主账号UID。
output.modifier	String	对该调优任务进行最后一次操作的账号UID。比如：某个子账号取消了该任务，该子账号UID会显示在这里。
output.creator	String	该调优任务创建人UID。
output.group	String	模型调优的任务类型。

任务状态	含义
PENDING	调优待开始。
QUEUING	调优正在排队（同时只有一个调优任务可以进行）
RUNNING	调优正在进行中。
CANCELING	调优正在取消中。
SUCCEEDED	调优成功。
FAILED	调优失败。
CANCELED	调优已经取消。

请求错误码说明

请求异常时返回

字段	类型	描述	示例值
code	String	错误码。	NotFound
request_id	String	本次请求的系统唯一码。	6332fb02-3111-43f0-bf79-f9e8c5ffa7f9
message	String	错误信息。	Not Found!

请求异常示例

{
        "code": "NotFound",
        "request_id": "BE213CDD-8A5C-59EE-9A67-055EAB0CB59B",
        "message": "Not Found!"
      }

错误码列表

HTTP状态码	错误码	错误信息举例	含义	处理方式
400	InvalidParameter	Missing training files	参数错误，缺少参数或者参数格式问题等。	根据错误信息，修正您的参数。
400	UnsupportedOperation	The fine-tune job can not be deleted because it is succeeded,failed or canceled	当资源处于特定状态时，无法对其进行操作。	待要操作的资源到达可操作状态时再进行操作。
404	NotFound	Not found!	要查询/操作的资源不存在。	检查要查询/操作的资源ID是否错误。
409	Conflict	Model instance xxxxx already exists, please specify a suffix	已存在deployed_model名为xxxxx的部署实例，需要指定后缀进行区分。	为部署指定唯一的后缀。
429	Throttling	Too many fine-tune job in running, please retry later. Only 20 fine-tune job in running or succeeded allowed per user.	资源的创建触发平台限制。	删除不再使用的模型。
500	InternalError	Internal server error!	内部错误。	记录 request_id，通过工单联系阿里云工程师进行排查。

创建调优任务

输入参数

hyper_parameters内支持的设置

返回样例

返回参数

请求错误码说明

`hyper_parameters`内支持的设置