Create Text Generation Tuning Job API-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Create a model fine-tuning training job for text generation. Datasets can be uploaded via API or mounted from OSS.

Prerequisites

Supported regions: The features described in this topic are only available in the China (Beijing) 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

China (Beijing)

POST https://dashscope.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

Using file_id dataset

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":"<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"
}'

Using OSS mounted dataset

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":"oss_mount",
            "mount_storage":{
                "region":"cn-beijing",
                "bucket":"example_bucket",
                "file_path":"dataset/data.jsonl"
            }
        }
    ],
    "validation_datasets":[
        {
            "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,
        "max_length":8192,
        "split":0.8
    },
    "training_type":"sft",
    "finetuned_output_suffix":"suffix"
}'

Headers

Content-Type string (Required)

Fixed value: application/json

Authorization string (Required)

API Key authentication, in the format Bearer sk-xxxx.

Request Body

model string (Required)

The base model ID 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:

cpt
sft
efficient_sft
dpo_full
dpo_lora

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.

Important

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.

data_augmentation boolean (Optional)

Whether to enable mixed training. When enabled, training data will be mixed with the general dataset provided by Model Studio, improving training results and preventing model capability degradation. Mixed data counts toward total training tokens and is billed at standard rates.