Impor model - Alibaba Cloud Model Studio - Alibaba Cloud Documentation Center

API impor model Model Studio menyediakan antarmuka lengkap untuk membuat, mengkueri, menampilkan daftar, dan menghapus tugas impor, memungkinkan Anda mengimpor file model fine-tuned dari OSS ke Model Studio.

Ikhtisar

API impor model memungkinkan Anda mengimpor file model fine-tuned yang disimpan di OSS ke Model Studio. Setelah diimpor, Anda dapat menerapkan model tersebut sebagai layanan yang dapat dipanggil melalui API create deployment. Impor model mendukung dua jenis model: fine-tuning parameter penuh (full) dan fine-tuning LoRA (lora).

Alur kerja impor model lengkap adalah sebagai berikut: buat tugas impor → kueri detail tugas impor (poll status tugas) → buat penerapan setelah tugas berhasil → tampilkan daftar dan hapus tugas yang tidak lagi diperlukan.

API impor model saat ini hanya tersedia di wilayah Singapura. Jika Anda menggunakan wilayah lain, gunakan konsol Model Studio di wilayah tersebut untuk mengimpor model.

Prasyarat

Anda telah mengonfigurasi Kunci API Model Studio Anda. Untuk informasi selengkapnya, lihat Dapatkan Kunci API.
Anda telah membuat bucket OSS dan memberikan otorisasi kepada Model Studio untuk mengakses OSS. Untuk informasi selengkapnya, lihat prasyarat dalam Impor Model.
File model telah diunggah ke bucket OSS dan memenuhi Persyaratan dan Batasan Impor.

Header permintaan umum

Semua operasi API memerlukan bidang-bidang berikut dalam Header HTTP:

Header	Description
Authorization	`Bearer ${DASHSCOPE_API_KEY}`. Untuk informasi selengkapnya tentang cara mendapatkan Kunci API, lihat Dapatkan Kunci API.
Content-Type	`application/json`

Objek model kustom

Objek model kustom berisi informasi lengkap mengenai tugas impor. Objek ini dibuat melalui API Buat tugas impor dan dapat diambil melalui API Kueri detail tugas impor serta Tampilkan daftar tugas impor. Setelah diimpor, Anda dapat menerapkan model tersebut melalui API Buat penerapan. Berikut adalah bidang-bidang yang terdapat dalam objek model kustom:

Bidang objek

Parameter	Type	Description
request_id	String	ID permintaan.
output.job_id	String	ID tugas impor, digunakan untuk mengkueri status tugas atau menghapus tugas.
output.model_name	String	Identifikasi model yang dihasilkan sistem, dalam format nama model dasar diikuti dengan akhiran timestamp.
output.display_name	String	Nama tampilan model yang diimpor.
output.source	String	Sumber impor. Nilai kembali berupa `OSS` huruf kapital.
output.weight_type	String	Jenis fine-tuning.
output.storage_info	Object	Informasi penyimpanan sumber impor, termasuk `bucket_name` dan `object_key`.
output.status	String	Status tugas. Untuk informasi selengkapnya, lihat Status tugas.
output.gmt_create	String	Waktu pembuatan tugas dalam format ISO 8601. Contoh: `2024-01-01T12:00:00.000+00:00`.

Status tugas

Tugas impor dapat memiliki status berikut selama siklus hidupnya:

Status	Description
PENDING	Tugas telah dikirim dan sedang menunggu untuk diproses.
RUNNING	Tugas sedang dieksekusi. Sistem sedang memvalidasi dan mengimpor file model.
SUCCESSED	Tugas telah selesai berhasil. Model telah diimpor dan dapat diterapkan melalui API Buat penerapan.
FAILED	Eksekusi tugas gagal. Anda dapat mengkueri detail tugas untuk mendapatkan `error_code` sebagai alasan kegagalan.

Buat tugas impor

Kirim tugas impor model. Sistem memvalidasi struktur dan keamanan file model untuk memastikan file tersebut dapat diterapkan dengan benar.

Endpoint

POST https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import

Contoh permintaan

curl -X POST "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
        "model_name": "qwen3-32b",
        "display_name": "My LoRA fine-tuned model",
        "source": "oss",
        "weight_type": "lora",
        "storage_info": {
            "bucket_name": "my-model-bucket",
            "object_key": "models/qwen3-32b-lora/"
        }
    }'

Parameter permintaan

Parameter	Type	Position	Required	Description
model_name	String	body	Yes	Nama model dasar. Sesuai dengan bidang Base Model di konsol. Untuk model yang didukung, lihat Model Dasar yang Didukung. Contoh: `qwen3-32b`.
display_name	String	body	No	Nama tampilan model yang diimpor. Sesuai dengan bidang Model Name di konsol. Maksimal 50 karakter. Jika tidak ditentukan, nama model dasar akan digunakan secara default.
source	String	body	Yes	Sumber impor. Sesuai dengan bidang Import Source di konsol. Saat ini hanya `oss` (impor dari OSS) yang didukung. Respons mengembalikan `OSS` huruf kapital.
weight_type	String	body	Yes	Jenis fine-tuning. `full` menunjukkan model fine-tuned parameter penuh. `lora` menunjukkan model fine-tuned LoRA.
storage_info	Object	body	Yes	Informasi penyimpanan sumber impor.
storage_info.bucket_name	String	body	Yes	Nama bucket OSS. Sesuai dengan bidang Bucket di konsol.
storage_info.object_key	String	body	Yes	Awalan path OSS file model. Harus diakhiri dengan `/`. Contoh: `models/qwen3-32b-lora/`.

Contoh respons

{
    "request_id": "6c6b****-3fea-****-bc26-c9e2********",
    "output": {
        "job_id": "937b****-2a4f-****-8abe-c2fa********",
        "model_name": "qwen3-32b-offline-20240101-abc1",
        "display_name": "My LoRA fine-tuned model",
        "source": "OSS",
        "weight_type": "lora",
        "storage_info": {
            "bucket_name": "my-model-bucket",
            "object_key": "models/qwen3-32b-lora/"
        },
        "status": "PENDING",
        "gmt_create": "2024-01-01T12:00:00.000+00:00"
    }
}

Parameter respons

Parameter	Type	Description
request_id	String	ID permintaan.
output.job_id	String	ID tugas impor, yang dapat digunakan bersama API Kueri detail tugas impor, Tampilkan daftar tugas impor, dan Hapus tugas impor.
output.model_name	String	Identifikasi model yang dihasilkan sistem, dalam format nama model dasar diikuti dengan akhiran timestamp.
output.display_name	String	Nama tampilan model yang diimpor.
output.source	String	Sumber impor. Nilai kembali berupa `OSS` huruf kapital.
output.weight_type	String	Jenis fine-tuning.
output.storage_info	Object	Informasi penyimpanan sumber impor, termasuk `bucket_name` dan `object_key`.
output.status	String	Status tugas. Untuk informasi selengkapnya, lihat Status tugas.
output.gmt_create	String	Waktu pembuatan tugas dalam format ISO 8601. Contoh: `2024-01-01T12:00:00.000+00:00`.

Kueri detail tugas impor

Kueri status dan detail saat ini dari tugas impor tertentu.

Endpoint

GET https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import/{job_id}

Contoh permintaan

curl "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import/937b****-2a4f-****-8abe-c2fa********" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json"

Parameter permintaan

Parameter	Type	Position	Required	Description
job_id	String	path	Yes	ID tugas impor, yang dapat diperoleh melalui API Buat tugas impor atau Tampilkan daftar tugas impor.

Contoh respons

{
    "request_id": "ca21****-b91b-****-bd35-c41c********",
    "output": {
        "job_id": "937b****-2a4f-****-8abe-c2fa********",
        "model_name": "qwen3-32b-offline-20240101-abc1",
        "display_name": "My LoRA fine-tuned model",
        "source": "OSS",
        "storage_info": {
            "bucket_name": "my-model-bucket",
            "object_key": "models/qwen3-32b-lora/"
        },
        "status": "RUNNING",
        "gmt_create": "2024-01-01T12:00:00.000+00:00"
    }
}

Parameter respons

Parameter respons sebagian besar sama dengan parameter respons API Buat tugas impor, kecuali bidang weight_type tidak disertakan. Ketika tugas gagal, respons mencakup bidang tambahan error_code yang menunjukkan alasan kegagalan.

Tampilkan daftar tugas impor

Kueri daftar tugas impor di ruang kerja saat ini dengan pagination.

Endpoint

GET https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import

Contoh permintaan

curl "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import?page_no=1&page_size=10" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json"

Filter berdasarkan status:

curl "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import?page_no=1&page_size=10&status=SUCCESSED" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json"

Parameter permintaan

Parameter	Type	Position	Required	Description
page_no	Integer	query	No	Nomor halaman. Nilai default: 1.
page_size	Integer	query	No	Jumlah entri per halaman. Nilai default: 10. Nilai maksimum: 100.
status	String	query	No	Filter berdasarkan status tugas. Untuk informasi selengkapnya, lihat Status tugas.
model_name	String	query	No	Filter berdasarkan nama model. Anda harus menggunakan nama yang dihasilkan sistem yang dikembalikan dalam respons (pencocokan eksak).

Contoh respons

{
    "request_id": "ca21****-b91b-****-bd35-c41c********",
    "output": {
        "total": 2,
        "page_no": 1,
        "page_size": 10,
        "list": [
            {
                "job_id": "937b****-2a4f-****-8abe-c2fa********",
                "model_name": "qwen3-32b-offline-20240101-abc1",
                "display_name": "My LoRA fine-tuned model",
                "status": "SUCCESSED",
                "source": "OSS",
                "storage_info": {
                    "bucket_name": "my-model-bucket",
                    "object_key": "models/qwen3-32b-lora/"
                },
                "gmt_create": "2024-01-01T12:00:00.000+00:00"
            },
            {
                "job_id": "edb0****-39ac-****-9859-8b1e********",
                "model_name": "qwen3-32b-offline-20240102-xyz4",
                "display_name": "My full-parameter fine-tuned model",
                "status": "FAILED",
                "source": "OSS",
                "storage_info": {
                    "bucket_name": "my-model-bucket",
                    "object_key": "models/qwen3-32b-full/"
                },
                "error_code": "Failed to retrieve files from OSS. Please check the files in OSS.",
                "gmt_create": "2024-01-02T09:00:00.000+00:00"
            }
        ]
    }
}

Parameter respons

Parameter	Type	Description
request_id	String	ID permintaan.
output.total	Integer	Jumlah total tugas yang sesuai dengan kriteria kueri.
output.page_no	Integer	Nomor halaman saat ini.
output.page_size	Integer	Jumlah entri per halaman.
output.list	Array	Daftar tugas impor. Setiap elemen memiliki bidang yang sama dengan parameter respons API Buat tugas impor, kecuali bidang `weight_type` tidak disertakan. Bidang tambahan `error_code` disertakan ketika tugas gagal.

Hapus tugas impor

Hapus tugas impor tertentu beserta file model terkaitnya. Hanya tugas dengan status SUCCESSED atau FAILED yang dapat dihapus. Setelah penghapusan berhasil, detail tugas yang dihapus akan dikembalikan.

Endpoint

DELETE https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import/{job_id}

Contoh permintaan

curl -X DELETE "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import/937b****-2a4f-****-8abe-c2fa********" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json"

Parameter permintaan

Parameter	Type	Position	Required	Description
job_id	String	path	Yes	ID tugas impor, yang dapat diperoleh melalui API Buat tugas impor atau Tampilkan daftar tugas impor.

Contoh respons

{
    "request_id": "e22b****-b20a-****-bf23-9b53********",
    "output": {
        "job_id": "937b****-2a4f-****-8abe-c2fa********",
        "model_name": "qwen3-32b-offline-20240101-abc1",
        "display_name": "My LoRA fine-tuned model",
        "source": "OSS",
        "storage_info": {
            "bucket_name": "my-model-bucket",
            "object_key": "models/qwen3-32b-lora/"
        },
        "status": "SUCCESSED",
        "gmt_create": "2024-01-01T12:00:00.000+00:00"
    }
}

Parameter respons

Parameter	Type	Description
request_id	String	ID permintaan.
output	Object	Detail tugas yang dihapus. Bidang-bidangnya sebagian besar sama dengan parameter respons API Buat tugas impor, kecuali bidang `weight_type` tidak disertakan.

Respons error

Ketika terjadi error, API mengembalikan respons error dalam format berikut:

{
    "request_id": "ca21****-b91b-****-bd35-c41c********",
    "code": "OperationDenied",
    "message": "The import job is currently running and cannot be deleted."
}

Kode error

Error code	Description
InvalidParameter	Parameter permintaan tidak valid. Misalnya, parameter yang diperlukan tidak ada, format parameter salah, atau nilai parameter tidak valid.
NotFound	Resource yang ditentukan tidak ada. Misalnya, job_id tidak ada, pengguna tidak memiliki akses, atau model dasar tidak mendukung impor.
OperationDenied	Operasi ditolak. Misalnya, mencoba menghapus tugas yang berstatus RUNNING.
InvalidApiKey	Kunci API tidak valid atau tidak diberikan.
InternalError	Terjadi error internal sistem. Silakan coba lagi nanti.