模型調優操作 - Alibaba Cloud Model Studio

本文檔以千問模型的調優操作為例進行說明，通過 API （HTTP）和命令列（Shell）兩種方式，使用阿里雲百鍊提供的模型調優功能。模型調優包含模型微調（SFT）、繼續預訓練（CPT）、模型偏好訓練（DPO）三種模型訓練方式。

前提條件

已經完整閱讀了模型調優簡介，瞭解模型調優的基本概念、流程及資料格式要求。
已開通服務並獲得API-KEY，請參考擷取API Key。
阿里雲子帳號（RAM使用者）需被授予必要的調用、訓練和部署許可權。

說明

通過 API 建立的訓練任務僅支援按 Token 計費，暫不支援使用模型訓練單元（預付費或後付費）。如需使用訓練單元，請通過控制台建立任務。

上傳調優檔案

準備調優檔案

SFT 訓練集

SFT ChatML（Chat Markup Language）格式訓練資料，支援多輪對話和多種角色設定。

不支援OpenAI 的name、weight參數，所有的 assistant 輸出都會被訓練。

# 一行訓練資料（json 格式），展開後典型結構如下:
{"messages": [
  {"role": "system", "content": "系統輸入1"}, 
  {"role": "user", "content": "使用者輸入1"}, 
  {"role": "assistant", "content": "期望的模型輸出1"}, 
  {"role": "user", "content": "使用者輸入2"}, 
  {"role": "assistant", "content": "期望的模型輸出2"}
  ...
]}

system/user/assistant 區別請參見概述，訓練資料集範例：SFT-ChatML格式樣本.jsonl、SFT-ChatML格式樣本.xlsx（xls、xlsx 格式只支援單輪對話）。

單條訓練資料的所有 assistant 行都支援"loss_weight"參數，用於設定該行在訓練時的相對重要性。（設定範圍0.0 ~ 1.0，數值越大，重要性越高）

該參數屬於邀測參數，如需使用，請聯絡您的商務經理。

 {"role": "assistant", "content": "期望的模型輸出1", "loss_weight": 1.0}, 
 {"role": "assistant", "content": "期望的模型輸出2", "loss_weight": 0.5}

也可以前往百鍊控制台下載資料範本。

將調優檔案上傳至阿里雲百鍊

OpenAI 相容 - FIle 介面

Python

import os
from pathlib import Path
from openai import OpenAI


client = OpenAI(
    # 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：api_key="sk-xxx",
    # 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下為新加坡地區url，若使用北京地區的服務，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# test.jsonl 是一個本地樣本檔案
file_object = client.files.create(file=Path("test.jsonl"), purpose="fine-tune")

print(file_object.model_dump_json())

Java

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) {
        // 建立用戶端，使用環境變數中的API密鑰
        OpenAIClient client = OpenAIOkHttpClient.builder()
                // 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // 以下為新加坡地區url，若使用北京地區的服務，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
                .baseUrl("https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1")
                .build();
        // 設定檔案路徑,請根據實際需求修改路徑與檔案名稱
        Path filePath = Paths.get("src/main/java/org/example/test.txt");
        // 建立檔案上傳參數
        FileCreateParams params = FileCreateParams.builder()
                .file(filePath)
                .purpose(FilePurpose.of("fine-tune"))
                .build();

        // 上傳檔案
        FileObject fileObject = client.files().create(params);
        System.out.println(fileObject);
    }
}

curl

# ======= 重要提示 =======
# 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 以下為新加坡地區url，若使用北京地區的服務，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1/files
# === 執行時請刪除該注釋 ===

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

說明

使用限制：

單個檔案大小最大為300MB
所有的有效檔案（未刪除）總使用空間配額為5GB
所有的有效檔案（未刪除）總數量配額為100個
檔案儲存體沒有時間限制

模型調優

建立調優任務

HTTP

Windows CMD 請將${DASHSCOPE_API_KEY}替換為 %DASHSCOPE_API_KEY%，PowerShell 請替換為 $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":[
        "<替換為訓練資料集的file_id1>",
        "<替換為訓練資料集的file_id2>"
    ],
    "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"
}'

輸入參數

欄位	必選	類型	傳參方式	描述
training_file_ids	是	Array	Body	訓練集檔案清單。
validation_file_ids	否	Array	Body	驗證集檔案清單。
model	是	String	Body	用於調優的基本模型 ID，或其他調優任務產出的模型 ID。
hyper_parameters	否	Map	Body	用於調優模型的超參數。不同模型支援的參數及其預設值不同，請在控制台選擇相同的模型和訓練方式查看實際預設值。以下參數影響訓練費用，必須填寫：`n_epochs`（迴圈次數）、`batch_size`（批次大小）、`max_length`（序列長度）。
training_type	否	String	Body	調優方法，可選值為： `cpt` `sft` `efficient_sft` `dpo_full` `dpo_lora`
job_name	否	String	Body	調優任務名稱
model_name	否	String	Body	調優產生的模型名稱（並非模型 ID，模型 ID 由系統產生）

返回範例

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

支援的基本模型ID（`model`）列表與訓練類型（`training_type`）支援情況：

如果調優的模型不支援sft方法，調優任務將會失敗。

模型服務	模型代碼	CPT全參訓練（cpt）	SFT全參訓練（sft）	SFT高效訓練（sft_efficient）	DPO全參訓練（dpo_full）	DPO高效訓練（dpo_lora）
Qwen3.6-Flash-2026-04-16	qwen3.6-flash-2026-04-16	×	支援	×	×	×

Qwen3.5-27B	qwen3.5-27b	×	支援	支援	×	×
Qwen3.5-9B	qwen3.5-9b	×	支援	支援	×	×
Qwen3.5-Flash-2026-02-23	qwen3.5-flash-2026-02-23	×	支援	×	×	×

Qwen3-32B	qwen3-32b	支援	支援	支援	支援	支援
Qwen3-30B-A3B-Instruct-2507	qwen3-30b-a3b-instruct-2507	支援	支援	支援	×	×
Qwen3-14B	qwen3-14b	×	支援	支援	支援	支援
Qwen3-8B	qwen3-8b	×	支援	支援	支援	支援
Qwen3-1.7B	qwen3-1.7b	支援	支援	支援	支援	支援
Qwen3-0.6B	qwen3-0.6b	支援	支援	支援	支援	支援

Qwen2.5-72B-Instruct	qwen2.5-72b-instruct	支援	支援	支援	支援	支援
Qwen2.5-32B-Instruct	qwen2.5-32b-instruct	支援	支援	支援	支援	支援
Qwen2.5-14B-Instruct	qwen2.5-14b-instruct	支援	支援	支援	支援	支援
Qwen2.5-7B-Instruct	qwen2.5-7b-instruct	支援	支援	支援	支援	支援

千問-Plus-Character-2025-11-06	qwen-plus-character-2025-11-06	×	支援	支援	支援	支援

`hyper_parameters`內支援的設定

不同模型支援的參數及其預設值不同，請前往控制台選擇相同的模型和訓練方式查看實際預設值。

參數名稱	推薦設定	類型	超參作用
`n_epochs` （迴圈次數）【必填】	資料量 < 10,000, 3~5次資料量 > 10,000, 1~2次	Integer	模型遍曆訓練的次數，請根據模型調優實際使用經驗進行調整。模型訓練迴圈次數越多，訓練時間越長，訓練費用越高。
`learning_rate` （學習率）	使用百鍊推薦的預設值	Float	控制模型修正權重的強度。學習率設定得太高，模型參數會劇烈變化，導致調優後的模型表現不一定更好，甚至變差；學習率太低，調優後的模型表現不會有太大變化。
`freeze_vit` （是否凍結視覺主幹網路）	根據需求調整	Boolean	用於凍結視覺主幹網路的參數，使其在訓練過程中不更新權重。僅適用於千問-VL（視覺理解）模型。警告只有 freeze_vit 設定為“true”時，模型才能進行按 Token 用量計費。
`batch_size` （批次大小）【必填】	使用百鍊推薦的預設值	Integer	一次性送入模型進行訓練的資料條數，參數過小會顯著延長訓練時間。不同模型的預設值不同，請前往控制台查看。
`eval_steps` （驗證步數）	根據需求調整	Integer	訓練階段針對模型的驗證間隔步長，用於階段性評估模型訓練準確率、訓練損失。該參數影響模型調優進行時的 Validation Loss 和 Validation Token Accuracy 的顯示頻率。
`logging_steps` （日誌顯示步數）	根據需求調整	Integer	調優日誌列印的步數。
`lr_scheduler_type` （學習率調整策略）	推薦`linear`/`Inverse_sqrt`	String	在模型訓練中動態調整學習率的策略。各策略詳情請參考在控制台進行模型調優。
`max_length` （序列長度）【必填】	8192	Integer	指的是單條訓練資料 token 支援的最大長度。如果單條資料 token 長度超過設定值，調優會直接丟棄該條資料，不進行訓練。字元與 token 之間的關係請參考Token和字串之間怎麼換算
`max_split_val_dataset_sample` （驗證集資料最大數量）	使用百鍊推薦的預設值	Integer	當不設定`"validation_file_ids"`時，阿里雲百鍊自動分割的驗證集最多隻有1000條。當設定了`"validation_file_ids"`時，該參數無效。
`split` （訓練集在訓練檔案中佔比）	使用百鍊推薦的預設值	Float	當不設定`"validation_file_ids"`時，阿里雲百鍊會自動把訓練檔案中的80%作為訓練集，20%作為驗證集。當設定了`"validation_file_ids"`時，該參數無效。
`warmup_ratio` （學習率預熱比例）	使用百鍊推薦的預設值	Float	學習率預熱佔用總的訓練過程的比例。學習率預熱是指學習率在訓練開始後由一個較小值線性遞增至學習率設定值。該參數主要是限制模型參數在訓練初始階段的變化幅度，從而協助模型更穩定地進行訓練。比例過大效果與過低的學習率相同，會導致調優後的模型表現不會有太大變化。比例過小效果與過高的學習率相同，可能導致調優後的模型表現不一定更好，甚至變差。該參數僅對學習率調整策略“Constant”無效。
`weight_decay` （權重衰減）	使用百鍊推薦的預設值	Float	L2正則化強度。L2正則化能在一定程度上保持模型的通用能力。數值過大會導致模型調優效果不明顯。
高效微調（支援`efficient_sft`、`dpo_lora`）參數說明當對一個已經高效微調後的模型進行二次高效微調時，`lora_rank`、`lora_alpha`、`lora_dropout`三個參數必須保持一致。
`lora_rank` （LoRA秩值）	64	Integer	LoRA訓練中的低秩矩陣的秩大小。秩越大調優效果越好，但訓練會略慢。
`lora_alpha` （LoRA阿爾法）	使用百鍊推薦的預設值	Integer	用於控制原模型權重與LoRA的低秩修正項之間的結合縮放係數。較大的Alpha值會給予LoRA修正項更多權重，使得模型更加依賴於微調任務的特定資訊；而較小的Alpha值則會讓模型更傾向於保留原始預訓練模型的知識。
`lora_dropout` （LoRA丟棄率）	使用百鍊推薦的預設值	Float	LoRA訓練中的低秩矩陣值的丟棄率。使用推薦數值能增強模型通用化能力。數值過大會導致模型微調效果不明顯。
混合訓練（支援`efficient_sft`、`sft`）參數
`data_augmentation` （是否開啟混合訓練）	根據模型的使用情境混合	Boolean	開啟後，訓練資料將與百鍊提供的通用資料集（多領域/多行業/多情境）混合： - 效果：提升訓練效果，避免模型能力退化。 - 計費：混合資料計入總訓練Token，按標準計費。
`augmentation_ratio` （設定混合倍率）	根據模型的使用情境混合	String	格式要求：與`augmentation_types`完全對應樣本：`"0.1,0.05,0.15"`（分別對應`augmentation_types`列出的三種資料集）含義：按訓練資料量的`10%/5%/15%`隨機抽取混合範圍：`0.0 ~ 2.0`
模型參數快照發布（僅支援`efficient_sft`、`sft`）參數
`save_strategy` （快照儲存策略）	可以設定為 `epoch`或`steps`。設定為`steps`時，可以通過設定`save_steps`參數，調整儲存間隔。	String	設定調優過程中，儲存模型參數快照（Checkpoint）的儲存間隔和儲存數量上限。
`save_steps` （儲存步數）	如果需要手動修改，建議設定為`eval_steps`參數的整數倍。	Integer	設定每訓練多少步儲存一次模型參數快照（Checkpoint）。
`save_total_limit` （快照儲存數量上限）	10	Integer	限制最多儲存多少個模型參數快照（Checkpoint）用於發布。

查詢調優任務詳情

使用建立任務時返回的job_id來查詢任務狀態。

HTTP

curl 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

輸入參數

欄位	類型	傳參方式	必選	描述
job_id	String	Path Parameter	是	要查詢的調優任務的ID。

返回成功範例

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

任務狀態	含義
PENDING	訓練待開始。
QUEUING	訓練正在排隊（同時只有一個訓練任務可以進行）
RUNNING	訓練進行中中。
CANCELING	訓練正在取消中。
SUCCEEDED	訓練成功。
FAILED	訓練失敗。
CANCELED	訓練已經取消。

說明

訓練成功後，finetuned_output指的是調優成功後的模型 ID，可用於模型部署。

擷取調優任務日誌

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'

可通過 offset 和 line 兩個參數擷取特定行數區間的日誌。 Offset 用於設定日誌輸出開始的位置；line 用於設定日誌最多輸出多少行。

返回結果範例：

{
    "request_id":"1100d073-4673-47df-aed8-c35b3108e968",
    "output":{
        "total":57,
        "logs":[
            "{輸出調優日誌1}",
            "{輸出調優日誌2}",
            ...
            ...
            ...
        ]
    }
}

查詢與發布模型參數快照

僅 SFT微調訓練（efficient_sft、sft）支援儲存和發布其中間狀態的模型參數快照（Checkpoint）。

查詢調優任務的參數快照列表

curl 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>/checkpoints' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

輸入參數

欄位	類型	傳參方式	必選	描述
job_id	String	Path Parameter	是	要查詢的調優任務的ID。

返回成功範例

說明

checkpoint指的是 Checkpoint ID，用於在模型發布（可選） API 中指定要發布的快照；model_name指的是模型 ID，可用於模型部署。（finetuned_output 輸出的是最後一個 checkpoint 的 model_name）

{
    "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）	含義
PENDING	快照（Checkpoint）待發布，需要使用模型發布 API 發布後才可以進行模型部署&調用。
PROCESSING	快照（Checkpoint）發布中。
SUCCEEDED	快照（Checkpoint）發布成功。可直接進行模型部署&調用。
FAILED	快照（Checkpoint）發布失敗。

模型發布（可選）

說明

在百鍊平台上，模型調優完成後可以匯出參數快照，匯出後才能基於此版本的參數快照在百鍊上進行模型部署。

匯出的參數快照儲存在雲端儲存中，暫不支援訪問或下載。

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'

輸入參數

欄位	類型	傳參方式	必選	描述
job_id	String	Path Parameter	是	要查詢的調優任務的 ID。
checkpoint_id	String	Path Parameter	是	要發布的 Checkpoint ID。
model_name	String	Path Parameter	是	發布後期望的模型 ID。

發布任務成功返回範例

{
    "request_id": "ed3faa41-6be3-4271-9b83-941b23680537",
    "output": true
}

由於發布任務是非同步執行的，請使用查詢快照列表 API 觀察快照發布狀態。

模型調優的更多操作

列舉調優工作清單

HTTP

curl 'https://dashscope.aliyuncs.com/api/v1/fine-tunes' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

中止調優任務

智能終止正在訓練中的調優任務

HTTP

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'

刪除調優任務

無法刪除正在訓練中的調優任務

HTTP

curl --request DELETE 'https://dashscope.aliyuncs.com/api/v1/fine-tunes/<job_id>' \
--header 'Authorization: Bearer '${DASHSCOPE_API_KEY} \
--header 'Content-Type: application/json'

模型部署&調用

模型部署

請前往模型部署控制台部署模型。

模型調用

當模型部署狀態為RUNNING時，可以像調用其他模型一樣使用調優後的模型。

也可以前往模型部署控制台介面擷取模型code。

更多使用方法和參數設定請前往DashScope API 參考。

HTTP

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": "<替換為部署任務成功後的模型執行個體 ID>",
    "input":{
        "messages":[
            {
                "role": "user",
                "content": "你是誰？"
            }
        ]
    },
    "parameters": {
        "result_format": "message"
    }
}'

前提條件

上傳調優檔案

準備調優檔案

SFT 訓練集

將調優檔案上傳至阿里雲百鍊

OpenAI 相容 - FIle 介面

模型調優

建立調優任務

HTTP

輸入參數

返回範例

支援的基本模型ID（model）列表與訓練類型（training_type）支援情況：

hyper_parameters內支援的設定

查詢調優任務詳情

HTTP

輸入參數

返回成功範例

擷取調優任務日誌

HTTP

查詢與發布模型參數快照

查詢調優任務的參數快照列表

模型發布（可選）

模型調優的更多操作

列舉調優工作清單

中止調優任務

刪除調優任務

模型部署&調用

模型部署

模型調用

支援的基本模型ID（`model`）列表與訓練類型（`training_type`）支援情況：

`hyper_parameters`內支援的設定