模型调优 API 详情_大模型服务平台百炼(Model Studio)-阿里云帮助中心

本文为您提供模型调优（模型训练、模型微调）的 HTTP 调用 API 参考。

使用这些API，您可以：

创建一个模型调优任务。
查看或列举调优任务及其状态。
查看特定调优任务的过程日志。
取消或删除一个调优任务。

前提条件

您已经阅读了模型调优简介和使用 API 进行模型调优，了解了如何使用模型调优 API 并熟悉如何在百炼平台进行模型调优的基本步骤。
已开通服务并获得API-KEY，请参考获取API Key。
已导入 API-KEY，请参考配置API Key到环境变量。

文件管理

请查看模型定制文件管理服务 API 参考。

创建调优任务

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":"qwen-turbo",
    "training_file_ids":[
        "86a9fe7f-dd77-43b0-9834-2170e12339ec",
        "03ead352-6190-4328-8016-61821c23d4fc"
    ],
    "hyper_parameters":{
        "n_epochs":1,
        "learning_rate":1.6e-5,
        "batch_size":32,
        "split":0.8  
    },
    "training_type":"sft",
    "finetuned_output_suffix":"suffix"
}'

输入参数

参数名称	默认设置	类型	是否必填	参数说明
training_file_ids		Array	是	训练集文件 ID 列表，文件 ID 由模型定制文件管理服务 API 产生。
validation_file_ids	空	Array	否	测试集文件 ID 列表，文件 ID 由模型定制文件管理服务 API 产生。
model		String	是	用于调优的基础模型 ID；或其他调优任务产出的模型 ID（对已经调优了的模型进行再次调优）。
hyper_parameters	百炼推荐的默认超参	Object	否	调优时的超参列表，百炼为支持的模型都提供了推荐的默认超参。
finetuned_output_suffix	空	String	否	用于定义调优后获得的模型 ID 的后缀。
training_type	`sft`	String	否	训练方法，可选值为：`sft`、`efficient_sft`、`dpo_full`、`dpo_lora`。

输入“hyper_parameters”超参列表

超参名称	默认设置	类型	是否必填	超参作用
`n_epochs`（循环次数）	1	Integer	否	模型遍历训练的次数，请根据模型调优实际使用经验进行调整。模型训练循环次数越多，训练时间越长，训练费用越高。
`learning_rate`（学习率）	`sft/dpo_full/dpo_lora`: 1e-5 量级 `efficient_sft`:1e-4 量级具体数值随模型选择变化。	Float	否	控制模型修正权重的强度。如果学习率设置得太高，模型参数会剧烈变化，导致调优后的模型表现不一定更好，甚至变差；如果学习率太低，调优后的模型表现不会有太大变化。
`batch_size`（批次大小）	具体数值随模型选择变化。模型越大，默认 batch_size 越小。	Integer	否	一次性送入模型进行训练的数据条数，参数过小会显著延长训练时间，推荐使用默认值。
`split` （训练集在训练文件中占比）	0.8	Float	否	当不设置`"validation_file_ids"`时，百炼会自动把训练文件中的80%作为训练集，20%作为验证集。
`max_split_val_dataset_sample` （验证集数据最大数量）	1000	Integer	否	当不设置`"validation_file_ids"`时，百炼自动分割的验证集最多只有1000条。
`lr_scheduler_type` （学习率调整策略）	cosine	String	否	在模型训练中动态调整学习率的策略。各策略详情请参考学习率调整策略介绍。
`eval_steps`（验证步数）	50	Integer	否	训练阶段针对模型的验证间隔步长，用于阶段性评估模型训练准确率、训练损失。该参数影响模型调优进行时的 Validation Loss 和 Validation Token Accuracy 的显示频率。
`max_length`（序列长度）	2048	Integer	否	指的是单条训练数据 token 支持的最大长度。如果单条数据 token 长度超过设定值，调优会直接丢弃该条数据，不进行训练。字符与 token 之间的关系请参考Token和字符串之间怎么换算。
`warmup_ratio`（学习率预热比例）	0.05	Float	否	学习率预热占用总的训练过程的比例。学习率预热是指学习率在训练开始后由一个较小值线性递增至学习率设定值。该参数主要是限制模型参数在训练初始阶段的变化幅度，从而帮助模型更稳定地进行训练。比例过大效果与过低的学习率相同，会导致调优后的模型表现不会有太大变化。比例过小效果与过高的学习率相同，可能导致调优后的模型表现不一定更好，甚至变差。该参数仅对学习率调整策略“Constant”无效。
`weight_decay`（权重衰减）	0.1	Float	否	L2正则化强度。L2正则化能在一定程度上保持模型的通用能力。数值过大会导致模型调优效果不明显。
`max_grad_norm`（梯度裁剪）	1	Float	否	梯度裁剪的最大值，用于防止参数调优时剧烈变化导致的调优失败。数值过大可能会导致调优失败，数值过小会导致模型调优效果不明显。
`logging_steps`（日志显示步数）	5	Integer	否	调优日志打印的步数。
仅`efficient_sft/dpo_lora`生效的参数
`lora_rank`（LoRA秩值）	8	Integer	否	LoRA训练中的低秩矩阵的秩大小。秩越大调优效果会更好一点，但训练会略慢。
`lora_alpha`（LoRA阿尔法）	32	Integer	否	用于控制原模型权重与LoRA的低秩修正项之间的结合缩放系数。较大的Alpha值会给予LoRA修正项更多权重，使得模型更加依赖于微调任务的特定信息；而较小的Alpha值则会让模型更倾向于保留原始预训练模型的知识。
`lora_dropout`（LoRA丢弃率）	0.1	Float	否	LoRA训练中的低秩矩阵值的丢弃率。使用推荐数值能增强模型通用化能力。数值过大会导致模型微调效果不明显。
`target_modules`（LoRA目标模块）	`AUTO`	String	否	选择模型的全部或特定模块层进行微调优化。只支持`ALL`和`AUTO`两个参数。 `ALL`是对所有的参数都加上 LoRA 训练； `AUTO`是指对模型的关键参数加上 LoRA 训练。

返回样例

{
    "request_id": "9654e55a-d74b-4113-aee1-fa19c9384fcc",
    "output": {
        "job_id": "ft-202410291653-1c7f",
        "job_name": "ft-202410291653-1c7f",
        "status": "PENDING",
        "model": "qwen-turbo",
        "base_model": "qwen-turbo",
        "training_file_ids": [
            "976bd01a-f30b-4414-86fd-50c54486e3ef"
        ],
        "validation_file_ids": [

        ],
        "hyper_parameters": {
            "n_epochs": 1,
            "learning_rate": 0.000016,
            "batch_size": 32,
            "split": 0.8
        },
        "training_type": "sft",
        "create_time": "2024-10-29 16:53:53",
        "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。比如：对模型 ID qwen2-7b-instruct_202410211621_7eba84f0 进行调优时，base_model 为 qwen2-7b-instruct。
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.user_identity	String	该调优任务隶属的主账号 uid。
output.modifier	String	对该调优任务进行最后一次操作的账号 uid。（比如：某个子账号取消了该任务，该子账号 uid 会显示在这里）
output.creator	String	该调优任务创建人 uid。
output.group	String	模型调优的任务类型。

查询调优任务详情

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

curl --location --request GET 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<替换为您的调优任务 id>' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

输入参数

字段	类型	传参方式	必选	描述
job_id	String	Url Path	是	要查询的定制任务的ID。

返回样例

{
    "request_id": "c59b2145-a93c-4e00-b610-4d7cc5c521a2",
    "output": {
        "job_id": "ft-202410291653-1c7f",
        "job_name": "ft-202410291653-1c7f",
        "status": "SUCCEEDED",
        "finetuned_output": "qwen-turbo-suffix-ft-202410291653-1c7f",
        "model": "qwen-turbo",
        "base_model": "qwen-turbo",
        "training_file_ids": [
            "976bd01a-f30b-4414-86fd-50c54486e3ef"
        ],
        "validation_file_ids": [

        ],
        "hyper_parameters": {
            "n_epochs": 1,
            "learning_rate": 0.000016,
            "batch_size": 32,
            "split": 0.8
        },
        "training_type": "sft",
        "create_time": "2024-10-29 16:53:53",
        "user_identity": "1396993924585947",
        "modifier": "1396993924585947",
        "creator": "1396993924585947",
        "end_time": "2024-10-29 17:11:26",
        "group": "llm",
        "usage": 279808
    }
}

返回参数

参数名称	类型	参数说明
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.finetuned_output	String	仅调优任务状态为“SUCCEED”时出现，返回的是调优完成的模型 ID。
output.model	String	调优任务使用的模型 ID。
output.base_model	String	调优任务使用的模型对应的基础模型ID。比如：对模型 ID qwen2-7b-instruct_202410211621_7eba84f0 进行调优时，base_model 为 qwen2-7b-instruct。
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.user_identity	String	该调优任务隶属的主账号 uid。
output.modifier	String	对该调优任务进行最后一次操作的账号 uid。（比如：某个子账号取消了该任务，该子账号 uid 会显示在这里）
output.creator	String	该调优任务创建人 uid。
output.end_time	String	调优任务结束时间，当任务状态为“SUCCEED”、“FAILED”、"CANCELED"时出现。
output.group	String	模型调优的任务类型。
output.usage	Integer	调优任务消耗的 token（count）数，扣费计算公式请参考：模型训练计费（模型调优、模型微调）。当任务状态为“SUCCEED”、"CANCELED"时出现。

列举调优任务

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

curl --location --request GET 'https://dashscope.aliyuncs.com/api/v1/fine-tunes?model=qwen-turbo&page_no=2' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

输入参数

参数名称	类型	传参方式	是否必填	参数说明
page_no	number	Query	否	默认1
page_size	number	Query	否	默认10，最大值100，最小值1
model	String	Query	否	模型 ID，指定该参数表示只列举基于该模型的调优任务

返回样例

{
    "request_id": "2182ef64-6398-457b-b3f6-5fde5fd6b388",
    "output": {
        "page_no": 2,
        "page_size": 10,
        "total": 12,
        "jobs": [
            {
                "job_id": "ft-202410291653-1c7f",
                "job_name": "ft-202410291653-1c7f",
                "status": "SUCCEEDED",
                "finetuned_output": "qwen-turbo-suffix-ft-202410291653-1c7f",
                "model": "qwen-turbo",
                "base_model": "qwen-turbo",
                "training_file_ids": [
                    "976bd01a-f30b-4414-86fd-50c54486e3ef"
                ],
                "validation_file_ids": [

                ],
                "hyper_parameters": {
                    "n_epochs": 1,
                    "learning_rate": 0.000016,
                    "batch_size": 32,
                    "split": 0.8
                },
                "training_type": "sft",
                "create_time": "2024-10-29 16:53:53",
                "user_identity": "1396993924585947",
                "modifier": "1396993924585947",
                "creator": "1396993924585947",
                "end_time": "2024-10-29 17:11:26",
                "group": "llm",
                "usage": 279808
            },
            {
                "job_id": "ft-202410291512-1851",
                "job_name": "ft-202410291512-1851",
                "status": "CANCELED",
                "model": "qwen-turbo",
                "base_model": "qwen-turbo",
                "training_file_ids": [
                    "86a9fe7f-dd77-43b0-9834-2170e12339ec",
                    "03ead352-6190-4328-8016-61821c23d4fc"
                ],
                "validation_file_ids": [

                ],
                "hyper_parameters": {
                    "n_epochs": 1,
                    "learning_rate": 0.000016,
                    "batch_size": 32,
                    "split": 0.8
                },
                "code": "1",
                "training_type": "sft",
                "create_time": "2024-10-29 15:12:00",
                "user_identity": "1396993924585947",
                "modifier": "1396993924585947",
                "creator": "1396993924585947",
                "end_time": "2024-10-29 15:16:00",
                "group": "llm",
                "usage": 0
            }
        ]
    }
}

返回参数

参数名称	类型	参数说明
request_id	String	本次请求的 ID。
output	Object	查询返回的详细信息。
output.page_no	Integer	页码。
output.page_size	Integer	每页显示的数据量。
output.total	Integer	调优任务总计数量。
output.jobs	Array	多个调优任务详情，详细参数请参考调优任务详情返回参数。

获取调优任务日志

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

curl --location --request GET 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<替换为您的调优任务 id>/logs?offset=10&line=10' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

输入参数

字段	类型	传参方式	必选	描述
job_id	String	Url Path	是	要打印日志的调优任务ID。
offset	Number	Query	否	忽略前offset行输出，从第offset+1行开始读取。不能超过当前已有输出的总行数，超过则不会有输出信息返回。默认值为0。
line	Number	Query	否	从offset+1行（包含）起，读取line行输出信息，如果本次请求的输出不足line行，则以实际输出为准。默认值为100，上限为1000。

返回样例

{
    "request_id": "ce49b45d-fe46-474e-9e1b-3e7427ffdf5a",
    "output": {
        "total": 20,
        "logs": [
            "{'train_runtime': 216.3999, 'train_samples_per_second': 2.066, 'train_steps_per_second': 0.014, 'train_loss': 0.9122632344563802, 'epoch': 0.8571428571428571}",
            " Actual number of consumed tokens is 279808!",
            " Uploaded checkpoint!",
            " Fine-tune succeeded!",
            " use checkpoint-3 as final checkpoint",
            "2024-10-29 17:03:47,719 - INFO - transfer for inference succeeded, start to deliver it for inference",
            "2024-10-29 17:09:43,322 - INFO - start to save checkpoint",
            "2024-10-29 17:11:24,689 - INFO - finetune-job succeeded",
            "2024-10-29 17:11:25,130 - INFO - training usage 279808",
            "2024-10-29 17:11:25,175 - INFO - ##FT_COMPLETE##"
        ]
    }
}

返回参数

参数名称	类型	参数说明
request_id	String	本次请求的 ID。
output	Object	查询返回的详细信息。
output.total	Integer	日志总计行数。
output.logs	Integer	输出的日志。

取消调优任务

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/<替换为您的调优任务 id>/cancel' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

输入参数

字段	类型	传参方式	必选	描述
job_id	String	Url Path	是	要取消的调优任务ID。

返回样例

{
    "request_id": "670fca9d-48dd-4c5a-83e7-33bcc20420f8",
    "output": {
        "status": "success"
    }
}

返回参数

参数名称	类型	参数说明
request_id	String	本次请求的 ID。
output	Object	取消操作返回的详细信息。

删除调优任务

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

curl --location --request DELETE 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<替换为您的调优任务 id>' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

输入参数

字段	类型	传参方式	必选	描述
job_id	String	Url Path	是	要删除的调优任务ID。

返回样例

{
    "request_id": "7d7e1469-df77-4163-83ce-54425df744ed",
    "output": {
        "status": "success"
    }
}

返回参数

参数名称	类型	参数说明
request_id	String	本次请求的 ID。
output	Object	删除操作返回的详细信息。

调优任务状态

任务状态	含义
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	资源的创建触发平台限制。	稍后再试。
500	InternalError	Internal server error!	内部错误。	记录request_id，通过工单联系阿里云工程师进行排查。