Skip to main content
千問模型調優

使用 API 或命令列進行模型調優

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

前提條件

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

上傳調優檔案

準備調優檔案

  • SFT 訓練集
SFT ChatML(Chat Markup Language)格式訓練資料,支援多輪對話和多種角色設定。
不支援OpenAI 的nameweight參數,所有的 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格式樣本.jsonlSFT-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 介面
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://dashscope-intl.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())
使用限制:
  • 單個檔案大小最大為300MB
  • 所有的有效檔案(未刪除)總使用空間配額為100GB
  • 所有的有效檔案(未刪除)總數量配額為10000個
  • 檔案儲存體沒有時間限制
通過 API 上傳的調優檔案,在百鍊控制台模型調優頁面與 API 呼叫中均可見可用。

模型調優

建立調優任務

  • 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_datasets":[
        {"data_source_type":"file_id","file_id":"<替換為訓練資料集的file_id1>"},
        {"data_source_type":"oss_mount","mount_storage":{"region":"cn-beijing","bucket":"example_bucket","file_path":"dataset/data.jsonl"}}
    ],
    "validation_datasets":[
        {"data_source_type":"file_id","file_id":"<替換為測試資料集的file_id>"},
        {"data_source_type":"oss_mount","mount_storage":{"region":"cn-beijing","bucket":"example_bucket","file_path":"dataset/val.jsonl"}}
    ],
    "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"
}'
使用 OSS 掛載方式載入資料集時,需將未經壓縮的資料集檔案夾整體上傳到 OSS Bucket,不支援 zip 檔案。MountStorage 的 file_path 指定資料集的 data.jsonl 檔案路徑;對包含多個檔案的資料集(如 data.jsonl 和圖片/視頻檔案同目錄),只需指定 data.jsonl 的路徑,無需指定其他檔案。掛載前需授權百鍊服務訪問您的 OSS 資料。OSS Bucket 所屬地區支援北京(cn-beijing)和新加坡(ap-southeast-1)。

輸入參數

欄位

必選

類型

傳參方式

描述

training_datasets

Array of Dataset

Body

訓練資料集列表。

validation_datasets

Array of Dataset

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": [],
        "validation_file_ids": [],
        "training_datasets": [
            {"data_source_type": "file_id", "file_id": "9e9ffdfa-c3bf-436e-9613-6f053c66aa6e"}
        ],
        "validation_datasets": [],
        "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
    }
}
支援的模型
  • 新加坡
  • 華北二(北京)
  • 文本產生
  • 視覺理解(千問VL)

模型名稱

模型代碼

SFT全參訓練(sft)

SFT高效訓練(efficient_sft)

Qwen3.5-27B

qwen3.5-27b

支援

支援

Qwen3.5-9B

qwen3.5-9b

支援

支援

Qwen3-14B

qwen3-14b

×

支援

調優方法對比

特性

CPT(持續預訓練)

SFT (監督微調)

DPO (直接偏好最佳化)

一句話總結

補知識注入領域知識

學做事學會遵循指令

做得更好對齊人類偏好

輸入資料

1000萬+ Token

無標籤的領域文本

1000+ 條

高品質的“問-答”對

100+ 組

同一指令下的“更好-更差”回答對

核心目標

領域適應,學習專業詞彙和事實

教會模型對話格式和任務執行能力

使模型輸出更符合人類價值觀和偏好

學習方式

自監督學習(預測下一個詞

監督學習模仿標準答案

直接偏好學習增大好答案機率,降低壞答案機率

模型階段

通常在 SFT 之前

CPT 之後,DPO 之前

通常在 SFT 之後,作為對齊的最後一步

訓練模式對比

全參訓練

高效訓練 (LoRA,推薦)

適用情境

• 需要模型學習新能力

• 追求全域效果最優

• 最佳化模型特定情境下的效果

• 對訓練時間和成本敏感的情境

訓練時間

較長,收斂速度較慢。

較短,收斂速度快。

不同模型支援的參數及其預設值不同,請前往控制台選擇相同的模型和訓練方式查看實際預設值
參數名稱推薦設定類型超參作用
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_sqrtString在模型訓練中動態調整學習率的策略。各策略詳情請參考在控制台進行模型調優
max_length(序列長度)【必填】8192Integer指的是單條訓練資料 token 支援的最大長度。如果單條資料 token 長度超過設定值,調優會直接丟棄該條資料,不進行訓練。字元與 token 之間的關係請參考Token和字串之間怎麼換算
max_split_val_dataset_sample(驗證集資料最大數量)使用百鍊推薦的預設值Integer當不設定"validation_datasets"時,阿里雲百鍊自動分割的驗證集最多隻有1000條。當設定了"validation_datasets"時,該參數無效。
split(訓練集在訓練檔案中佔比)使用百鍊推薦的預設值Float當不設定"validation_datasets"時,阿里雲百鍊會自動把訓練檔案中的80%作為訓練集,20%作為驗證集。當設定了"validation_datasets"時,該參數無效。
warmup_ratio(學習率預熱比例)使用百鍊推薦的預設值Float學習率預熱佔用總的訓練過程的比例。學習率預熱是指學習率在訓練開始後由一個較小值線性遞增至學習率設定值。該參數主要是限制模型參數在訓練初始階段的變化幅度,從而協助模型更穩定地進行訓練。比例過大效果與過低的學習率相同,會導致調優後的模型表現不會有太大變化。比例過小效果與過高的學習率相同,可能導致調優後的模型表現不一定更好,甚至變差。
該參數僅對學習率調整策略“Constant”無效。
weight_decay(權重衰減)使用百鍊推薦的預設值FloatL2正則化強度。L2正則化能在一定程度上保持模型的通用能力。數值過大會導致模型調優效果不明顯。
高效微調(支援efficient_sftdpo_lora)參數
當對一個已經高效微調後的模型進行二次高效微調時,lora_ranklora_alphalora_dropout三個參數必須保持一致。
lora_rank(LoRA秩值)64IntegerLoRA訓練中的低秩矩陣的秩大小。秩越大調優效果越好,但訓練會略慢。
lora_alpha(LoRA阿爾法)使用百鍊推薦的預設值Integer用於控制原模型權重與LoRA的低秩修正項之間的結合縮放係數。較大的Alpha值會給予LoRA修正項更多權重,使得模型更加依賴於微調任務的特定資訊;而較小的Alpha值則會讓模型更傾向於保留原始預訓練模型的知識。
lora_dropout(LoRA丟棄率)使用百鍊推薦的預設值FloatLoRA訓練中的低秩矩陣值的丟棄率。使用推薦數值能增強模型通用化能力。數值過大會導致模型微調效果不明顯。
模型參數快照發布(僅支援efficient_sftsft)參數
save_strategy(快照儲存策略)可以設定為 epochsteps
  • 設定為steps時,可以通過設定save_steps參數,調整儲存間隔。
String設定調優過程中,儲存模型參數快照(Checkpoint)的儲存間隔和儲存數量上限。
save_steps(儲存步數)如果需要手動修改,建議設定為eval_steps參數的整數倍。Integer設定每訓練多少步儲存一次模型參數快照(Checkpoint)。
save_total_limit(快照儲存數量上限)10Integer限制最多儲存多少個模型參數快照(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": [],
        "validation_file_ids": [],
        "training_datasets": [
            {"data_source_type": "file_id", "file_id": "9e9ffdfa-c3bf-436e-9613-6f053c66aa6e"}
        ],
        "validation_datasets": [],
        "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_sftsft)支援儲存和發布其中間狀態的模型參數快照(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)發布失敗。

模型發布(可選)

在百鍊平台上,模型調優完成後可以匯出參數快照,匯出後才能基於此版本的參數快照在百鍊上進行模型部署。匯出的參數快照儲存在雲端儲存中,暫不支援訪問或下載。
URL 中的 <checkpoint_id> 取值來自上一步查詢快照列表介面返回的 checkpoint 欄位(如 checkpoint-20),而非 full_name 或其他含 job_id 首碼的欄位值。
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。取值為查詢快照列表介面返回的 checkpoint 欄位值(如 checkpoint-20),不含 job_id 首碼。

model_name

String

Path Parameter

發布後期望的模型 ID。

發布任務成功返回範例
{
    "request_id": "ed3faa41-6be3-4271-9b83-941b23680537",
    "output": true
}
由於發布任務是非同步執行的,請使用查詢快照列表 API 觀察快照發布狀態。

模型調優的更多操作

列舉調優工作清單

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

中止調優任務

智能終止正在訓練中的調優任務
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'

刪除調優任務

無法刪除正在訓練中的調優任務
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 參考
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"
    }
}'
Token Plan
模型體驗
  • 音樂產生
用量統計與效能監控
資產中心
服務支援