建立調優任務

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

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_datasets":[
              {
                  "data_source_type":"file_id",
                  "file_id":"<替換為訓練資料集的檔案id>"
              },
              {
                  "data_source_type":"oss_mount",
                  "mount_storage":{
                      "region":"ap-southeast-1",
                      "bucket":"example_bucket",
                      "file_path":"dataset/data.jsonl"
                  }
              }
          ],
          "validation_datasets":[
              {
                  "data_source_type":"file_id",
                  "file_id":"<替換為驗證資料集的檔案id>"
              },
              {
                  "data_source_type":"oss_mount",
                  "mount_storage":{
                      "region":"ap-southeast-1",
                      "bucket":"example_bucket",
                      "file_path":"dataset/val.jsonl"
                  }
              }
          ],
          "hyper_parameters":{
              "n_epochs":1,
              "learning_rate":"1.6e-5",
              "batch_size":32,
              "split":0.8
          },
          "training_type":"sft",
          "finetuned_output_suffix":"suffix"
      }'

視頻產生模型

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/fine-tunes' \
--header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.7-i2v",
    "training_datasets": [
        {
            "data_source_type": "file_id",
            "file_id": "<替換為訓練資料集的檔案id>"
        },
        {
            "data_source_type": "oss_mount",
            "mount_storage": {
                "region": "ap-southeast-1",
                "bucket": "example_bucket",
                "file_path": "dataset/data.jsonl"
            }
        }
    ],
    "training_type": "efficient_sft",
    "hyper_parameters": {
        "n_epochs": 400,
        "batch_size": 1,
        "learning_rate": 2e-5,
        "split": 0.9,
        "max_split_val_dataset_sample": 5,
        "eval_epochs": 50,
        "max_pixels": 102400,
        "save_total_limit": 10,
        "lora_rank": 32,
        "lora_alpha": 32
    }
}'

映像產生模型

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/fine-tunes' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.7-image-pro",
    "training_datasets": [
        {
            "data_source_type": "file_id",
            "file_id": "<替換為訓練資料集的檔案id>"
        },
        {
            "data_source_type": "oss_mount",
            "mount_storage": {
                "region": "ap-southeast-1",
                "bucket": "example_bucket",
                "file_path": "dataset/data.jsonl"
            }
        }
    ],
    "validation_datasets": [
        {
            "data_source_type": "file_id",
            "file_id": "<替換為驗證資料集的檔案id>"
        },
        {
            "data_source_type": "oss_mount",
            "mount_storage": {
                "region": "ap-southeast-1",
                "bucket": "example_bucket",
                "file_path": "dataset/val.jsonl"
            }
        }
    ],
    "training_type": "efficient_sft",
    "hyper_parameters": {
        "learning_rate": 3e-5,
        "max_steps": 800,
        "eval_steps": 200,
        "max_token_length": "1k",
        "gradient_clip": 0.5,
        "weight_decay": 0.02,
        "max_pixels": "1k",
        "val_img_size": "1k",
        "generation_type": "t2i",
        "lora_rank": 32,
        "save_total_limit": 10
    }
}'

輸入參數

欄位	必選	類型	傳參方式	參數說明
training_datasets	是	Array of Dataset	Body	訓練集檔案清單。
validation_datasets	否	Array of Dataset	Body	測試集檔案清單。
model	是	String	Body	用於調優的基本模型 ID；或其他調優任務產出的模型ID（對已經調優了的模型進行再次調優）。視頻/映像產生模型支援以下 model 值：圖生視頻-基於首幀：`wan2.7-i2v`（推薦）、`wan2.6-i2v`、`wan2.5-i2v-preview`、`wan2.2-i2v-flash` 圖生視頻-基於首尾幀：`wan2.2-kf2v-flash` 映像產生（文生圖/圖生圖）：`wan2.7-image-pro`、`wan2.7-image`
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`。視頻/映像產生模型僅支援 `efficient_sft`（LoRA 高效微調）。
job_name	否	String	Body	調優任務名稱
model_name	否	String	Body	調優完成後的模型名稱

Dataset 結構

欄位	必選	類型	參數說明
data_source_type	是	String	資料來源類型，可選值： `oss_mount`（掛載 OSS 檔案） `file_id`（由檔案管理服務 API 上傳的檔案）
mount_storage	否	OSS 掛載結構	資料來源類型為 `oss_mount` 時必填。掛載檔案資訊。
file_id	否	String	資料來源類型為 `file_id` 時必填。檔案 ID，由檔案管理服務 API 產生。

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 檔案。

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_datasets"`時，阿里雲百鍊自動分割的驗證集最多隻有1000條。當設定了`"validation_datasets"`時，該參數無效。
`split` （訓練集在訓練檔案中佔比）	使用百鍊推薦的預設值	Float	當不設定`"validation_datasets"`時，阿里雲百鍊會自動把訓練檔案中的80%作為訓練集，20%作為驗證集。當設定了`"validation_datasets"`時，該參數無效。
`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`）參數
`save_strategy` （快照儲存策略）	可以設定為 `epoch`或`steps`。設定為`steps`時，可以通過設定`save_steps`參數，調整儲存間隔。	String	設定調優過程中，儲存模型參數快照（Checkpoint）的儲存間隔和儲存數量上限。
`save_steps` （儲存步數）	如果需要手動修改，建議設定為`eval_steps`參數的整數倍。	Integer	設定每訓練多少步儲存一次模型參數快照（Checkpoint）。
`save_total_limit` （快照儲存數量上限）	10	Integer	限制最多儲存多少個模型參數快照（Checkpoint）用於發布。

視頻產生（萬相）

僅適用於視頻產生模型（wan 系列）。若模型效果不佳或訓練不收斂，可以嘗試調整 n_epochs 或 learning_rate。建議總訓練步數不少於 800 步。

欄位	類型	必選	描述	推薦值
batch_size	int	是	批次大小。一次性送入模型進行訓練的資料條數。 wan2.7-i2v：推薦為 1。 wan2.6-i2v：推薦為 1。 wan2.5-i2v-preview：推薦為 4。 wan2.2-i2v-flash：推薦為 4。 wan2.2-kf2v-flash：推薦為 4。	以模型為準
n_epochs	int	是	訓練迴圈次數。steps = n_epochs × ⌈資料集大小 / batch_size⌉。建議總步數 ≥ 800。例如：資料集 5 條，batch_size=2，每輪步數=⌈5/2⌉=3，最小 n_epochs = 800/3 ≈ 267。	400
learning_rate	float	是	學習率。控制模型權重更新幅度。過高可能導致模型變差，過低則變化不明顯。	2e-5
eval_epochs	int	是	驗證間隔。取值需 ≥ `n_epochs/10`。每隔多少個 epoch 進行一次驗證評估並儲存 Checkpoint。	50
max_pixels	int	是	訓練視頻的最大解析度（像素總數 = 寬×高）。系統僅對超過該值的視頻進行縮放處理。 wan2.7-i2v：推薦 102400。範圍 36864～102400。 wan2.6-i2v：推薦 36864。範圍 16384～36864。 wan2.5-i2v-preview：推薦 36864。範圍 16384～36864。 wan2.2-i2v-flash：推薦 262144。範圍 65536～262144。 wan2.2-kf2v-flash：推薦 262144。範圍 65536～262144。	以模型為準
split	float	否	訓練集劃分比例。取值 (0,1)，僅在未指定 validation_datasets 時生效。	0.9
max_split_val_dataset_sample	int	否	自動劃分驗證集的最大樣本數。驗證集數量 = min(總數×(1−split), 此值)。	5
save_total_limit	int	否	Checkpoint 儲存數量上限。系統只儲存最後 N 個 Checkpoint。	10
lora_rank	int	否	LoRA 低秩矩陣維數。取值須為 2ⁿ（16/32/64）。	32
lora_alpha	int	否	LoRA 權重縮放係數。取值須為 2ⁿ（16/32/64）。	32

映像產生（萬相）

欄位	類型	必選	描述	推薦值
max_steps	int	是	訓練總步數。控制訓練時間長度的核心參數。max_steps 決定訓練迭代次數，max_token_length 決定每步處理的資料量。建議不少於 500 步以確保模型充分收斂；巨量資料集可適當增加步數。	800
eval_steps	int	是	驗證間隔。取值需≥0。訓練期間每隔多少個 steps 進行一次驗證評估，用於階段性評估模型訓練效果。同時儲存當前 step 的模型檔案。	200
learning_rate	float	是	學習率。控制模型權重更新的幅度。過高可能導致模型變差，過低則變化不明顯。推薦使用預設值。	3e-5
generation_type	string	是	產生模式。`"t2i"`：文生圖模式；`"i2i"`：圖生圖模式。決定訓練資料格式和推理方式。	t2i
max_pixels	string	是	訓練圖片的最大解析度。例如 "1k"、"2k"（1K 即 1024×1024，2K 即 2048×2048）。設定訓練集中圖片解析度的像素總數（寬×高）上限，系統僅對超過該值的圖片進行縮放處理，未超限的圖片保持原樣。建議三個解析度參數（max_pixels、max_token_length、val_img_size）保持一致。	文生圖："2k" 圖生圖："1k"
val_img_size	string	是	驗證圖產生解析度。例如 "1k"、"2k"（1K 即 1024×1024，2K 即 2048×2048）。訓練過程中驗證評估時產生圖片的目標解析度。	文生圖："2k" 圖生圖："1k"
max_token_length	string	是	每步訓練的最大 Token 長度。例如 "1k"、"2k"。與 max_steps 共同控制訓練過程：max_steps 決定迭代次數，max_token_length 決定每步處理的資料量。	文生圖："2k" 圖生圖："1k"
gradient_clip	float	是	梯度裁剪。對所有可訓練參數做全域梯度範數裁剪的閾值，防止梯度爆炸。設為 -1 表示不裁剪。	0.5
weight_decay	float	是	權重衰減。AdamW 解耦式權重衰減係數，對所有可訓練參數生效，用於正則化防止過擬合。	0.02
lora_rank	int	是	LoRA 低秩矩陣的維數。該值決定了微調參數量的大小。數值越大，模型擬合能力越強，但訓練速度會變慢。取值必須為 2ⁿ（如 16、32、64）。	32
save_total_limit	int	否	Checkpoint 儲存數量上限。限制最多儲存的模型數量。系統將始終只儲存訓練產生的最後 N 個 Checkpoint（N 為該參數值）。	10
split	float	否	訓練集劃分比例。取值範圍為 (0, 1)。僅在未指定 `validation_datasets` 時生效。此參數用於從訓練集中自動按比例拆分出驗證集。例如，0.9 表示 90% 訓練集，10% 驗證集。	0.9

max_token_length對應每步訓練的最大 Token 長度：

generation_type	max_token_length	L_max
t2i（文生圖）	1k	12,800
t2i（文生圖）	2k	23,220
i2i（圖生圖）	1k	23,220
i2i（圖生圖）	2k	32,000

返回範例

文本產生模型

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

視頻產生模型

重點關注 output.job_id（任務ID）和 output.finetuned_output（微調後產出的新模型名稱，用於部署）。

{
    "request_id": "0eb05b0c-02ba-414a-9d0c-xxxxxxxxx",
    "output": {
        "job_id": "ft-202511111122-xxxx",
        "job_name": "ft-202511111122-xxxx",
        "status": "PENDING",
        "finetuned_output": "wan2.5-i2v-preview-ft-202511111122-xxxx",
        "model": "wan2.5-i2v-preview",
        "base_model": "wan2.5-i2v-preview",
        "training_file_ids": [],
        "training_datasets": [
            {
                "data_source_type": "file_id",
                "file_id": "xxxxxxxxxxxx"
            }
        ],
        "validation_file_ids": [],
        "validation_datasets": [],
        "hyper_parameters": {
            "n_epochs": 400,
            "batch_size": 4,
            "learning_rate": 2.0E-5,
            "split": 0.9,
            "eval_epochs": 50
        },
        "training_type": "efficient_sft",
        "create_time": "2025-11-11 11:22:22"
    }
}

映像產生模型

重點關注 output.job_id（任務ID）和 output.finetuned_output（微調後產出的新模型名稱，用於部署）。

{
    "request_id": "0eb05b0c-02ba-414a-9d0c-xxxxxxxxx",
    "output": {
        "job_id": "ft-202606030110-xxxx",
        "job_name": "ft-202606030110-xxxx",
        "status": "PENDING",
        "finetuned_output": "wan2.7-image-pro-ft-202606030110-xxxx",
        "model": "wan2.7-image-pro",
        "base_model": "wan2.7-image-pro",
        "training_file_ids": [],
        "training_datasets": [
            {
                "data_source_type": "file_id",
                "file_id": "xxxxxxxxxxxx"
            }
        ],
        "validation_file_ids": [],
        "validation_datasets": [],
        "hyper_parameters": {
            "max_steps": 800,
            "learning_rate": 3.0E-5,
            "eval_steps": 200,
            "max_token_length": "1k",
            "max_pixels": "1k",
            "val_img_size": "1k",
            "generation_type": "t2i",
            "lora_rank": 32
        },
        "training_type": "efficient_sft",
        "create_time": "2026-06-03 01:10:47"
    }
}

返回參數

參數名稱	類型	參數說明
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	相容欄位，新任務始終返回空數組，請使用 output.training_datasets。
output.training_datasets	Array of Dataset	訓練資料集列表。
output.validation_file_ids	Array	相容欄位，新任務始終返回空數組，請使用 output.validation_datasets。
output.validation_datasets	Array of Dataset	測試資料集列表。
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	模型調優的任務類型。
output.finetuned_output	String	僅調優任務狀態為“SUCCEEDED”時出現，返回的是調優完成的模型ID。
output.end_time	String	調優任務結束時間，當任務狀態為“SUCCEEDED”、“FAILED”、“CANCELED”時出現。
output.usage	Integer	調優任務消耗的Token（count）數，計費計算公式請參考：計費項目。當任務狀態為“SUCCEEDED”、“CANCELED”時出現。
output.output_cnt	Integer	當前任務已產出的 Checkpoint 數量。僅對支援多 Checkpoint 輸出的模型（如 `cosyvoice-v3-flash`）返回。Checkpoint 詳細列表可通過 Checkpoint 管理介面擷取。
output.max_output_cnt	Integer	單次任務可產出的 Checkpoint 數量上限。`output_cnt` 超出上限的部分會按調優充分度截斷。僅對支援多 Checkpoint 輸出的模型返回。

任務狀態	含義
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，通過工單聯絡阿里雲工程師進行排查。