ファインチューニングジョブの作成

モデルファインチューニングジョブを作成します。

前提条件

サポートされるリージョン: このトピックで説明する機能はシンガポールリージョンでのみ提供されており、このリージョンの API Key を使用する必要があります。
アカウント権限: Alibaba Cloud サブアカウント (RAM ユーザー) を使用する場合は、モデル呼び出し、トレーニング、デプロイのための権限をサブアカウントに付与する必要があります。
環境変数の設定: API Key の取得と環境変数としての設定が完了している必要があります。
事前準備: Qwen モデルのチューニングを確認し、ファインチューニング対応モデル、ファインチューニングの手順、データ形式、課金について理解している必要があります。

Singapore

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

Windows CMD の場合は、$DASHSCOPE_API_KEY を %DASHSCOPE_API_KEY% に置き換えてください。PowerShell の場合は、$env:DASHSCOPE_API_KEY に置き換えてください。

リクエストパラメーター

ヘッダー

Content-Type string (必須)

固定値: application/json

Authorization string (必須)

API Key 認証。形式は Bearer sk-xxxx です。

リクエストボディ

model string (必須)

ファインチューニング対象のモデル ID、または他のファインチューニングジョブで生成されたモデル 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 です。単一のトレーニングサンプルでサポートされる最大トークン長です。1 つのサンプルがこのトークン長を超えると、そのサンプルは破棄され、トレーニングには使用されません。

文字とトークンの関係については、トークンと文字列の変換をご参照ください。

learning_rate float (省略可)

学習率。Model Studio のデフォルト値の使用を推奨します。モデルの重み更新の強度を制御します。

高すぎる場合: モデルのパラメーターが大幅に変化し、パフォーマンスが低下する可能性があります。
低すぎる場合: モデルのパフォーマンスはほとんど変化しません。

lr_scheduler_type string (省略可)

学習率スケジューラーのタイプ。推奨値: linear または inverse_sqrt。トレーニング中に学習率を動的に調整するための戦略です。各戦略の詳細については、学習率スケジューラーの説明をご参照ください。

split float (省略可)

トレーニングファイルにおけるトレーニングデータの割合。Model Studio のデフォルト値の使用を推奨します。

validation_datasets が設定されていない場合、Model Studio は自動的に 80% をトレーニングセット、20% を検証セットとして使用します。validation_datasets が設定されている場合、このパラメーターは無効です。

max_split_val_dataset_sample int (省略可)

検証データセットの最大サイズ。Model Studio のデフォルト値の使用を推奨します。

validation_datasets が設定されていない場合、自動分割された検証セットには最大 1,000 サンプルが含まれます。validation_datasets が設定されている場合、このパラメーターは無効です。

eval_steps int (省略可)

検証ステップ数。トレーニング中の検証間隔で、モデルのトレーニング精度とトレーニング損失を定期的に評価するために使用されます。

このパラメーターは、チューニング中の検証損失 (Validation Loss) と検証トークン精度 (Validation Token Accuracy) の表示頻度に影響します。

logging_steps int (省略可)

ロギングステップ数。チューニングログを出力する間隔のステップ数です。

warmup_ratio float (省略可)

ウォームアップ比率。Model Studio のデフォルト値の使用を推奨します。トレーニング全体のうち、学習率のウォームアップに使用される割合です。学習率のウォームアップとは、トレーニング開始後に学習率が小さな値から設定値まで線形に増加することを指し、モデルがより安定してトレーニングされるようにします。

大きすぎる場合: 学習率が低すぎる場合と同じ効果となり、チューニング後もモデルのパフォーマンスはほとんど変化しません。
小さすぎる場合: 学習率が高すぎる場合と同じ効果となり、チューニング後にモデルのパフォーマンスが悪化する可能性があります。

このパラメーターは Constant 学習率スケジューラーには適用されません。

weight_decay float (省略可)

重み減衰 (L2 正則化の強度)。Model Studio のデフォルト値の使用を推奨します。モデルの汎用能力をある程度維持するのに役立ちます。値が大きすぎると、チューニング効果が分かりにくくなります。

freeze_vit boolean (省略可)

ビジョンバックボーンを凍結するかどうか。ビジョンバックボーンのパラメーターを凍結し、トレーニング中にその重みが更新されないようにします。Qwen-VL (視覚理解) モデルにのみ適用されます。

freeze_vit を true に設定した場合にのみ、モデルをトークン使用量に基づいて課金できます。

lora_rank int (省略可)

LoRA ランク。推奨値は 64 です。LoRA トレーニングにおける低ランク行列のランクです。ランクが大きいほどチューニング結果は向上しますが、トレーニングはわずかに遅くなります。

training_type が efficient_sft または dpo_lora の場合にのみ有効です。

既に効率的にファインチューニングされたモデルに対して再度効率的なファインチューニングを実行する場合、lora_rank、lora_alpha、lora_dropout は一貫している必要があります。

lora_alpha int (省略可)

LoRA スケーリング係数。Model Studio のデフォルト値の使用を推奨します。元のモデルの重みと LoRA 低ランク補正の間のスケーリング係数を制御します。

alpha 値が大きいほど、LoRA 補正により多くの重みが与えられ、モデルはタスク固有の情報に依存しやすくなります。
alpha 値が小さいほど、モデルは元の事前学習済み知識を保持する傾向が強くなります。

training_type が efficient_sft または dpo_lora の場合にのみ有効です。

lora_dropout float (省略可)

LoRA ドロップアウト率。Model Studio のデフォルト値の使用を推奨します。LoRA トレーニングにおける低ランク行列の値のドロップアウト率です。推奨値を使用するとモデルの汎化性能が向上します。値が大きすぎると、ファインチューニング効果が分かりにくくなります。

training_type が efficient_sft または dpo_lora の場合にのみ有効です。

save_strategy string (省略可)

チェックポイントの保存方法。epoch または steps に設定できます。steps に設定した場合は、save_steps パラメーターで保存間隔を調整できます。

training_type が efficient_sft または sft の場合にのみ有効です。

save_steps int (省略可)

保存ステップ数。モデルチェックポイントを保存する間隔のトレーニングステップ数を設定します。eval_steps の整数倍に設定することを推奨します。

training_type が efficient_sft または sft の場合にのみ有効です。

save_total_limit int (省略可)

チェックポイント保存上限。推奨値は 10 です。デプロイ用に保存されるチェックポイントの最大数を制限します。

training_type が efficient_sft または sft の場合にのみ有効です。

training_datasets Array of Dataset (必須)

トレーニングデータセットのファイルリスト。

データセットの構造

data_source_type string (必須)

データソースタイプ。有効な値:

oss_mount (OSS ファイルのマウント)
file_id (ファイル管理 API でアップロードされたファイル)

mount_storage object (条件付き必須)

データソースタイプが oss_mount の場合に必須です。OSS のマウント情報。

プロパティ

region string (必須)

マウントする OSS バケットのリージョン。北京 (cn-beijing) とシンガポール (ap-southeast-1) をサポートしています。

bucket string (必須)

マウントする OSS バケットの名前。

file_path string (必須)

マウントする OSS ファイルパス (オブジェクトキー)。複数のファイルを含むデータセットの場合は、data.jsonl へのパスを指定します。file_id 方式とは異なり、圧縮されていないデータセットフォルダーを OSS にアップロードする必要があります。Zip ファイルはサポートされていません。

file_id string (条件付き必須)

データソースタイプが file_id の場合に必須です。ファイルアップロード API で生成されたファイル ID。

validation_datasets Array of Dataset (省略可)

検証データセットのファイルリスト。構造は training_datasets と同じです。

job_name string (省略可)

チューニングジョブの名前。

model_name string (省略可)

チューニング完了後のモデル名。

Using file_id dataset

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":"<Replace with the file ID of your training dataset>"
        }
    ],
    "validation_datasets":[
        {
            "data_source_type":"file_id",
            "file_id":"<Replace with the file ID of your validation dataset>"
        }
    ],
    "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"
}'

Using OSS mounted dataset

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":"oss_mount",
            "mount_storage":{
                "region":"ap-southeast-1",
                "bucket":"example_bucket",
                "file_path":"dataset/data.jsonl"
            }
        }
    ],
    "validation_datasets":[
        {
            "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,
        "max_length":8192,
        "split":0.8
    },
    "training_type":"sft",
    "finetuned_output_suffix":"suffix"
}'

dashscope CLI

export DASHSCOPE_API_KEY="your-api-key"
# Replace {WorkspaceId} with your workspace ID, ap-southeast-1 with your region (e.g., us-east-1, eu-central-1)
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
# List fine-tuning jobs
dashscope ft list

# Create a fine-tuning job
dashscope ft create -t <file-id> -m qwen3-4b-instruct-2507 -e 1 -b 8

重要SDK Expert インタラクティブアシスタントを使用すると、自然言語で同じ開発作業やトラブルシューティングを行えます。詳細は

DashScope SDK Expert をご参照ください。

応答パラメーター

request_id string

このリクエストの ID。

output object

ジョブの詳細。

プロパティ

job_id string

ファインチューニングジョブの一意の識別子。ジョブの詳細やログのクエリ、ジョブのキャンセルや削除に使用されます。生成ルール: ft-{yyyyMMddHHmm}-{4 char uuid}。

job_name string

ファインチューニングジョブの名前。

status string

ファインチューニングジョブのステータス:

PENDING: トレーニング待機中。
QUEUING: トレーニングはキューイング中です。(同時に実行できるファインチューニングジョブは 1 つだけです。)
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

ファインチューニングジョブで消費されたトークン数。課金の計算式については、課金をご参照ください。ジョブステータスが SUCCEEDED または CANCELED の場合に返されます。

workspace_id string

チューニングジョブのワークスペース ID。

user_identity string

ユーザー ID。Alibaba Cloud アカウント ID です。

creator string

作成者の Alibaba Cloud アカウント ID。

modifier string

更新者の Alibaba Cloud アカウント ID。

group string

ファインチューニングジョブのグループ。

code string

エラーコード。呼び出しが失敗した場合に返されます。下記のエラーコード表をご参照ください。

message string

エラーメッセージの詳細。呼び出しが失敗した場合に返されます。

Success response example

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

Error response example

{
    "code": "InvalidParameter",
    "request_id": "BE213CDD-8A5C-59EE-9A67-055EAB0CB59B",
    "message": "Missing training files"
}

エラーコード

呼び出しが失敗してエラーメッセージが返された場合は、次の表を参照してトラブルシューティングを行ってください。

HTTP ステータスコード	エラーコード	解決策
400	InvalidParameter	パラメーターエラー: パラメーターの欠落または形式の問題です。エラーメッセージに基づいてパラメーターを修正してください。
400	UnsupportedOperation	リソースが特定の状態にある場合、そのリソースに対して操作を実行できません。リソースが操作可能な状態になってから再試行してください。
404	NotFound	クエリ/操作対象のリソースが存在しません。リソース ID が誤っていないか確認してください。
409	Conflict	同じ名前のデプロイメントインスタンスが既に存在します。区別できるようにサフィックスを指定してください。
429	Throttling	リソースの作成がプラットフォームの制限に達しました。使用しなくなったモデルを削除してください。
500	InternalError	内部エラーです。request_id を記録し、チケットで Alibaba Cloud エンジニアに連絡して調査を依頼してください。

次のステップ

ファインチューニングは非同期操作です。この API を呼び出した後、チューニングジョブのクエリと管理 API を使用してチューニングジョブのステータスを照会できます。