创建调优任务-大模型服务平台百炼(Model Studio)-阿里云帮助中心

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

创建调优任务

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

文本生成模型

curl --location --request POST "https://dashscope.aliyuncs.com/api/v1/fine-tunes" \
      --header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
      --header 'Content-Type: application/json' \
      --data '{
          "model":"qwen3-14b",
          "training_datasets":[
              {
                  "data_source_type":"file_id",
                  "file_id":"86a9fe7f-dd77-43b0-9834-2170e12339ec"
              },
              {
                  "data_source_type":"oss_mount",
                  "mount_storage":{
                      "region":"cn-beijing",
                      "bucket":"example_bucket",
                      "file_path":"dataset/data.jsonl"
                  }
              }
          ],
          "validation_datasets":[
              {
                  "data_source_type":"file_id",
                  "file_id":"03ead352-6190-4328-8016-61821c23d4fc"
              },
              {
                  "data_source_type":"oss_mount",
                  "mount_storage":{
                      "region":"cn-beijing",
                      "bucket":"example_bucket",
                      "file_path":"dataset/val.jsonl"
                  }
              }
          ],
          "hyper_parameters":{
              "n_epochs":1,
              "learning_rate":"1.6e-5",
              "batch_size":32,
              "split":0.8
          },
          "training_type":"sft",
          "finetuned_output_suffix":"suffix"
      }'

图像生成模型

curl --location 'https://dashscope.aliyuncs.com/api/v1/fine-tunes' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.7-image-pro",
    "training_datasets": [
        {
            "data_source_type": "file_id",
            "file_id": "<替换为训练数据集的文件id>"
        },
        {
            "data_source_type": "oss_mount",
            "mount_storage": {
                "region": "cn-beijing",
                "bucket": "example_bucket",
                "file_path": "dataset/data.jsonl"
            }
        }
    ],
    "validation_datasets": [
        {
            "data_source_type": "file_id",
            "file_id": "<替换为验证数据集的文件id>"
        },
        {
            "data_source_type": "oss_mount",
            "mount_storage": {
                "region": "cn-beijing",
                "bucket": "example_bucket",
                "file_path": "dataset/val.jsonl"
            }
        }
    ],
    "training_type": "efficient_sft",
    "hyper_parameters": {
        "learning_rate": 3e-5,
        "max_steps": 800,
        "eval_steps": 200,
        "max_token_length": "1k",
        "gradient_clip": 0.5,
        "weight_decay": 0.02,
        "max_pixels": "1k",
        "val_img_size": "1k",
        "generation_type": "t2i",
        "lora_rank": 32,
        "save_total_limit": 10
    }
}'

视频生成模型

curl --location 'https://dashscope.aliyuncs.com/api/v1/fine-tunes' \
--header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.5-i2v-preview",
    "training_datasets": [
        {
            "data_source_type": "file_id",
            "file_id": "<替换为训练数据集的文件id>"
        },
        {
            "data_source_type": "oss_mount",
            "mount_storage": {
                "region": "cn-beijing",
                "bucket": "example_bucket",
                "file_path": "dataset/data.jsonl"
            }
        }
    ],
    "training_type": "efficient_sft",
    "hyper_parameters": {
        "n_epochs": 400,
        "batch_size": 2,
        "learning_rate": 2e-5,
        "split": 0.9,
        "max_split_val_dataset_sample": 5,
        "eval_epochs": 50,
        "max_pixels": 36864,
        "save_total_limit": 10,
        "lora_rank": 32,
        "lora_alpha": 32
    }
}'

输入参数

字段	必选	类型	传参方式	参数说明
training_datasets	是	Array of Dataset	Body	训练集文件列表。
validation_datasets	否	Array of Dataset	Body	测试集文件列表。
model	是	String	Body	用于调优的基础模型ID基础模型 ID；或其他调优任务产出的模型ID（对已经调优了的模型进行再次调优）。视频/图像生成模型支持以下 model 值：图生视频-基于首帧：`wan2.5-i2v-preview`、`wan2.2-i2v-flash` 图生视频-基于首尾帧：`wan2.2-kf2v-flash` 图像生成（文生图/图生图）：`wan2.7-image-pro`、`wan2.7-image`
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	调优方法，可选值为：`cpt`、`sft`、`efficient_sft`、`dpo_full`、`dpo_lora`。视频/图像生成模型仅支持 `efficient_sft`（LoRA 高效微调）。
job_name	否	String	Body	调优任务名称
model_name	否	String	Body	调优完成后的模型名称

Dataset 结构

字段	必选	类型	参数说明
data_source_type	是	String	数据源类型，可选值： `oss_mount`（挂载 OSS 文件） `file_id`（由文件管理服务 API 上传的文件）
mount_storage	否	OSS 挂载结构	数据源类型为 `oss_mount` 时必填。挂载文件信息。
file_id	否	String	数据源类型为 `file_id` 时必填。文件 ID，由文件管理服务 API 产生。

OSS 挂载结构

字段	必选	类型	参数说明
region	是	String	要挂载的 OSS Bucket 所属地域。支持北京（cn-beijing）和新加坡（ap-southeast-1）。
bucket	是	String	要挂载的 OSS Bucket 名称。
file_path	是	String	要挂载的 OSS 文件路径（object key）。对包含多个文件的数据集，使用其 data.jsonl 的文件路径。与使用 file_id 的方式不同，需要将未经压缩的数据集文件夹整体上传到 OSS，不支持 zip 文件。

hyper_parameters 参数说明

文本生成（千问）

不同模型支持的参数及其默认值不同，请前往控制台选择相同的模型和训练方式查看实际默认值。

参数名称

推荐设置

类型

超参作用

n_epochs

（循环次数）【必填】

数据量 < 10,000, 3~5次

数据量 > 10,000, 1~2次

Integer

模型遍历训练的次数，请根据模型调优实际使用经验进行调整。

模型训练循环次数越多，训练时间越长，训练费用越高。

learning_rate

（学习率）

使用百炼推荐的默认值

Float

控制模型修正权重的强度。

学习率设置得太高，模型参数会剧烈变化，导致调优后的模型表现不一定更好，甚至变差；
学习率太低，调优后的模型表现不会有太大变化。

freeze_vit

（是否冻结视觉主干网络）

根据需求调整

Boolean

用于冻结视觉主干网络的参数，使其在训练过程中不更新权重。仅适用于千问-VL（视觉理解）模型。

警告

只有 freeze_vit 设置为“true”时，模型才能进行按 Token 用量计费。

batch_size

（批次大小）【必填】

使用百炼推荐的默认值

Integer

一次性送入模型进行训练的数据条数，参数过小会显著延长训练时间。不同模型的默认值不同，请前往控制台查看。

eval_steps

（验证步数）

根据需求调整

Integer

训练阶段针对模型的验证间隔步长，用于阶段性评估模型训练准确率、训练损失。

该参数影响模型调优进行时的 Validation Loss 和 Validation Token Accuracy 的显示频率。

logging_steps

（日志显示步数）

根据需求调整

Integer

调优日志打印的步数。

lr_scheduler_type

（学习率调整策略）

语音合成模型（CosyVoice）

仅适用于 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）。

说明

CosyVoice 调优当前仅支持 training_type 为 efficient_sft。完整请求示例与端到端流程参见用户指南CosyVoice模型调优。

视频生成（万相）

仅适用于视频生成模型（wan 系列）。若模型效果不佳或训练不收敛，可以尝试调整 n_epochs 或 learning_rate。建议总训练步数不少于 800 步。

字段	类型	必选	描述	推荐值
batch_size	int	是	批次大小。一次性送入模型进行训练的数据条数。 wan2.5-i2v-preview：推荐为 2。 wan2.2-i2v-flash：推荐为 4。 wan2.2-kf2v-flash：推荐为 4。	以模型为准
n_epochs	int	是	训练循环次数。steps = n_epochs × ⌈数据集大小 / batch_size⌉。建议总步数 ≥ 800。例如：数据集 5 条，batch_size=2，每轮步数=⌈5/2⌉=3，最小 n_epochs = 800/3 ≈ 267。	400
learning_rate	float	是	学习率。控制模型权重更新幅度。过高可能导致模型变差，过低则变化不明显。	2e-5
eval_epochs	int	是	验证间隔。取值需 ≥ `n_epochs/10`。每隔多少个 epoch 进行一次验证评估并保存 Checkpoint。	50
max_pixels	int	是	训练视频的最大分辨率（像素总数 = 宽×高）。系统仅对超过该值的视频进行缩放处理。 wan2.5-i2v-preview：推荐 36864。范围 16384～36864。 wan2.2-i2v-flash：推荐 262144。范围 65536～262144。 wan2.2-kf2v-flash：推荐 262144。范围 65536～262144。	以模型为准
split	float	否	训练集划分比例。取值 (0,1)，仅在未指定 validation_datasets 时生效。	0.9
max_split_val_dataset_sample	int	否	自动划分验证集的最大样本数。验证集数量 = min(总数×(1−split), 此值)。	5
save_total_limit	int	否	Checkpoint 保存数量上限。系统只保存最后 N 个 Checkpoint。	10
lora_rank	int	否	LoRA 低秩矩阵维数。取值须为 2ⁿ（16/32/64）。	32
lora_alpha	int	否	LoRA 权重缩放系数。取值须为 2ⁿ（16/32/64）。	32

图像生成（万相）

字段	类型	必选	描述	推荐值
max_steps	int	是	训练总步数。控制训练时长的核心参数。max_steps 决定训练迭代次数，max_token_length 决定每步处理的数据量。建议不少于 500 步以确保模型充分收敛；大数据集可适当增加步数。	800
eval_steps	int	是	验证间隔。取值需≥0。训练期间每隔多少个 steps 进行一次验证评估，用于阶段性评估模型训练效果。同时保存当前 step 的模型文件。	200
learning_rate	float	是	学习率。控制模型权重更新的幅度。过高可能导致模型变差，过低则变化不明显。推荐使用默认值。	3e-5
generation_type	string	是	生成模式。`"t2i"`：文生图模式；`"i2i"`：图生图模式。决定训练数据格式和推理方式。	t2i
max_pixels	string	是	训练图片的最大分辨率。例如 "1k"、"2k"（1K 即 1024×1024，2K 即 2048×2048）。设置训练集中图片分辨率的像素总数（宽×高）上限，系统仅对超过该值的图片进行缩放处理，未超限的图片保持原样。建议三个分辨率参数（max_pixels、max_token_length、val_img_size）保持一致。	文生图："2k" 图生图："1k"
val_img_size	string	是	验证图生成分辨率。例如 "1k"、"2k"（1K 即 1024×1024，2K 即 2048×2048）。训练过程中验证评估时生成图片的目标分辨率。	文生图："2k" 图生图："1k"
max_token_length	string	是	每步训练的最大 Token 长度。例如 "1k"、"2k"。与 max_steps 共同控制训练过程：max_steps 决定迭代次数，max_token_length 决定每步处理的数据量。	文生图："2k" 图生图："1k"
gradient_clip	float	是	梯度裁剪。对所有可训练参数做全局梯度范数裁剪的阈值，防止梯度爆炸。设为 -1 表示不裁剪。	0.5
weight_decay	float	是	权重衰减。AdamW 解耦式权重衰减系数，对所有可训练参数生效，用于正则化防止过拟合。	0.02
lora_rank	int	是	LoRA 低秩矩阵的维数。该值决定了微调参数量的大小。数值越大，模型拟合能力越强，但训练速度会变慢。取值必须为 2ⁿ（如 16、32、64）。	32
save_total_limit	int	否	Checkpoint 保存数量上限。限制最多保存的模型数量。系统将始终只保存训练生成的最后 N 个 Checkpoint（N 为该参数值）。	10
split	float	否	训练集划分比例。取值范围为 (0, 1)。仅在未指定 `validation_datasets` 时生效。此参数用于从训练集中自动按比例拆分出验证集。例如，0.9 表示 90% 训练集，10% 验证集。	0.9

max_token_length对应每步训练的最大 Token 长度：

generation_type	max_token_length	L_max
t2i（文生图）	1k	128,000
t2i（文生图）	2k	232,200
i2i（图生图）	1k	232,200
i2i（图生图）	2k	320,000

返回样例

文本生成模型

{
          "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": [],
              "training_datasets": [
                  {
                      "data_source_type": "file_id",
                      "file_id": "976bd01a-f30b-4414-86fd-50c54486e3ef"
                  }
              ],
              "validation_file_ids": [],
              "validation_datasets": [],
              "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"
          }
      }

视频生成模型

重点关注 output.job_id（任务ID）和 output.finetuned_output（微调后产出的新模型名称，用于部署）。

{
    "request_id": "0eb05b0c-02ba-414a-9d0c-xxxxxxxxx",
    "output": {
        "job_id": "ft-202511111122-xxxx",
        "job_name": "ft-202511111122-xxxx",
        "status": "PENDING",
        "finetuned_output": "wan2.5-i2v-preview-ft-202511111122-xxxx",
        "model": "wan2.5-i2v-preview",
        "base_model": "wan2.5-i2v-preview",
        "training_file_ids": [],
        "training_datasets": [
            {
                "data_source_type": "file_id",
                "file_id": "xxxxxxxxxxxx"
            }
        ],
        "validation_file_ids": [],
        "validation_datasets": [],
        "hyper_parameters": {
            "n_epochs": 400,
            "batch_size": 2,
            "learning_rate": 2.0E-5,
            "split": 0.9,
            "eval_epochs": 50
        },
        "training_type": "efficient_sft",
        "create_time": "2025-11-11 11:22:22"
    }
}

返回参数

参数名称	类型	参数说明
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	兼容字段，新任务始终返回空数组，请使用 output.training_datasets。
output.training_datasets	Array of Dataset	训练数据集列表。
output.validation_file_ids	Array	兼容字段，新任务始终返回空数组，请使用 output.validation_datasets。
output.validation_datasets	Array of Dataset	测试数据集列表。
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	模型调优的任务类型。
output.finetuned_output	String	仅调优任务状态为“SUCCEEDED”时出现，返回的是调优完成的模型ID。
output.end_time	String	调优任务结束时间，当任务状态为“SUCCEEDED”、“FAILED”、“CANCELED”时出现。
output.usage	Integer	调优任务消耗的Token（count）数，扣费计算公式请参考：计费项。当任务状态为“SUCCEEDED”、“CANCELED”时出现。
output.output_cnt	Integer	当前任务已产出的 Checkpoint 数量。仅对支持多 Checkpoint 输出的模型（如 `cosyvoice-v3-flash`）返回。Checkpoint 详细列表可通过 Checkpoint 管理接口获取。
output.max_output_cnt	Integer	单次任务可产出的 Checkpoint 数量上限。`output_cnt` 超出上限的部分会按调优充分度截断。仅对支持多 Checkpoint 输出的模型返回。

任务状态	含义
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，通过工单联系阿里云工程师进行排查。