DocsICP FilingConsole
Documentation
Home Page Alibaba Cloud Model Studio API Reference (Models) Model Production Model tuning Text Generation Create a Tuning Job

Text Generation - Create a Tuning Job

Updated at:
Copy as MD
Product
My Favorites

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

Prerequisites

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

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.

ImportantThis 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.

Only effective when training_type is efficient_sft or sft.

augmentation_types string (Optional)

Preset data types. When mixed training is enabled, select preset data types separated by commas. Must be used together with augmentation_ratio. Example: "dialogue_cn,general_purpose_cn,nlp".

Available values:

Value

Dataset name

Applicable models

dialogue_cn

Chinese - Dialogue

Qwen 2 series

math_cn

Chinese - Math

Qwen 2 series

general_coding_cn

Chinese - Code

Qwen 2 series

general_purpose_cn

Chinese - General

Qwen 2 series

nlp

NLP Understanding

Qwen 2 series

dialogue_en

English - Dialogue

Qwen 2 series

math_en

English - Math

Qwen 2 series

general_coding_en

English - Code

Qwen 2 series

general_purpose_en

English - General

Qwen 2 series

mix_v2

General - V2

Qwen 3 series

vl_mix

General

Qwen 3 VL series

Only effective when training_type is efficient_sft or sft.

augmentation_ratio string (Optional)

Augmentation ratio. Must correspond exactly to augmentation_types. Randomly samples and mixes data proportional to training data volume. Value range: 0.0-2.0. Example: "0.1,0.05,0.15".

Only effective when training_type is efficient_sft or sft.

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

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

export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your Workspace ID, and cn-beijing with the corresponding region (Singapore: ap-southeast-1, US East: us-east-1)
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
# List fine-tuning jobs
dashscope ft list

# Create a fine-tuning job
dashscope ft create -t <file-id> -m qwen3-4b-instruct-2507 -e 1 -b 8

Response parameters

request_id string

The ID of this request.

output object

Job details.

Properties

job_id string

Unique 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 string

Fine-tuning job name.

status string

Status 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 string

The new model ID produced after fine-tuning. Returned when job status is SUCCEEDED.

model string

The base model used.

base_model string

The base model used.

training_file_ids array

Legacy field for backward compatibility, always returns an empty array for new jobs. Please use training_datasets.

training_datasets Array of Dataset

Training dataset list.

validation_file_ids array

Legacy field for backward compatibility, always returns an empty array for new jobs. Please use validation_datasets.

validation_datasets Array of Dataset

Validation dataset list. Empty array if no validation set is specified.

hyper_parameters object

The actual hyperparameters used.

training_type string

The training method for fine-tuning.

create_time string

Job creation time.

end_time string

Job end time. Returned when job status is SUCCEEDED, FAILED, or CANCELED.

usage integer

The 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 string

The workspace ID of the tuning job.

user_identity string

User identity, Alibaba Cloud account ID.

creator string

Creator's Alibaba Cloud account ID.

modifier string

Modifier's Alibaba Cloud account ID.

group string

Fine-tuning job group.

code string

Error code. Returned when the call fails. See the error code table below.

message string

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

{
    "code": "InvalidParameter",
    "request_id": "BE213CDD-8A5C-59EE-9A67-055EAB0CB59B",
    "message": "Missing training files"
}

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.If you need to increase fine-tuning job concurrency or retain more successfully tuned models, please contact your account manager.

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.

Previous：Text GenerationNext：Model import