Learn how to tune Qwen models in Alibaba Cloud Model Studio using the API (HTTP) and the command line (shell). Model tuning involves three methods: supervised fine-tuning (SFT), continual pre-training (CPT), and direct preference optimization (DPO).
Prerequisites
Review Introduction to model fine-tuning to understand its concepts, process, and data requirements.
Activate the service and obtain an API key. For instructions, see Get an API key.
Grant the RAM user (RAM user) the necessary invocation, training, and deployment permissions.
The API supports only token-based billing for training jobs. To use model training units (prepaid or postpaid), create the job in the console.
Tuning file upload
Preparing fine-tuning files
SFT training set
SFT ChatML (Chat Markup Language) format training data supports multi-turn conversations and various role settings.
The OpenAInameandweightparameters are not supported. All assistant outputs will be trained.
# A single line of training data (in JSON format) has the following typical structure when expanded:
{"messages": [
{"role": "system", "content": "System input 1"},
{"role": "user", "content": "User input 1"},
{"role": "assistant", "content": "Expected model output 1"},
{"role": "user", "content": "User input 2"},
{"role": "assistant", "content": "Expected model output 2"}
...
]}For information about the differences between system, user, and assistant, see Overview. Sample training datasets: SFT-ChatML_format_example.jsonl, SFT-ChatML_format_example.xlsx. XLS and XLSX formats support only single-turn conversations.
All assistant lines in a single training data entry support the "loss_weight" parameter, which sets the relative importance of that line during training. (Range: 0.0 to `1.0`. A larger value indicates higher importance.)
This parameter is available for invitational preview. To use it, contact your account manager.
{"role": "assistant", "content": "Expected model output 1", "loss_weight": 1.0},
{"role": "assistant", "content": "Expected model output 2", "loss_weight": 0.5}You can also download a data template from the Model Studio console. |
|
Upload fine-tuning file to Model Studio
OpenAI-compatible Files API
import os
from pathlib import Path
from openai import OpenAI
client = OpenAI(
# If you have not configured an environment variable, replace the following line with api_key="sk-xxx" and use your Model Studio API key.
# API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key=os.getenv("DASHSCOPE_API_KEY"),
# The following is the URL for the Singapore region. If you use a service in the China (Beijing) region, replace the URL with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
# test.jsonl is a local sample file.
file_object = client.files.create(file=Path("test.jsonl"), purpose="fine-tune")
print(file_object.model_dump_json())import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.files.*;
import java.nio.file.Path;
import java.nio.file.Paths;
public class Main {
public static void main(String[] args) {
// Create a client and use the API key from the environment variable.
OpenAIClient client = OpenAIOkHttpClient.builder()
// API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
// The following is the URL for the Singapore region. If you use a service in the China (Beijing) region, replace the URL with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
.baseUrl("https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1")
.build();
// Set the file path. Modify the path and filename as needed.
Path filePath = Paths.get("src/main/java/org/example/test.txt");
// Create file upload parameters.
FileCreateParams params = FileCreateParams.builder()
.file(filePath)
.purpose(FilePurpose.of("fine-tune"))
.build();
// Upload the file.
FileObject fileObject = client.files().create(params);
System.out.println(fileObject);
}
}# ======= Important =======
# API keys for the Singapore and China (Beijing) regions are different. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# The following is the URL for the Singapore region. If you use a service in the China (Beijing) region, replace the URL with: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/files
# === Delete this comment before running ===
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/files \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
--form 'file=@"test.jsonl"' \
--form 'purpose="fine-tune"'Limitations:
The maximum size of a single file is 300 MB.
The total size of all non-deleted files is limited to 5 GB.
You can store a maximum of 100 non-deleted files.
Files are stored indefinitely.
Model fine-tuning
Create a fine-tuning job
HTTP
For Windows CMD, replace${DASHSCOPE_API_KEY}with%DASHSCOPE_API_KEY%. For PowerShell, use$env:DASHSCOPE_API_KEY.
curl --location "https://dashscope.aliyuncs.com/api/v1/fine-tunes" \
--header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{
"model":"qwen3-8b",
"training_file_ids":[
"<your_training_file_id_1>",
"<your_training_file_id_2>"
],
"hyper_parameters":
{
"n_epochs": 3,
"batch_size": 16,
"max_length": 8192,
"learning_rate": "1.6e-5",
"lr_scheduler_type": "linear",
"split": 0.9,
"warmup_ratio": 0.05,
"eval_steps": 50,
"data_augmentation": true,
"augmentation_ratio": "0.1,0.05,0.15",
"augmentation_types": "dialogue_CN,general_purpose_CN,NLP",
"save_strategy": "epoch",
"save_total_limit": 10
},
"training_type":"sft"
}'Parameters
Parameter | Required | Type | Location | Description |
training_file_ids | Yes | Array | Body | A list of file IDs for the training set. |
validation_file_ids | No | Array | Body | A list of file IDs for the validation set. |
model | Yes | String | Body | The ID of the base model for fine-tuning, or the ID of a previously fine-tuned model. |
hyper_parameters | No | Map | Body | Hyperparameters for the fine-tuning job. Supported parameters and their default values vary by model. To view the default values, go to the console and select the same model and fine-tuning method. The following parameters are required because they affect the training cost: |
training_type | No | String | Body | Specifies the fine-tuning method. Valid values are:
|
job_name | No | String | Body | Specifies the name of the fine-tuning job. |
model_name | No | String | Body | Specifies the name of the fine-tuned model. This is not the model ID, which is generated by the system. |
Response
{
"request_id": "635f7047-003e-4be3-b1db-6f98e239f57b",
"output":
{
"job_id": "ft-202511272033-8ae7",
"job_name": "ft-202511272033-8ae7",
"status": "PENDING",
"finetuned_output": "qwen3-8b-ft-202511272033-8ae7",
"model": "qwen3-8b",
"base_model": "qwen3-8b",
"training_file_ids":
[
"9e9ffdfa-c3bf-436e-9613-6f053c66aa6e"
],
"validation_file_ids":
[],
"hyper_parameters":
{
"n_epochs": 3,
"batch_size": 16,
"max_length": 8192,
"learning_rate": "1.6e-5",
"lr_scheduler_type": "linear",
"split": 0.9,
"warmup_ratio": 0.05,
"eval_steps": 50,
"data_augmentation": true,
"augmentation_ratio": "0.1,0.05,0.15",
"augmentation_types": "dialogue_CN,general_purpose_CN,NLP",
"save_strategy": "epoch",
"save_total_limit": 10
},
"training_type": "sft",
"create_time": "2025-11-27 20:33:15",
"workspace_id": "llm-8v53etv3hwb8orx1",
"user_identity": "1654290265984853",
"modifier": "1654290265984853",
"creator": "1654290265984853",
"group": "llm",
"max_output_cnt": 10
}
}Base models (model) and training types (training_type)
hyper_parameters: Supported settings
Retrieve a fine-tuning job
To retrieve the details of a fine-tuning job, use the job_id returned when you create the job.
HTTP
curl 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'Request parameters
Parameter | Type | Location | Required | Description |
job_id | String | Path | Yes | The ID of the fine-tuning job. |
Successful response
{
"request_id": "d100cddb-ac85-4c82-bd5c-9b5421c5e94d",
"output":
{
"job_id": "ft-202511272033-8ae7",
"job_name": "ft-202511272033-8ae7",
"status": "RUNNING",
"finetuned_output": "qwen3-8b-ft-202511272033-8ae7",
"model": "qwen3-8b",
"base_model": "qwen3-8b",
"training_file_ids":
[
"9e9ffdfa-c3bf-436e-9613-6f053c66aa6e"
],
"validation_file_ids":
[],
"hyper_parameters":
{
"n_epochs": 3,
"batch_size": 16,
"max_length": 8192,
"learning_rate": "1.6e-5",
"lr_scheduler_type": "linear",
"split": 0.9,
"warmup_ratio": 0.05,
"eval_steps": 50,
"data_augmentation": true,
"augmentation_ratio": "0.1,0.05,0.15",
"augmentation_types": "dialogue_CN,general_purpose_CN,NLP",
"save_strategy": "epoch",
"save_total_limit": 10
},
"training_type": "sft",
"create_time": "2025-11-27 20:33:15",
"workspace_id": "llm-8v53etv3hwb8orx1",
"user_identity": "1654290265984853",
"modifier": "1654290265984853",
"creator": "1654290265984853",
"group": "llm",
"max_output_cnt": 10
}
}Job status | Description |
PENDING | The job is waiting to start. |
QUEUING | The job is queued. Only one fine-tuning job runs at a time. |
RUNNING | The job is running. |
CANCELING | The job is being canceled. |
SUCCEEDED | The job succeeded. |
FAILED | The job failed. |
CANCELED | The job was canceled. |
After a fine-tuning job succeeds, the finetuned_output field provides the resulting model ID. Use this ID for model deployment.
Get fine-tuning job logs
HTTP
curl 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>/logs?offset=0&line=1000' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json' Use theoffsetandlineparameters to retrieve a range of log lines. Theoffsetparameter specifies the starting line, and thelineparameter specifies the maximum number of lines to return.
Sample response:
{
"request_id":"1100d073-4673-47df-aed8-c35b3108e968",
"output":{
"total":57,
"logs":[
"{Fine-tuning log 1}",
"{Fine-tuning log 2}",
...
...
...
]
}
}Query and publish model checkpoints
Only SFT fine-tuning (efficient_sftandsft) supports saving and publishing checkpoints from intermediate training states.
List checkpoints for a fine-tuning job
curl 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>/checkpoints' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'Request parameters
Parameter | Type | Parameter location | Required | Description |
job_id | String | Path Parameter | Yes | The ID of the fine-tuning job. |
Sample response
The checkpoint field contains the checkpoint ID, which specifies the checkpoint to publish in the Model publishing (optional) API. The model_name field contains the model ID used for model deployment. The finetuned_output field in the original fine-tuning job response is the model_name of the final checkpoint.
{
"request_id": "c11939b5-efa6-4639-97ae-ed4597984647",
"output":
[
{
"create_time": "2025-11-11T16:25:42",
"full_name": "ft-202511272033-8ae7-checkpoint-20",
"job_id": "ft-202511272033-8ae7",
"checkpoint": "checkpoint-20",
"model_name": "qwen3-8b-instruct-ft-202511272033-8ae7",
"status": "SUCCEEDED"
}
]
}Status | Description |
PENDING | The checkpoint is pending publication. You must publish it using the Model publishing API before you can use it for model deployment and invocation. |
PROCESSING | The checkpoint is being published. |
SUCCEEDED | The checkpoint has been published successfully. You can now use it for model deployment and invocation. |
FAILED | The checkpoint failed to publish. |
Model publishing (optional)
In Model Studio, after a fine-tuning job completes, you must export a checkpoint before you can deploy the model.
Exported checkpoints are stored in cloud storage. You cannot access or download them at this time.
curl --request GET 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>/export/<checkpoint_id>?model_name=<model_name>' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'Request parameters
Parameter | Type | Parameter location | Required | Description |
job_id | String | Path Parameter | Yes | The ID of the fine-tuning job. |
checkpoint_id | String | Path Parameter | Yes | The ID of the checkpoint to publish. |
model_name | String | Path Parameter | Yes | The custom model ID to assign to the published model. |
Sample response
{
"request_id": "ed3faa41-6be3-4271-9b83-941b23680537",
"output": true
}The publishing task is asynchronous. Use the List checkpoints for a fine-tuning job API to monitor the publishing status of the checkpoint.
More fine-tuning operations
List fine-tuning jobs
curl 'https://dashscope.aliyuncs.com/api/v1/fine-tunes' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json' Cancel a fine-tuning job
Cancels a running fine-tuning job.
curl --request POST 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>/cancel' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json' Delete a fine-tuning job
You cannot delete a running fine-tuning job.
curl --request DELETE 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json' Model deployment and invocation
Model deployment
To deploy the model, go to the model deployment console.
Model invocation
Once the model deployment status is RUNNING, you can invoke the fine-tuned model just like any other model.
You can also get the Model Code from the model deployment console.
For details on usage and parameters, see the DashScope API Reference.
curl 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json' \
--data '{
"model": "<your_model_instance_id>",
"input":{
"messages":[
{
"role": "user",
"content": "Who are you?"
}
]
},
"parameters": {
"result_format": "message"
}
}'