建立一個映像產生的模型微調訓練任務。資料集支援通過API上傳資料集或OSS掛載。
適用範圍
- 適用地區：本文描述的功能僅在新加坡地區可用，且必須使用該地區的API Key。
- 開通帳號許可權：若使用阿里雲子帳號（RAM使用者），需要為子帳號授予模型調用、訓練和部署許可權。
- 配置環境變數：已成功擷取 API Key，並配置到環境變數。
- 準備工作：已閱讀映像產生模型調優，瞭解支援微調的模型、微調步驟、資料格式以及計費說明。
建立微調任務
- 新加坡
POST https://dashscope-intl.aliyuncs.com/api/v1/fine-tunesWindows CMD 請將$DASHSCOPE_API_KEY替換為%DASHSCOPE_API_KEY%，PowerShell請替換為$env:DASHSCOPE_API_KEY
請求參數要求標頭（Headers）Content-Typestring （必選）固定值：application/jsonAuthorization string （必選）API Key鑒權，格式為Bearer sk-xxxx。請求體（Request Body）modelstring （必選）指定微調所用的基準模型。
array[string] （條件必選）訓練集檔案ID數組，可傳入多個ID。與 training_datasets 二選一，若使用 training_datasets 則無需傳此參數。檔案ID通過上傳檔案 API 擷取。validation_file_ids array[string] （可選）驗證集檔案ID數組，可傳入多個ID。與 validation_datasets 二選一，若使用 validation_datasets 則無需傳此參數。若兩者均不提供，系統會從訓練集中自動劃分。檔案ID通過上傳檔案 API 擷取。training_type string （必選）微調類型，當前僅支援efficient_sft（LoRA高效微調）。hyper_parameters object （可選）超參數配置。初次訓練時，推薦使用預設的超參數。若模型效果不佳或訓練不收斂，可以嘗試調整 max_steps 或 learning_rate 等參數。
超參數屬性 max_steps int （必選）訓練總步數。控制訓練時間長度的核心參數。推薦值：800。max_steps 決定訓練迭代次數，max_token_length 決定每步處理的資料量。建議不少於 500 步以確保模型充分收斂；巨量資料集可適當增加步數。eval_steps int （必選）驗證間隔。推薦值：200。取值需≥0。訓練期間每隔多少個 steps 進行一次驗證評估，用於階段性評估模型訓練效果。同時儲存當前 step 的模型檔案。learning_rate float （必選）學習率。推薦值：3e-5。控制模型權重更新的幅度。過高可能導致模型變差，過低則變化不明顯。generation_type string （必選）產生模式。決定訓練資料格式和推理方式。可選值：
string （必選）訓練圖片的最大解析度。設定訓練集中圖片解析度的像素總數（寬×高）上限，系統僅對超過該值的圖片進行縮放處理，未超限的圖片保持原樣。建議三個解析度參數（max_pixels、max_token_length、val_img_size）保持一致。
string （必選）驗證圖產生解析度。訓練過程中驗證評估時產生圖片的目標解析度。可選值同 max_pixels。推薦值：文生圖 2k，圖生圖 1k。max_token_length string （必選）每步訓練的最大 Token 長度，影響單步計算量與計費。與 max_steps 共同控制訓練過程：max_steps 決定迭代次數，max_token_length 決定每步處理的資料量。可選值：
float （必選）梯度裁剪。推薦值：0.5。對所有可訓練參數做全域梯度範數裁剪的閾值，防止梯度爆炸。設為 -1 表示不裁剪。weight_decay float （必選）權重衰減。推薦值：0.02。AdamW 解耦式權重衰減係數，對所有可訓練參數生效，用於正則化防止過擬合。lora_rank int （必選）LoRA 低秩矩陣的維數。推薦值：32。該值決定了微調參數量的大小。數值越大，模型擬合能力越強，但訓練速度會變慢。取值必須為2n（如 16、32、64）。save_total_limit int （可選）Checkpoint 儲存數量上限。推薦值：10。限制最多儲存的模型數量。系統將始終只儲存訓練產生的最後 N 個 Checkpoint。split float （可選）訓練集劃分比例。推薦值：0.9。取值範圍為 (0, 1)。僅在未指定validation_file_ids或validation_datasets時生效。此參數用於從訓練集中自動按比例拆分出驗證集。例如，0.9表示90%訓練集，10%驗證集。Array of Dataset （條件必選）訓練集檔案清單。與 training_file_ids 二選一，若使用 training_file_ids 則無需傳此參數。
Dataset 結構 data_source_type string （必選）資料來源類型，可選值：
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 檔案。string （條件必選）資料來源類型為 file_id 時必填。檔案 ID，由上傳檔案 API 產生。Array of Dataset （可選）驗證集檔案清單。結構同training_datasets。與 validation_file_ids 二選一。若兩者均不提供，系統會從訓練集中自動劃分。job_name string （可選）調優任務名稱。model_name string （可選）調優完成後的模型名稱。 |
響應參數request_idstring請求的唯一識別碼。output object任務詳情。
屬性 job_id string模型微調任務唯一標識，用於查詢任務詳情、日誌、取消或刪除任務。建置規則：ft-{yyyyMMddHHmm}-{4位uuid}。job_name string模型微調任務名稱。status string微調訓練任務的狀態：
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阿里雲百鍊API Key所屬的業務空間ID。請參見擷取Workspace ID。user_identity string使用者標識，阿里雲帳號ID。creator string建立人的阿里雲帳號ID。modifier string修改人的阿里雲帳號ID。group string模型微調任務分組。max_output_cnt integer訓練期間最多儲存的 checkpoint 數量。等同於超參數 save_total_limit 的值。string錯誤碼。調用失敗時返回。請參見下方錯誤碼錶。message string錯誤詳情描述。調用失敗時返回。 |
重點關註： output.job_id（任務ID）、output.finetuned_output（微調後產出的新模型名稱）。 |
錯誤碼
如果調用失敗並返回報錯資訊，請參見下表進行排查。
HTTP 狀態代碼 | 錯誤碼 | 解決方案 |
|---|---|---|
400 | InvalidParameter | 參數錯誤，缺少參數或者參數格式問題等。根據錯誤資訊修正您的參數。 |
400 | UnsupportedOperation | 當資源處於特定狀態時，無法對其進行操作。待要操作的資源到達可操作狀態時再進行操作。 |
404 | NotFound | 要查詢/操作的資源不存在。檢查資源ID是否錯誤。 |
409 | Conflict | 已存在同名部署執行個體，需要指定尾碼進行區分。 |
429 | Throttling | 資源的建立觸發平台限制。刪除不再使用的模型。 |
500 | InternalError | 內部錯誤。記錄 request_id，通過工單聯絡阿里雲工程師進行排查。 |