Pembuatan Pekerjaan Fine-tuning untuk Generasi Gambar

Prasyarat

Wilayah yang didukung: Fitur yang dijelaskan dalam dokumen ini hanya tersedia di wilayah Singapura. Anda harus menggunakan API Key dari wilayah ini.
Izin akun: Jika Anda menggunakan sub-akun Alibaba Cloud (RAM user), Anda perlu memberikan izin kepada sub-akun tersebut untuk pemanggilan model, pelatihan, dan penerapan permissions.
Konfigurasi variabel lingkungan: Anda telah berhasil memperoleh API Key dan mengonfigurasikannya sebagai variabel lingkungan.
Persiapan: Anda telah membaca Fine-tune image generation models untuk memahami model yang mendukung fine-tuning, langkah-langkah fine-tuning, format data, dan petunjuk penagihan.

Buat Pekerjaan Fine-tuning

Singapura

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

Untuk Windows CMD, ganti $DASHSCOPE_API_KEY dengan %DASHSCOPE_API_KEY%. Untuk PowerShell, ganti dengan $env:DASHSCOPE_API_KEY

Parameter permintaan

Headers

Content-Type string (Wajib)Nilai tetap: application/jsonAuthorization string (Wajib)Otentikasi API Key. Format: Bearer sk-xxxx.

Request Body

model string (Wajib)Menentukan model dasar untuk fine-tuning.

wan2.7-image-pro: Direkomendasikan untuk fine-tuning teks-ke-gambar/gambar-ke-gambar.
wan2.7-image

training_file_ids array[string] (Wajib bersyarat)Array ID file set data pelatihan. Beberapa ID dapat diberikan. Saling eksklusif dengan training_datasets. Jika training_datasets digunakan, parameter ini tidak diperlukan. ID file diperoleh melalui Upload File API.validation_file_ids array[string] (Opsional)Array ID file set data validasi. Beberapa ID dapat diberikan. Saling eksklusif dengan validation_datasets. Jika validation_datasets digunakan, parameter ini tidak diperlukan. Jika keduanya tidak diberikan, sistem akan secara otomatis membagi sebagian dari set pelatihan. ID file diperoleh melalui Upload File API.training_type string (Wajib)Jenis fine-tuning. Saat ini hanya mendukung efficient_sft (fine-tuning efisien LoRA).hyper_parameters object (Opsional)Konfigurasi hiperparameter. Untuk pelatihan awal, disarankan menggunakan hiperparameter default. Jika performa model buruk atau pelatihan tidak konvergen, coba sesuaikan parameter seperti max_steps atau learning_rate.

Properti hiperparameter

max_steps int (Wajib)Total langkah pelatihan. Parameter utama yang mengontrol durasi pelatihan. Nilai yang direkomendasikan: 800.max_steps menentukan jumlah iterasi pelatihan, sedangkan max_token_length menentukan volume data yang diproses per langkah.Disarankan menggunakan minimal 500 langkah agar model cukup konvergen. Anda dapat menambahkan langkah untuk set data yang lebih besar.

Parameter ini memengaruhi penagihan pelatihan. Harap atur secara tepat.

eval_steps int (Wajib)Interval validasi. Nilai yang direkomendasikan: 200. Nilainya harus >= 0. Menentukan berapa banyak langkah antara setiap evaluasi validasi selama pelatihan, digunakan untuk penilaian berkala terhadap progres pelatihan model. File model pada langkah saat ini juga disimpan.learning_rate float (Wajib)Laju pembelajaran. Nilai yang direkomendasikan: 3e-5. Mengontrol besarnya pembaruan bobot model. Terlalu tinggi dapat menurunkan kualitas model, sedangkan terlalu rendah dapat menghasilkan perubahan yang tidak signifikan.generation_type string (Wajib)Mode generasi. Menentukan format data pelatihan dan metode inferensi. Nilai yang valid:

t2i: Mode teks-ke-gambar.
i2i: Mode gambar-ke-gambar.

max_pixels string (Wajib)Resolusi maksimum gambar pelatihan. Menetapkan batas atas jumlah piksel total (lebar x tinggi) gambar dalam set pelatihan. Sistem hanya menskalakan gambar yang melebihi nilai ini; gambar di bawah batas tetap tidak berubah. Disarankan menjaga ketiga parameter resolusi (max_pixels, max_token_length, val_img_size) konsisten.

1k: yaitu, 1024x1024.
2k: yaitu, 2048x2048.

Nilai yang direkomendasikan: 2k untuk teks-ke-gambar, 1k untuk gambar-ke-gambar.val_img_size string (Wajib)Resolusi generasi gambar validasi. Resolusi target untuk gambar yang dihasilkan selama evaluasi validasi dalam proses pelatihan. Nilai yang valid sama dengan max_pixels. Nilai yang direkomendasikan: 2k untuk teks-ke-gambar, 1k untuk gambar-ke-gambar.max_token_length string (Wajib)Panjang token maksimum per langkah pelatihan, memengaruhi komputasi dan penagihan per langkah. Bersama dengan max_steps, mengontrol proses pelatihan: max_steps menentukan jumlah iterasi, sedangkan max_token_length menentukan volume data per langkah. Nilai yang valid:

1k: Direkomendasikan untuk skenario gambar-ke-gambar.
2k: Direkomendasikan untuk skenario teks-ke-gambar.

Pemetaan antara max_token_length dan L_max untuk penagihan:

generation_type	max_token_length	L_max
t2i (text-to-image)	1k	12,800
t2i (text-to-image)	2k	23,220
i2i (image-to-image)	1k	23,220
i2i (image-to-image)	2k	32,000

gradient_clip float (Wajib)Pemangkasan gradien. Nilai yang direkomendasikan: 0.5. Ambang batas untuk pemangkasan norma gradien global pada semua parameter yang dapat dilatih guna mencegah ledakan gradien. Atur ke -1 untuk menonaktifkan pemangkasan.weight_decay float (Wajib)Penurunan bobot. Nilai yang direkomendasikan: 0.02. Koefisien penurunan bobot terpisah AdamW, diterapkan pada semua parameter yang dapat dilatih untuk regularisasi guna mencegah overfitting.lora_rank int (Wajib)Rank matriks low-rank LoRA. Nilai yang direkomendasikan: 32. Nilai ini menentukan jumlah parameter fine-tuning. Nilai yang lebih besar memberikan kemampuan pemodelan yang lebih kuat tetapi kecepatan pelatihan lebih lambat. Nilainya harus merupakan pangkat dari 2ⁿ (misalnya, 16, 32, 64).save_total_limit int (Opsional)Jumlah maksimum checkpoint yang disimpan. Nilai yang direkomendasikan: 10. Membatasi jumlah maksimum model yang disimpan. Sistem akan selalu menyimpan hanya N checkpoint terakhir yang dihasilkan selama pelatihan.split float (Opsional)Rasio pemisahan set pelatihan. Nilai yang direkomendasikan: 0.9. Rentang nilai: (0, 1). Hanya berlaku jika baik validation_file_ids maupun validation_datasets tidak ditentukan. Parameter ini digunakan untuk secara otomatis membagi sebagian dari set pelatihan sebagai set validasi. Misalnya, 0.9 berarti 90% set pelatihan dan 10% set validasi.

training_datasets Array of Dataset (Wajib bersyarat)Daftar file set data pelatihan. Saling eksklusif dengan training_file_ids. Jika training_file_ids digunakan, parameter ini tidak diperlukan.

Struktur Dataset

data_source_type string (Wajib)Jenis sumber data. Nilai yang valid:

oss_mount (Memasang file OSS)
file_id (File yang diunggah melalui File Management API)

mount_storage object (Wajib bersyarat)Diperlukan ketika data_source_type adalah oss_mount. Informasi pemasangan OSS.

Properti

region string (Wajib)Wilayah bucket OSS yang akan dimasang. Mendukung Beijing (cn-beijing) dan Singapura (ap-southeast-1).bucket string (Wajib)Nama bucket OSS yang akan dimasang.file_path string (Wajib)Jalur file OSS (kunci objek) yang akan dimasang. Untuk set data yang berisi beberapa file, gunakan jalur file data.jsonl. Berbeda dengan pendekatan file_id, Anda perlu mengunggah seluruh folder set data yang tidak dikompresi ke OSS. File zip tidak didukung.

file_id string (Wajib bersyarat)Diperlukan ketika data_source_type adalah file_id. ID file, dihasilkan oleh Upload File API.

validation_datasets Array of Dataset (Opsional)Daftar file set data validasi. Strukturnya sama dengan training_datasets.Saling eksklusif dengan validation_file_ids. Jika keduanya tidak diberikan, sistem akan secara otomatis membagi sebagian dari set pelatihan.job_name string (Opsional)Nama pekerjaan fine-tuning.model_name string (Opsional)Nama model setelah fine-tuning selesai.

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_file_ids": [
        "<Replace with the training dataset file ID>"
    ],
    "training_type": "efficient_sft",
    "hyper_parameters": {
        "learning_rate": 3e-5,
        "max_steps": 800,
        "eval_steps": 200,
        "max_token_length": "2k",
        "gradient_clip": 0.5,
        "weight_decay": 0.02,
        "max_pixels": "2k",
        "val_img_size": "2k",
        "generation_type": "t2i",
        "lora_rank": 32,
        "save_total_limit": 10
    }
}'

Parameter respons

request_id stringIdentifier unik permintaan.output objectDetail pekerjaan.

Properti

job_id stringIdentifier unik pekerjaan fine-tuning, digunakan untuk menanyakan detail pekerjaan, log, membatalkan, atau menghapus pekerjaan. Aturan pembuatan: ft-{yyyyMMddHHmm}-{4-digit uuid}.job_name stringNama pekerjaan fine-tuning.status stringStatus pekerjaan fine-tuning:

PENDING: Pelatihan tertunda.
QUEUING: Pelatihan sedang dalam antrian (hanya satu pekerjaan fine-tuning yang dapat berjalan sekaligus).
RUNNING: Pelatihan sedang berlangsung.
SUCCEEDED: Pelatihan berhasil.
FAILED: Pelatihan gagal.
CANCELED: Pelatihan telah dibatalkan.
CANCELING: Pelatihan sedang dibatalkan.

finetuned_output stringID model baru yang dihasilkan setelah fine-tuning, digunakan untuk penerapan dan pemanggilan. Dikembalikan ketika status pekerjaan adalah SUCCEEDED.model stringModel dasar yang digunakan.base_model stringModel dasar yang digunakan.training_file_ids arrayBidang lama untuk kompatibilitas mundur. Pekerjaan baru selalu mengembalikan array kosong. Gunakan training_datasets.training_datasets Array of DatasetDaftar set data pelatihan.validation_file_ids arrayBidang lama untuk kompatibilitas mundur. Pekerjaan baru selalu mengembalikan array kosong. Gunakan validation_datasets.validation_datasets Array of DatasetDaftar set data validasi. Mengembalikan array kosong jika tidak ada set validasi yang ditentukan.hyper_parameters objectHiperparameter yang benar-benar digunakan.training_type stringMetode pelatihan untuk fine-tuning model.create_time stringWaktu pembuatan pekerjaan.end_time stringWaktu akhir pekerjaan. Dikembalikan ketika status pekerjaan adalah SUCCEEDED, FAILED, atau CANCELED.usage integerJumlah token yang dikonsumsi oleh pekerjaan fine-tuning. Dikembalikan ketika status pekerjaan adalah SUCCEEDED atau CANCELED.workspace_id stringID ruang kerja yang terkait dengan API Key Alibaba Cloud Model Studio. Lihat Get the Workspace ID.user_identity stringIdentitas pengguna, yaitu ID akun Alibaba Cloud.creator stringID akun Alibaba Cloud dari pembuat.modifier stringID akun Alibaba Cloud dari pengubah.group stringGrup pekerjaan fine-tuning.max_output_cnt integerJumlah maksimum checkpoint yang disimpan selama pelatihan. Sama dengan nilai hiperparameter save_total_limit.

code stringKode kesalahan. Dikembalikan ketika pemanggilan gagal. Lihat tabel kode kesalahan di bawah.message stringDeskripsi detail kesalahan. Dikembalikan ketika pemanggilan gagal.

Contoh respons sukses
Contoh respons error

Bidang utama: output.job_id (ID Pekerjaan), output.finetuned_output (Nama model baru yang dihasilkan setelah fine-tuning).

{
    "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": "2k",
            "max_pixels": "2k",
            "val_img_size": "2k",
            "generation_type": "t2i",
            "lora_rank": 32
        },
        "training_type": "efficient_sft",
        "create_time": "2026-06-03 01:10:47"
    }
}

Kode kesalahan

Jika pemanggilan gagal dan mengembalikan pesan kesalahan, rujuk tabel berikut untuk troubleshooting.

Kode status HTTP	Kode kesalahan	Solusi
400	InvalidParameter	Parameter tidak valid—parameter hilang atau formatnya salah. Perbaiki parameter sesuai dengan pesan kesalahan.
400	UnsupportedOperation	Sumber daya tidak dapat dioperasikan dalam status tertentu. Tunggu hingga sumber daya mencapai status yang memungkinkan operasi sebelum melanjutkan.
404	NotFound	Sumber daya yang diminta atau akan dioperasikan tidak ditemukan. Periksa apakah ID sumber daya yang digunakan salah.
409	Conflict	Instans penerapan dengan nama yang sama sudah ada. Gunakan sufiks untuk membedakannya.
429	Throttling	Pembuatan sumber daya telah mencapai batas platform. Hapus model yang tidak lagi digunakan.
500	InternalError	Terjadi kesalahan internal. Catat request_id dan hubungi insinyur Alibaba Cloud melalui tiket untuk troubleshooting.

Langkah berikutnya

Fine-tuning adalah operasi asinkron. Setelah memanggil API ini, Anda dapat menggunakan API Query and Manage Tuning Jobs untuk memeriksa status pekerjaan.

​Prasyarat

​Buat Pekerjaan Fine-tuning

Parameter permintaan

Headers

Request Body

Parameter respons

​Kode kesalahan

​Langkah berikutnya

Prasyarat

Buat Pekerjaan Fine-tuning

Kode kesalahan

Langkah berikutnya