Text Generation - Create a Tuning Job - Alibaba Cloud Model Studio

Prerequisites

Supported regions: The features described in this topic are only available in the Singapore region, and you must use an API Key from this region.
Account permissions: If you use an Alibaba Cloud sub-account (RAM user), you need to grant the sub-account permissions for model invocation, training, and deployment.
Configure environment variables: You have successfully obtained an API Key and configured it as an environment variable.
Preparation: You have read Qwen model tuning to understand the supported models for fine-tuning, fine-tuning steps, data formats, and billing.

Create a fine-tuning job

Singapore

POST https://dashscope-intl.aliyuncs.com/api/v1/fine-tunes

For Windows CMD, replace $DASHSCOPE_API_KEY with %DASHSCOPE_API_KEY%. For PowerShell, replace with $env:DASHSCOPE_API_KEY

Request parameters

Headers

Content-Type string (Required)Fixed value: application/jsonAuthorization string (Required)API Key authentication, in the format Bearer sk-xxxx.

Request Body

model string (Required)The for fine-tuning, or the model ID produced by another fine-tuning job (for re-tuning an already fine-tuned model).training_type string (Optional)Fine-tuning method. Available values:

sft
efficient_sft

hyper_parameters object (Optional)Hyperparameter settings. Different models support different parameter sets with different default values. Please check the console with the same model and tuning method to view actual default values. Among them, n_epochs, batch_size, and max_length affect tuning costs and must be specified.

Hyperparameter properties

n_epochs int (Required)Number of training epochs. The number of times the model iterates through the training data. Adjust based on your fine-tuning experience.

Data volume < 10,000: recommended 3-5 epochs.
Data volume > 10,000: recommended 1-2 epochs.

This parameter affects training billing. More epochs mean longer training time and higher costs.

batch_size int (Required)Batch size. The number of data samples sent to the model for training at once. A value too small will significantly increase training time. Default values vary by model, please check the console.max_length int (Required)Sequence length. Recommended value: 8192. The maximum token length supported for a single training sample. If a single sample exceeds this token length, it will be discarded and not used for training.For the relationship between characters and tokens, see Token and string conversion.learning_rate float (Optional)Learning rate. Recommended to use the Model Studio default value. Controls the intensity of model weight correction.

If too high, model parameters change drastically, potentially degrading performance.
If too low, model performance will not change significantly.

lr_scheduler_type string (Optional)Learning rate scheduler type. Recommended: linear or inverse_sqrt. A strategy for dynamically adjusting the learning rate during training. For details on each strategy, see Learning rate scheduler description.split float (Optional)The proportion of training data in the training file. Recommended to use the Model Studio default value.When validation_datasets is not set, Model Studio automatically uses 80% as training set and 20% as validation set. This parameter is invalid when validation_datasets is set.max_split_val_dataset_sample int (Optional)Maximum validation dataset size. Recommended to use the Model Studio default value.When validation_datasets is not set, the automatically split validation set contains at most 1,000 samples. This parameter is invalid when validation_datasets is set.eval_steps int (Optional)Validation steps. The validation interval during training, used for periodic evaluation of model training accuracy and training loss.This parameter affects the display frequency of Validation Loss and Validation Token Accuracy during tuning.logging_steps int (Optional)Logging steps. The interval steps for printing tuning logs.warmup_ratio float (Optional)Warmup ratio. Recommended to use the Model Studio default value. The proportion of total training process used for learning rate warmup. Learning rate warmup means the learning rate linearly increases from a small value to the set value after training starts, helping the model train more stably.

If too large: same effect as too low a learning rate, resulting in minimal change in model performance after tuning.
If too small: same effect as too high a learning rate, potentially causing worse model performance after tuning.

This parameter is not applicable to the Constant learning rate scheduler.

weight_decay float (Optional)Weight decay (L2 regularization strength). Recommended to use the Model Studio default value. Helps preserve the model's general capabilities to some extent. A value too large will make tuning effects less noticeable.freeze_vit boolean (Optional)Whether to freeze the vision backbone. Freezes the parameters of the vision backbone so its weights are not updated during training. Only applicable to Qwen-VL (visual understanding) models.

Only when freeze_vit is set to true can the model be billed by token usage.

lora_rank int (Optional)LoRA rank. Recommended value: 64. The rank of the low-rank matrix in LoRA training. A larger rank yields better tuning results but slightly slower training.Only effective when training_type is efficient_sft or dpo_lora.

When performing a second efficient fine-tuning on an already efficiently fine-tuned model, lora_rank, lora_alpha, and lora_dropout must remain consistent.

lora_alpha int (Optional)LoRA scaling factor. Recommended to use the Model Studio default value. Controls the scaling factor between the original model weights and the LoRA low-rank correction.

A larger alpha value gives more weight to the LoRA correction, making the model more dependent on task-specific information.
A smaller alpha value makes the model more inclined to retain the original pretrained knowledge.

Only effective when training_type is efficient_sft or dpo_lora.lora_dropout float (Optional)LoRA dropout rate. Recommended to use the Model Studio default value. The dropout rate of low-rank matrix values in LoRA training. Using the recommended value enhances model generalization. A value too large will make fine-tuning effects less noticeable.Only effective when training_type is efficient_sft or dpo_lora.save_strategy string (Optional)Checkpoint save strategy. Can be set to epoch or steps. When set to steps, you can adjust the save interval with the save_steps parameter.Only effective when training_type is efficient_sft or sft.save_steps int (Optional)Save steps. Set how many training steps between each model checkpoint save. Recommended to set as an integer multiple of eval_steps .Only effective when training_type is efficient_sft or sft.save_total_limit int (Optional)Checkpoint save limit. Recommended value: 10. Limits the maximum number of checkpoints saved for deployment.Only effective when training_type is efficient_sft or sft.

training_datasets Array of Dataset (Required)Training dataset file list.

Dataset structure

data_source_type string (Required)Data source type. Available values:

oss_mount (Mount OSS file)
file_id (File uploaded via File Management API)

mount_storage object (Conditionally required)Required when data source type is oss_mount. OSS mount information.

Properties

region string (Required)The region of the OSS Bucket to mount. Supports Beijing (cn-beijing) and Singapore (ap-southeast-1).bucket string (Required)The name of the OSS Bucket to mount.file_path string (Required)The OSS file path (object key) to mount. For datasets containing multiple files, use the path to data.jsonl. Unlike the file_id method, you need to upload the uncompressed dataset folder to OSS. Zip files are not supported.

file_id string (Conditionally required)Required when data source type is file_id. File ID, generated by the Upload File API.

validation_datasets Array of Dataset (Optional)Validation dataset file list. Same structure as training_datasets.job_name string (Optional)Tuning job name.model_name string (Optional)Model name after tuning is complete.

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_datasets":[
        {
            "data_source_type":"file_id",
            "file_id":"<Replace with the file ID of your training dataset>"
        }
    ],
    "validation_datasets":[
        {
            "data_source_type":"file_id",
            "file_id":"<Replace with the file ID of your validation dataset>"
        }
    ],
    "hyper_parameters":{
        "n_epochs":1,
        "learning_rate":"1.6e-5",
        "batch_size":32,
        "max_length":8192,
        "split":0.8
    },
    "training_type":"sft",
    "finetuned_output_suffix":"suffix"
}'

Response parameters

request_id stringThe ID of this request.output objectJob details.

Properties

job_id stringUnique identifier for the fine-tuning job, used to query job details, logs, cancel, or delete the job. Generation rule: ft-{yyyyMMddHHmm}-{4 char uuid}.job_name stringFine-tuning job name.status stringStatus of the fine-tuning job:

PENDING: Training pending.
QUEUING: Training is queuing (only one fine-tuning job can run at a time).
RUNNING: Training in progress.
SUCCEEDED: Training succeeded.
FAILED: Training failed.
CANCELED: Training canceled.
CANCELING: Training is being canceled.

finetuned_output stringThe new model ID produced after fine-tuning. Returned when job status is SUCCEEDED.model stringThe base model used.base_model stringThe base model used.training_file_ids arrayLegacy field for backward compatibility, always returns an empty array for new jobs. Please use training_datasets.training_datasets Array of DatasetTraining dataset list.validation_file_ids arrayLegacy field for backward compatibility, always returns an empty array for new jobs. Please use validation_datasets.validation_datasets Array of DatasetValidation dataset list. Empty array if no validation set is specified.hyper_parameters objectThe actual hyperparameters used.training_type stringThe training method for fine-tuning.create_time stringJob creation time.end_time stringJob end time. Returned when job status is SUCCEEDED, FAILED, or CANCELED.usage integerThe number of tokens consumed by the fine-tuning job. For the billing calculation formula, see: Billing. Returned when job status is SUCCEEDED or CANCELED.workspace_id stringThe workspace ID of the tuning job.user_identity stringUser identity, Alibaba Cloud account ID.creator stringCreator's Alibaba Cloud account ID.modifier stringModifier's Alibaba Cloud account ID.group stringFine-tuning job group.

code stringError code. Returned when the call fails. See the error code table below.message stringError message details. Returned when the call fails.

{
    "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"
    }
}

Error codes

If the call fails and returns an error message, refer to the following table for troubleshooting.

HTTP status code	Error code	Solution
400	InvalidParameter	Parameter error: missing parameters or format issues. Correct your parameters based on the error message.
400	UnsupportedOperation	Cannot operate on the resource when it is in a specific state. Wait until the resource reaches an operable state before retrying.
404	NotFound	The resource to query/operate does not exist. Check if the resource ID is incorrect.
409	Conflict	A deployment instance with the same name already exists. Specify a suffix to differentiate.
429	Throttling	Resource creation triggered a platform limit. Delete models that are no longer in use.
500	InternalError	Internal error. Record the request_id and contact Alibaba Cloud engineers through a ticket for investigation.

Next step

Fine-tuning is an asynchronous operation. After calling this API, you can query the tuning job status through the Query and manage tuning jobs API.

​Prerequisites

​Create a fine-tuning job

Request parameters

Headers

Request Body

Response parameters

​Error codes

​Next step

Prerequisites

Create a fine-tuning job

Error codes

Next step