文本產生-建立調優任務 - Alibaba Cloud Model Studio

適用範圍

適用地區：本文描述的功能僅在新加坡地區可用，且必須使用該地區的API Key。
開通帳號許可權：若使用阿里雲子帳號（RAM使用者），需要為子帳號授予模型調用、訓練和部署許可權。
配置環境變數：已成功擷取 API Key，並配置到環境變數。
準備工作：已閱讀千問模型調優，瞭解支援微調的模型、微調步驟、資料格式以及計費說明。

建立微調任務

新加坡

POST https://dashscope-intl.aliyuncs.com/api/v1/fine-tunes

Windows CMD 請將$DASHSCOPE_API_KEY替換為%DASHSCOPE_API_KEY%，PowerShell請替換為 $env:DASHSCOPE_API_KEY

請求參數

要求標頭（Headers）

Content-Type string （必選）固定值：application/jsonAuthorization string （必選）API Key鑒權，格式為Bearer sk-xxxx。

請求體（Request Body）

model string （必選）用於調優的或其他調優任務產出的模型ID（對已經調優了的模型進行再次調優）。training_type string （可選）調優方法，可選值：

sft
efficient_sft

hyper_parameters object （可選）超參數設定。不同模型支援的參數集合及其預設值不同，請前往控制台選擇相同的模型和調優方式查看實際預設值。其中 n_epochs、batch_size、max_length 影響調優費用，必須填寫。

超參數屬性

n_epochs int （必選）訓練迴圈次數。模型遍曆訓練的次數，請根據模型調優實際使用經驗進行調整。

資料量 < 10,000：推薦 3~5 次。
資料量 > 10,000：推薦 1~2 次。

該參數影響訓練計費，迴圈次數越多，訓練時間越長，費用越高。

batch_size int （必選）批次大小。一次性送入模型進行訓練的資料條數，參數過小會顯著延長訓練時間。不同模型的預設值不同，請前往控制台查看。max_length int （必選）序列長度。推薦值：8192。單條訓練資料 token 支援的最大長度。如果單條資料 token 長度超過設定值，調優會直接丟棄該條資料，不進行訓練。字元與 token 之間的關係請參考Token和字串之間怎麼換算。learning_rate float （可選）學習率。推薦使用百鍊預設值。控制模型修正權重的強度。

學習率過高，模型參數會劇烈變化，可能導致模型表現變差。
學習率過低，模型表現不會有太大變化。

lr_scheduler_type string （可選）學習率調整策略。推薦 linear 或 inverse_sqrt。在模型訓練中動態調整學習率的策略。各策略詳情請參考學習率調整策略說明。split float （可選）訓練集在訓練檔案中的佔比。推薦使用百鍊預設值。未設定 validation_datasets 時，百鍊會自動把訓練檔案中的 80% 作為訓練集、20% 作為驗證集。設定了 validation_datasets 時該參數無效。max_split_val_dataset_sample int （可選）驗證集資料最大數量。推薦使用百鍊預設值。未設定 validation_datasets 時，自動分割的驗證集最多 1000 條。設定了 validation_datasets 時該參數無效。eval_steps int （可選）驗證步數。訓練階段針對模型的驗證間隔步長，用於階段性評估模型訓練準確率、訓練損失。該參數影響模型調優進行時的 Validation Loss 和 Validation Token Accuracy 的顯示頻率。logging_steps int （可選）日誌顯示步數。調優日誌列印的間隔步數。warmup_ratio float （可選）學習率預熱比例。推薦使用百鍊預設值。學習率預熱佔用總的訓練過程的比例。學習率預熱是指學習率在訓練開始後由一個較小值線性遞增至學習率設定值，協助模型更穩定地訓練。

比例過大：效果與過低的學習率相同，會導致調優後的模型表現不會有太大變化。
比例過小：效果與過高的學習率相同，可能導致調優後的模型表現不一定更好，甚至變差。

該參數僅對學習率調整策略 Constant 無效。

weight_decay float （可選）權重衰減（L2 正則化強度）。推薦使用百鍊預設值。能在一定程度上保持模型的通用能力，數值過大會導致調優效果不明顯。freeze_vit boolean （可選）是否凍結視覺主幹網路。用於凍結視覺主幹網路的參數，使其在訓練過程中不更新權重。僅適用於千問-VL（視覺理解）模型。

只有 freeze_vit 設定為 true 時，模型才能進行按 Token 用量計費。

lora_rank int （可選）LoRA 秩值。推薦值：64。LoRA 訓練中的低秩矩陣的秩大小。秩越大調優效果越好，但訓練會略慢。僅在 training_type 為 efficient_sft 或 dpo_lora 時生效。

當對一個已經高效微調後的模型進行二次高效微調時，lora_rank、lora_alpha、lora_dropout 三個參數必須保持一致。

lora_alpha int （可選）LoRA 縮放係數。推薦使用百鍊預設值。用於控制原模型權重與 LoRA 的低秩修正項之間的結合縮放係數。

較大的 Alpha 值會給予 LoRA 修正項更多權重，使得模型更加依賴於微調任務的特定資訊。
較小的 Alpha 值則會讓模型更傾向於保留原始預訓練模型的知識。

僅在 training_type 為 efficient_sft 或 dpo_lora 時生效。lora_dropout float （可選）LoRA 丟棄率。推薦使用百鍊預設值。LoRA 訓練中的低秩矩陣值的丟棄率。使用推薦數值能增強模型通用化能力，數值過大會導致模型微調效果不明顯。僅在 training_type 為 efficient_sft 或 dpo_lora 時生效。save_strategy string （可選）快照儲存策略。可設定為 epoch 或 steps。設定為 steps 時，可通過 save_steps 參數調整儲存間隔。僅在 training_type 為 efficient_sft 或 sft 時生效。save_steps int （可選）儲存步數。設定每訓練多少步儲存一次模型參數快照（Checkpoint）。建議設定為 eval_steps 的整數倍。僅在 training_type 為 efficient_sft 或 sft 時生效。save_total_limit int （可選）快照儲存數量上限。推薦值：10。限制最多儲存多少個模型參數快照（Checkpoint）用於發布。僅在 training_type 為 efficient_sft 或 sft 時生效。

training_datasets Array of Dataset （必選）訓練集檔案清單。

Dataset 結構

data_source_type string （必選）資料來源類型，可選值：

oss_mount（掛載 OSS 檔案）
file_id（由檔案管理服務 API 上傳的檔案）

mount_storage object （條件必選）資料來源類型為 oss_mount 時必填。OSS 掛載資訊。

屬性

region string （必選）要掛載的 OSS Bucket 所屬地區。支援北京（cn-beijing）和新加坡（ap-southeast-1）。bucket string （必選）要掛載的 OSS Bucket 名稱。file_path string （必選）要掛載的 OSS 檔案路徑（object key）。對包含多個檔案的資料集，使用其 data.jsonl 的檔案路徑。與使用 file_id 的方式不同，需要將未經壓縮的資料集檔案夾整體上傳到 OSS，不支援 zip 檔案。

file_id string （條件必選）資料來源類型為 file_id 時必填。檔案 ID，由上傳檔案 API 產生。

validation_datasets Array of Dataset （可選）測試集檔案清單。結構同training_datasets。job_name string （可選）調優任務名稱。model_name string （可選）調優完成後的模型名稱。

curl --location --request POST "https://dashscope-intl.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":"<替換為訓練資料集的檔案id>"
        }
    ],
    "validation_datasets":[
        {
            "data_source_type":"file_id",
            "file_id":"<替換為驗證資料集的檔案id>"
        }
    ],
    "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"
}'

返回參數

request_id string本次請求的ID。output object任務詳情。

屬性

job_id string模型微調任務唯一標識，用於查詢任務詳情、日誌、取消或刪除任務。建置規則：ft-{yyyyMMddHHmm}-{4位uuid}。job_name string模型微調任務名稱。status string微調訓練任務的狀態：

PENDING：訓練待開始。
QUEUING：訓練正在排隊（同一時間只能運行一個微調任務）。
RUNNING：訓練進行中中。
SUCCEEDED：訓練成功。
FAILED：訓練失敗。
CANCELED：訓練已取消。
CANCELING：訓練正在取消中。

finetuned_output string微調後產出的新模型ID。任務狀態為 SUCCEEDED 時返回。model string使用的基準模型。base_model string使用的基準模型。training_file_ids array相容舊版欄位，新任務始終返回空數組，請使用 training_datasets。training_datasets Array of Dataset訓練資料集列表。validation_file_ids array相容舊版欄位，新任務始終返回空數組，請使用 validation_datasets。validation_datasets Array of Dataset驗證資料集列表。若未指定驗證集，為空白數組。hyper_parameters object實際使用的超參數。training_type string模型微調的訓練方式。create_time string任務建立時間。end_time string任務結束時間。任務狀態為 SUCCEEDED、FAILED 或 CANCELED 時返回。usage integer微調任務消耗的 Token 數。計費計算公式請參考：計費說明。任務狀態為 SUCCEEDED 或 CANCELED 時返回。workspace_id string調優任務所屬的業務空間ID。user_identity string使用者標識，阿里雲帳號ID。creator string建立人的阿里雲帳號ID。modifier string修改人的阿里雲帳號ID。group string模型微調任務分組。

code string錯誤碼。調用失敗時返回。請參見下方錯誤碼錶。message string錯誤詳情描述。調用失敗時返回。

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

錯誤碼

如果調用失敗並返回報錯資訊，請參見下表進行排查。

HTTP 狀態代碼	錯誤碼	解決方案
400	InvalidParameter	參數錯誤，缺少參數或者參數格式問題等。根據錯誤資訊修正您的參數。
400	UnsupportedOperation	當資源處於特定狀態時，無法對其進行操作。待要操作的資源到達可操作狀態時再進行操作。
404	NotFound	要查詢/操作的資源不存在。檢查資源ID是否錯誤。
409	Conflict	已存在同名部署執行個體，需要指定尾碼進行區分。
429	Throttling	資源的建立觸發平台限制。刪除不再使用的模型。
500	InternalError	內部錯誤。記錄 request_id，通過工單聯絡阿里雲工程師進行排查。

下一步

調優為非同步作業，調用本介面後可通過查詢和管理調優任務介面查詢調優任務狀態。

​適用範圍

​建立微調任務

請求參數

要求標頭（Headers）

請求體（Request Body）

返回參數

​錯誤碼

​下一步

適用範圍

建立微調任務

錯誤碼

下一步