建立調優任務

建立一個新的模型微調訓練任務。

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

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_file_ids":[
              "86a9fe7f-dd77-43b0-9834-2170e12339ec",
              "03ead352-6190-4328-8016-61821c23d4fc"
          ],
          "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",
          "finetuned_output_suffix":"suffix"
      }'

輸入參數

欄位	必選	類型	傳參方式	參數說明
training_file_ids	是	Array	Body	調優集檔案ID列表，檔案ID由檔案管理 API 產生。
validation_file_ids	否	Array	Body	測試集檔案ID列表，檔案ID由檔案管理 API 產生。
model	是	String	Body	用於調優的基本模型 ID；或其他調優任務產出的模型ID（對已經調優了的模型進行再次調優）。
hyper_parameters	否	Map	Body	調優時的超參列表。不同模型支援的參數集合及其預設值不同，請在控制台選擇相同的模型和調優方式查看實際預設值。文本產生 / 視覺理解等模型：使用 `n_epochs`（迴圈次數）、`batch_size`（批次大小）、`max_length`（序列長度）等參數，其中 `n_epochs`、`batch_size`、`max_length` 影響調優費用，必須填寫。各參數詳情請參見 hyper_parameters 參數說明。 CosyVoice 語音合成模型（僅 `cosyvoice-v3-flash`）：8 個 LM / FM 超參全部必填。各參數詳情請參見下方「CosyVoice 語音合成模型 hyper_parameters」。
training_type	否	String	Body	調優方法，可選值為：`sft`、`efficient_sft`。
job_name	否	String	Body	調優任務名稱
model_name	否	String	Body	調優完成後的模型名稱

`hyper_parameters`內支援的設定

參數名稱	預設設定	推薦設定	類型	超參作用
`n_epochs` （迴圈次數）	1	結合調優效果調整	Integer	模型遍曆訓練的次數，請根據模型調優實際使用經驗進行調整。模型訓練迴圈次數越多，訓練時間越長，訓練費用越高。
`learning_rate` （學習率）	`sft`: 1e-5 量級 `efficient_sft`:1e-4 量級具體數值隨模型選擇變化。	使用百鍊推薦的預設值	Float	控制模型修正權重的強度。學習率設定得太高，模型參數會劇烈變化，導致調優後的模型表現不一定更好，甚至變差；學習率太低，調優後的模型表現不會有太大變化。
`freeze_vit` （是否凍結視覺主幹網路）	true	根據需求調整	Boolean	用於凍結視覺主幹網路的參數，使其在訓練過程中不更新權重。僅適用於千問-VL（視覺理解）模型。
`batch_size` （批次大小）	具體數值隨模型選擇變化。模型越大，預設 batch_size 越小。	使用百鍊推薦的預設值	Integer	一次性送入模型進行訓練的資料條數，參數過小會顯著延長訓練時間，推薦使用預設值。
`eval_steps` （驗證步數）	50	根據需求調整	Integer	訓練階段針對模型的驗證間隔步長，用於階段性評估模型訓練準確率、訓練損失。該參數影響模型調優進行時的 Validation Loss 和 Validation Token Accuracy 的顯示頻率。
`logging_steps` （日誌顯示步數）	5	根據需求調整	Integer	調優日誌列印的步數。
`lr_scheduler_type` （學習率調整策略）	`cosine`	推薦`linear`/`Inverse_sqrt`	String	在模型訓練中動態調整學習率的策略。支援設定為：
`max_length` （序列長度）	2048	8192	Integer	指的是單條訓練資料 token 支援的最大長度。如果單條資料 token 長度超過設定值，調優會直接丟棄該條資料，不進行訓練。
`max_split_val_dataset_sample` （驗證集資料最大數量）	1000	使用百鍊推薦的預設值	Integer	當不設定`"validation_file_ids"`時，阿里雲百鍊自動分割的驗證集最多隻有1000條。當設定了`"validation_file_ids"`時，該參數無效。
`split` （訓練集在訓練檔案中佔比）	0.8	使用百鍊推薦的預設值	Float	當不設定`"validation_file_ids"`時，阿里雲百鍊會自動把訓練檔案中的80%作為訓練集，20%作為驗證集。當設定了`"validation_file_ids"`時，該參數無效。
`warmup_ratio` （學習率預熱比例）	0.05	使用百鍊推薦的預設值	Float	學習率預熱佔用總的訓練過程的比例。學習率預熱是指學習率在訓練開始後由一個較小值線性遞增至學習率設定值。該參數主要是限制模型參數在訓練初始階段的變化幅度，從而協助模型更穩定地進行訓練。比例過大效果與過低的學習率相同，會導致調優後的模型表現不會有太大變化。比例過小效果與過高的學習率相同，可能導致調優後的模型表現不一定更好，甚至變差。該參數僅對學習率調整策略“Constant”無效。
`weight_decay` （權重衰減）	0.1	使用百鍊推薦的預設值	Float	L2正則化強度。L2正則化能在一定程度上保持模型的通用能力。數值過大會導致模型調優效果不明顯。
高效微調（支援`efficient_sft`）參數說明當對一個已經高效微調後的模型進行二次高效微調時，`lora_rank`、`lora_alpha`、`lora_dropout`三個參數必須保持一致。
`lora_rank` （LoRA秩值）	8	64	Integer	LoRA訓練中的低秩矩陣的秩大小。秩越大調優效果越好，但訓練會略慢。
`lora_alpha` （LoRA阿爾法）	32	使用百鍊推薦的預設值	Integer	用於控制原模型權重與LoRA的低秩修正項之間的結合縮放係數。較大的Alpha值會給予LoRA修正項更多權重，使得模型更加依賴於微調任務的特定資訊；而較小的Alpha值則會讓模型更傾向於保留原始預訓練模型的知識。
`lora_dropout` （LoRA丟棄率）	0.1	使用百鍊推薦的預設值	Float	LoRA訓練中的低秩矩陣值的丟棄率。使用推薦數值能增強模型通用化能力。數值過大會導致模型微調效果不明顯。
模型參數快照發布參數
`save_strategy` （快照儲存策略）	`epoch`	可以設定為 `epoch`或`steps`。設定為`steps`時，可以通過設定`save_steps`參數，調整儲存間隔。	String	設定調優過程中，儲存模型參數快照（Checkpoint）的儲存間隔和儲存數量上限。
`save_steps` （儲存步數）	50	如果需要手動修改，建議設定為`eval_steps`參數的整數倍。	Integer	設定每訓練多少步儲存一次模型參數快照（Checkpoint）。
`save_total_limit` （快照儲存數量上限）	1	10	Integer	限制最多儲存多少個模型參數快照（Checkpoint）用於匯出。

CosyVoice 語音合成模型 hyper_parameters

僅適用於 cosyvoice-v3-flash 模型，與文本產生模型的 n_epochs、batch_size、max_length 不可混用。

參數	必選	推薦	取值範圍	說明
lm_max_epoch	是	60	[1, 2147483647]	LM 調優輪次（epoch 數）。
lm_step	是	5	[1, 2147483647]	LM 儲存 checkpoint 的步長（每多少個 epoch 儲存一次）。
lm_num	是	3	[1, 2147483647]	LM 保留的 checkpoint 數量上限。
lm_batch_size	是	1000	[1, 2147483647]	LM 批次大小（batch size）。
fm_max_epoch	是	100	[1, 2147483647]	FM 調優輪次（epoch 數）。
fm_step	是	10	[1, 2147483647]	FM 儲存 checkpoint 的步長（每多少個 epoch 儲存一次）。
fm_num	是	3	[1, 2147483647]	FM 保留的 checkpoint 數量上限。
fm_batch_size	是	2000	[1, 2147483647]	FM 批次大小（batch size）。

返回範例

{
          "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": [
                  "976bd01a-f30b-4414-86fd-50c54486e3ef"
              ],
              "validation_file_ids": [
      
              ],
              "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"
          }
      }

返回參數

參數名稱	類型	參數說明
request_id	String	本次請求的ID。
output	Object	本次調優任務的詳細資料。
output.job_id	String	本次調優的任務ID，可用於查詢訓練任務詳情、查詢訓練日誌、取消訓練任務、刪除訓練任務等介面。建置規則：`ft-{yyyyMMddHHmm}-{4位uuid}`。
output.jobs_name	String	同`output.job_id`。
output.status	String	本次調優任務的狀態。
output.model	String	調優任務使用的模型ID。
output.base_model	String	調優任務使用的模型對應的基本模型ID。比如：調優任務`ft-202410291653-1c7f`使用的基本模型是`qwen3-14b`。
output.training_file_ids	Array	調優檔案ID列表。
output.validation_file_ids	Array	驗證檔案ID列表。
output.hyper_parameters	Object	顯性聲明過的超參表。
output.training_type	String	調優方法。
output.create_time	String	調優任務建立時間。
output.workspace_id	String	調優任務所屬的業務空間ID。
output.user_identity	String	該調優任務隸屬的主帳號UID。
output.modifier	String	對該調優任務進行最後一次操作的帳號UID。比如：某個子帳號取消了該任務，該子帳號UID會顯示在這裡。
output.creator	String	該調優任務建立人UID。
output.group	String	模型調優的任務類型。

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

請求錯誤碼說明

請求異常時返回

欄位	類型	描述	樣本值
code	String	錯誤碼。	NotFound
request_id	String	本次請求的系統唯一碼。	6332fb02-3111-43f0-bf79-f9e8c5ffa7f9
message	String	錯誤資訊。	Not Found!

請求異常樣本

{
        "code": "NotFound",
        "request_id": "BE213CDD-8A5C-59EE-9A67-055EAB0CB59B",
        "message": "Not Found!"
      }

錯誤碼列表

HTTP狀態代碼	錯誤碼	錯誤資訊舉例	含義	處理方式
400	InvalidParameter	Missing training files	參數錯誤，缺少參數或者參數格式問題等。	根據錯誤資訊，修正您的參數。
400	UnsupportedOperation	The fine-tune job can not be deleted because it is succeeded,failed or canceled	當資源處於特定狀態時，無法對其進行操作。	待要操作的資源到達可操作狀態時再進行操作。
404	NotFound	Not found!	要查詢/操作的資源不存在。	檢查要查詢/操作的資源ID是否錯誤。
409	Conflict	Model instance xxxxx already exists, please specify a suffix	已存在deployed_model名為xxxxx的部署執行個體，需要指定尾碼進行區分。	為部署指定唯一的尾碼。
429	Throttling	Too many fine-tune job in running, please retry later. Only 20 fine-tune job in running or succeeded allowed per user.	資源的建立觸發平台限制。	刪除不再使用的模型。
500	InternalError	Internal server error!	內部錯誤。	記錄 request_id，通過工單聯絡阿里雲工程師進行排查。

建立調優任務

輸入參數

hyper_parameters內支援的設定

返回範例

返回參數

請求錯誤碼說明

`hyper_parameters`內支援的設定