Create a tuning task

Create a model fine-tuning job.

For Windows CMD, replace ${DASHSCOPE_API_KEY} with %DASHSCOPE_API_KEY%. For PowerShell, use $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"
      }'

Input parameters

Parameter	Required	Type	Passing method	Description
training_file_ids	Yes	Array	Body	A list of file IDs for the training set. The File Management API generates these IDs.
validation_file_ids	No	Array	Body	A list of file IDs for the validation set. The File Management API generates these IDs.
model	Yes	String	Body	The ID of the to fine-tune, or the ID of a model from a previous fine-tuning job for further fine-tuning.
hyper_parameters	No	Map	Body	The hyperparameter settings for fine-tuning. The supported hyperparameters and their default values vary by model. To view the actual default values, select the corresponding model and fine-tuning method in the console. Models for text generation and visual understanding: Use parameters such as `n_epochs`, `batch_size`, and `max_length`. The `n_epochs`, `batch_size`, and `max_length` parameters affect the fine-tuning cost and are required. For more information, see the hyper_parameters description. CosyVoice speech synthesis model (`cosyvoice-v3-flash` only): All 8 LM/FM hyperparameters are required. For details about each parameter, see the "CosyVoice speech synthesis model hyper_parameters" section below.
training_type	No	String	Body	The fine-tuning method. Valid values are `sft`, and `efficient_sft`.
job_name	No	String	Body	The name of the fine-tuning job.
model_name	No	String	Body	The name for the fine-tuned model.

`hyper_parameters` supported settings

Parameter	Default	Recommended settings	Type	Description
`n_epochs`	1	Adjust based on fine-tuning results.	Integer	Number of times the model iterates through the training data. Higher values increase training duration and cost.
`learning_rate`	`sft`: 1e-5 level `efficient_sft`: 1e-4 level The specific value varies depending on the selected model.	Use the default value.	Float	Controls the intensity of model weight updates. Too high: parameters change drastically, degrading performance. Too low: performance may not change significantly.
`freeze_vit`	true	Adjust as needed.	Boolean	Freezes the visual backbone parameters so that its weights remain unchanged during training. Applies only to Qwen-VL models.
`batch_size`	The specific value varies depending on the selected model. The larger the model, the smaller the default batch size.	Use the default value.	Integer	Number of data entries per training iteration. Smaller values prolong training time.
`eval_steps`	50	Adjust as needed.	Integer	Interval (in steps) for evaluating training accuracy and loss during training. Controls display frequency of Validation Loss and Token Accuracy.
`logging_steps`	5	Adjust as needed.	Integer	Interval (in steps) for printing fine-tuning logs.
`lr_scheduler_type`	`cosine`	Recommended: `linear` or `Inverse_sqrt`	String	Strategy for dynamically adjusting the learning rate during training. Valid values:
`max_length`	2048	8192	Integer	Maximum token length per training entry. Entries exceeding this limit are discarded.
`max_split_val_dataset_sample`	1000	Use the default value.	Integer	If `"validation_file_ids"` is not set, Alibaba Cloud Model Studio automatically splits a validation set of up to 1,000 entries. If you set `"validation_file_ids"`, this parameter is ignored.
`split`	0.8	Use the default value.	Float	If you do not set `"validation_file_ids"`, Model Studio automatically uses 80% of the training file as the training set and 20% as the validation set. If you set `"validation_file_ids"`, this parameter has no effect.
`warmup_ratio`	0.05	Use the default value.	Float	Proportion of total training steps dedicated to learning rate warmup. During warmup, the learning rate linearly increases from a small initial value to the configured rate. Limits the extent of parameter changes during early training, improving stability. Too high: equivalent to a low learning rate; performance may not change. Too low: equivalent to a high learning rate; may degrade performance. Does not apply to the "Constant" learning rate scheduler type.
`weight_decay`	0.1	Use the default value.	Float	L2 regularization strength. Helps maintain model generalization. If too high, fine-tuning effects are insignificant.
Parameters for efficient SFT (supports `efficient_sft`) Note When you perform a second round of efficient fine-tuning on a model that has already been efficiently fine-tuned, the `lora_rank`, `lora_alpha`, and `lora_dropout` parameters must be consistent.
`lora_rank`	8	64	Integer	Rank of the low-rank matrix in LoRA. Higher ranks improve fine-tuning results but slightly slow down training.
`lora_alpha`	32	Use the default value.	Integer	Scaling factor that controls the balance between original model weights and LoRA corrections. Larger values give more weight to LoRA corrections, making the model more task-specific. Smaller values preserve more pre-trained model knowledge.
`lora_dropout`	0.1	Use the default value.	Float	Dropout rate for LoRA low-rank matrix values. The recommended value enhances generalization. If too high, fine-tuning effects are insignificant.
Parameters for publishing checkpoints
`save_strategy`	`epoch`	Can be set to `epoch` or `steps`. When set to `steps`, set the `save_steps` parameter to adjust the saving interval.	String	Controls the interval and maximum number of checkpoints saved during fine-tuning.
`save_steps`	50	To modify it, set it to an integer multiple of the `eval_steps` parameter.	Integer	Number of training steps after which a checkpoint is saved.
`save_total_limit`	1	10	Integer	Maximum number of checkpoints to save for export.

CosyVoice speech synthesis model hyperparameters

Applies only to the cosyvoice-v3-flash model and is incompatible with the n_epochs, batch_size, or max_length parameters of the text generation model.

Parameter	Required	Recommended	Value	Description
lm_max_epoch	Yes	60	[1, 2147483647]	The number of epochs for LM fine-tuning.
lm_step	Yes	5	[1, 2147483647]	The interval, in epochs, for saving LM checkpoints.
lm_num	Yes	3	[1, 2147483647]	The maximum number of LM checkpoints to keep.
lm_batch_size	Yes	1000	[1, 2147483647]	The batch size for LM fine-tuning.
fm_max_epoch	Yes	100	[1, 2147483647]	The number of epochs for FM fine-tuning.
fm_step	Yes	10	[1, 2147483647]	The interval, in epochs, for saving FM checkpoints.
fm_num	Yes	3	[1, 2147483647]	The maximum number of FM checkpoints to keep.
fm_batch_size	Yes	2000	[1, 2147483647]	The batch size for FM fine-tuning.

Sample response

{
          "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",
...

Response parameters

Parameter	Type	Description
request_id	String	The ID of the request.
output	Object	Details of the fine-tuning job.
output.job_id	String	The ID of the fine-tuning job. Use this ID to call APIs such as Query Training Job Details, Query Training Log, Cancel Training Job, and Delete Training Job. Format: `ft-{yyyyMMddHHmm}-{4-character uuid}`.
output.job_name	String	Same as `output.job_id`.
output.status	String	The task status of the fine-tuning job.
output.model	String	The ID of the model for the fine-tuning job.
output.base_model	String	The ID of the base model used for the fine-tuning job. For example, the base model for the fine-tuning job `ft-202410291653-1c7f` is `qwen3-14b`.
output.training_file_ids	Array	A list of training file IDs.
output.validation_file_ids	Array	A list of validation file IDs.
output.hyper_parameters	Object	An object containing the explicitly specified hyperparameters.
output.training_type	String	The fine-tuning method.
output.create_time	String	The time the fine-tuning job was created.
output.workspace_id	String	The ID of the workspace containing the fine-tuning job.
output.user_identity	String	The UID of the primary account that owns the fine-tuning job.
output.modifier	String	The UID of the account that last modified the fine-tuning job. Example: If a sub-account cancels the job, this field contains the sub-account's UID.
output.creator	String	The UID of the user who created the fine-tuning job.
output.group	String	The type of the model fine-tuning job.

Task status	Description
PENDING	The fine-tuning job is pending.
QUEUING	The fine-tuning job is queued (only one fine-tuning job can run at a time).
RUNNING	The fine-tuning job is running.
CANCELING	The fine-tuning job is being canceled.
SUCCEEDED	The fine-tuning job succeeded.
FAILED	The fine-tuning job failed.
CANCELED	The fine-tuning job was canceled.

Request error codes

This response is returned when a request fails.

Field	Type	Description	Example value
code	String	The error code.	NotFound
request_id	String	The unique ID for the request.	6332fb02-3111-43f0-bf79-f9e8c5ffa7f9
message	String	The error message.	Not Found!

Example error response

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

Common error codes

HTTP status code	Error code	Example message	Description	Suggested action
400	InvalidParameter	Missing training files	The request included a missing, malformed, or incorrectly formatted parameter.	Correct the parameter as indicated in the error message.
400	UnsupportedOperation	The fine-tune job cannot be deleted because its status is Succeeded, Failed, or Canceled.	The resource is in a state that prevents this operation.	Retry the operation after the resource enters a valid state.
404	NotFound	Not found!	The specified resource does not exist.	Verify that the resource ID is correct.
409	Conflict	model instance xxxxx already exists, please specify a suffix	A deployment instance with this name already exists.	Provide a unique suffix.
429	Throttling	Too many fine-tune jobs are running. Retry the request later. You can have a maximum of 20 running or succeeded fine-tune jobs.	The request has triggered a platform limit.	Delete any unused models.
500	InternalError	Internal server error!	An internal error occurred.	Record the request ID and submit a ticket to an Alibaba Cloud engineer.