Skip to main content

Panduan penerapan API

Topik ini menggunakan model Qwen sebagai contoh untuk memandu Anda melalui siklus lengkap penerapan model di Alibaba Cloud Model Studio menggunakan panggilan API (HTTP), termasuk penerapan, kueri, inferensi, penghapusan, dan pemecahan masalah izin.

Dokumen ini hanya berlaku untuk wilayah China (Beijing).

Prasyarat

1. Terapkan model

Perintah berikut menunjukkan cara membuat layanan khusus. Di antaranya, contoh penagihan berbasis token menggunakan model kustom hasil fine-tuning qwen3-8b-ft-202511132025-0260 untuk membuat layanan khusus qwen3-8b-ft-202511132025-0260; contoh model unit menggunakan model preset. Untuk mendapatkan ID model kustom: Buka Konsol Model Studio - Fine-tuning model, klik Task Name -> Output -> klik nama model berwarna biru untuk masuk ke halaman My Models, tempat Anda dapat melihat ID model di area informasi dasar model. Gunakan Model IDsebagai input untuk parameter model_name untuk menerapkan model melalui API.
  • Model unit
  • Ditagih berdasarkan penggunaan token model
  • dashscope CLI
  • Setelah Anda menjalankan perintah penerapan, penagihan dimulai segera setelah layanan berhasil diterapkan, bahkan jika Anda tidak menggunakannya. Sebelum melanjutkan, sebaiknya tinjau aturan penagihan layanan.
  • Sumber daya komputasi untuk rencana model unit post-paid dialokasikan berdasarkan prinsip first-come, first-served. Jika pembelian tidak berhasil, pengembalian dana penuh akan diberikan.
Metode penagihan model unit mengenakan biaya berdasarkan durasi penggunaan. Metode penagihan ini ideal untuk tugas inferensi berskala besar setelah fine-tuning model, menawarkan sumber daya khusus dengan penyesuaian performa dan biaya yang fleksibel. Anda dapat menyesuaikan baik throughput/konkurensi maupun kecepatan generasi.
curl "https://dashscope.aliyuncs.com/api/v1/deployments" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "name": "my_qwen_plus",
    "model_name": "qwen-plus-2025-12-01",
    "plan": "mu",
    "deploy_spec": "MU1",
    "enable_thinking": true,
    "capacity": 4,
    "max_context_length": 10000,
    "rpm_limit": 500,
    "tpm_limit": 1000
}'
Mode penerapan model unit mendukung pengaturan tambahan berikut:

Item konfigurasi

Detail konfigurasi

Nama layanan

Nama kustom untuk layanan penerapan.

Pilih model

Pilih model yang akan diterapkan, termasuk model bawaan platform dan model hasil fine-tuning.

Tipe model unit

Pilih spesifikasi penerapan. Spesifikasi yang berbeda sesuai dengan daya komputasi dan performa yang berbeda.

Model unit per replika

Jumlah model unit yang diperlukan per replika ditentukan bersama oleh template penerapan dan tipe model unit, dan tidak dapat diubah. Misalnya, qwen3-32b memerlukan 16 model unit per replika. Total Model Unit = Replika yang Diterapkan × Model unit per Replika, yang menentukan berapa banyak sumber daya yang digunakan oleh layanan yang diterapkan. Meningkatkan jumlah replika yang diterapkan mengonsumsi lebih banyak model unit dan memberikan performa model yang lebih baik.

Jumlah replika penerapan

Atur jumlah awal replika penerapan, yang memengaruhi kapasitas konkurensi layanan.

Template penerapan

Pilih template penerapan (seperti "single-node deployment"). Template yang berbeda sesuai dengan skema konfigurasi sumber daya yang berbeda. Hanya tersedia dalam mode penagihan model unit.

Konfigurasi mode inferensi model

Untuk beberapa model yang diterapkan dalam mode Model Unit, Anda dapat mengonfigurasi mode inferensi, panjang konteks maksimum, dan lainnya.

  • Instruct - Setelah penerapan, model menjalankan inferensi dalam mode non-thinking.

  • Thinking - Setelah penerapan, model menjalankan inferensi dalam mode thinking.

Panjang konteks maksimum

Mode penerapan Model Unit dari beberapa model mendukung pengaturan ini. Panjang konteks maksimum bergantung pada jenis model.

Pembatasan laju layanan

Mode penerapan Model Unit dari beberapa model mendukung pengaturan ini. Anda dapat membatasi RPM dan TPM pemanggilan model.

Untuk cara mengonfigurasi hal di atas melalui API, lihat Membuat penerapan menggunakan API.
Setelah perintah berhasil dijalankan, hasil berikut dikembalikan: (mengambil contoh penerapan model unit)
{
    "request_id": "83b173ab-2b2f-41aa-8c57-b173e8be934e",
    "output":
    {
        "deployed_model": "qwen3-8b-ft-202511132025-0260",
        "gmt_create": "2025-11-20T20:06:46.405",
        "gmt_modified": "2025-11-20T20:06:46.405",
        "status": "PENDING",
        "model_name": "qwen3-8b-ft-202511132025-0260",
        "base_model": "qwen3-8b",
        "workspace_id": "llm-8v*****",
        "charge_type": "post_paid",
        "creator": "16542*****",
        "modifier": "16542*****",
        "plan": "mu",
        "model_unit_spec": "MU1"
    }
}
Di antaranya, deployed_model adalah ID unik layanan khusus; gunakan nilai deployed_model ini sebagai pengenal di jalur API berikutnya seperti kueri dan penghapusan (bukan name dalam parameter permintaan).

2. Kueri status layanan

Gunakan perintah berikut untuk mengkueri informasi detail layanan khusus tertentu:
curl "https://dashscope.aliyuncs.com/api/v1/deployments/qwen3-8b-ft-202511132025-0260" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header 'Content-Type: application/json'
Setelah perintah berhasil dijalankan, hasil berikut dikembalikan:
{
    "request_id": "ca36952d-9136-426e-ab08-68a97ad72719",
    "output":
    {
        "deployed_model": "qwen3-8b-ft-202511132025-0260",
        "gmt_create": "2025-11-20T20:32:08",
        "gmt_modified": "2025-11-20T20:42:25",
        "status": "RUNNING",
        "model_name": "qwen3-8b-ft-202511132025-0260",
        "base_model": "qwen3-8b",
        "base_capacity": 2,
        "capacity": 2,
        "ready_capacity": 2,
        "workspace_id": "llm-8v53etv3hwb8orx1",
        "charge_type": "post_paid",
        "creator": "1654290265984853",
        "modifier": "1654290265984853",
        "plan": "mu",
        "model_unit_spec": "MU1"
    }
}
Ketika status layanan adalah RUNNING, penerapan layanan telah selesai.

3. Kirim permintaan inferensi

Jika ini pertama kalinya Anda menggunakan DashScope SDK, lihat Instal SDK.Pastikan ruang kerja Kunci API Anda sama dengan ruang kerja tempat penerapan model berada.
Saat memanggil layanan khusus yang telah diterapkan, parameter model harus diatur ke code model yang diperoleh setelah penerapan model berhasil; buka konsol penerapan khusus (Beijing) untuk mendapatkannya.
import os
import dashscope

# 若没有配置环境变量,请用百炼API Key将下一行替换为:api_key="sk-xxx",
client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "你是谁?"},
]
response = client.chat.completions.create(
    model="qwen3-14b-xxx-xxx",  # 请替换为模型部署成功后的code
    messages=messages,
    enable_thinking=False,
)
print(response)

Penyelarasan parameter inferensi

Nilai default parameter dari mesin inferensi Model Studio mungkin berbeda dengan framework inferensi lokal. Untuk menyelaraskan dengan default vLLM, lihat tabel berikut saat mengatur parameter; jika Anda menggunakan framework lain seperti SGLang, lihat dokumentasi yang sesuai untuk penyesuaian.

Nama parameter

Nilai yang direkomendasikan (sesuai default vLLM)

temperature

Rentang nilai [0, 2); mengaturnya ke 1.0 setara dengan default mesin vLLM.

top_p

Rentang nilai (0, 1.0]; mengaturnya ke 1.0 setara dengan default mesin vLLM.

top_k

Ketika nilainya None atau lebih besar dari 100, kebijakan top_k tidak diaktifkan dan hanya top_p yang berlaku; mengaturnya ke 99 tidak mendukung sampling penuh, yang mendekati default vLLM yaitu 0 (sampling penuh).

presence_penalty

Rentang nilai [-2.0, 2.0]; mengaturnya ke 0 setara dengan default mesin vLLM.

repetition_penalty (protokol DashScope)

Meningkatkan nilai ini mengurangi pengulangan dalam generasi; 1.0 berarti tidak ada penalti; rentang nilainya lebih besar dari 0, dan mengaturnya ke 1.0 setara dengan default mesin vLLM.

4. Hapus layanan khusus

Setelah Anda menjalankan perintah penghapusan berikut, layanan penerapan model akan segera mulai offline, dan ini tidak dapat dibatalkan. Anda akan:
  1. Tidak dapat lagi memanggil model.
  2. Berhenti ditagih untuk layanan penerapan.
Anda dapat menghapus layanan khusus yang tidak lagi digunakan dengan perintah berikut:
curl --request DELETE 'https://dashscope.aliyuncs.com/api/v1/deployments/qwen3-8b-ft-202511132025-0260' \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header 'Content-Type: application/json'
Setelah perintah berhasil dijalankan, hasil berikut dikembalikan:
{
    "request_id": "8f726017-6042-420e-a465-0d366a3aba59",
    "output":
    {
        "deployed_model": "qwen3-8b-ft-202511132025-0260",
        "gmt_create": "2025-11-20T20:32:08",
        "gmt_modified": "2025-11-27T16:35:31.591",
        "status": "DELETING",
        "model_name": "qwen3-8b-ft-202511132025-0260",
        "base_model": "qwen3-8b",
        "base_capacity": 2,
        "capacity": 2,
        "ready_capacity": 2,
        "workspace_id": "llm-8v53etv3hwb8orx1",
        "charge_type": "post_paid",
        "creator": "1654290265984853",
        "modifier": "1654290265984853",
        "plan": "mu",
        "model_unit_spec": "MU1"
    }
}
Setelah penghapusan berhasil, memanggil API 2. Kueri status layanan tidak akan lagi mengembalikan status model yang diterapkan.

Pemecahan masalah izin

Jika Anda mengalami kesalahan izin yang tidak memadai selama penerapan model, ada dua jalur pemecahan masalah bergantung pada metode penerapan:

Penerapan konsol

  1. Jika "Kekurangan izin untuk modul ini" ditampilkan, pastikan akun Anda memiliki izin Model Deployment-Actions pada halaman manajemen izin ruang kerja. Jika Anda tidak dapat melakukan operasi, hubungi organisasi atau administrator TI Anda untuk menambahkan izin yang diperlukan atau memeriksa masalah izin untuk Anda.
  2. Jika galat "Ruang kerja xx tidak memiliki izin untuk menerapkan model xx" dilaporkan selama penerapan, buka halaman Workspaces di Bailian dan tambahkan izin penerapan untuk model yang sesuai ke ruang kerja yang sesuai.
    Kesalahan panggilan API: Workspace xxx does not have deployment privilege for model xxxx.
    PixPin_2025-11-27_15-03-57
    PixPin_2025-11-27_15-06-41
    Jika Anda dimintai izin yang tidak memadai, hubungi organisasi atau administrator TI Anda untuk menambahkan izin terkait atau melakukan operasi atas nama Anda.

Penerapan API

Saat menerapkan model melalui API, Anda perlu memastikan bahwa:
  1. Workspace yang dimiliki Kunci API memiliki izin untuk mengelola model. Buka halaman Workspaces di Bailian dan periksa pengaturan izin penerapan model dari ruang kerja yang sesuai.
    Kesalahan panggilan API: Workspace xxx does not have deployment privilege for model xxxx.
    Pada kolom Actions dari ruang kerja yang sesuai, klik Authorization & Throttling Settings. Temukan model target dalam daftar Models dan periksa status otorisasi di kolom Model Deployment. Jika Unauthorized ditampilkan, klik Modify di kolom Actions untuk memberikan otorisasi. Jika pesan izin yang tidak memadai muncul, hubungi organisasi atau administrator TI Anda untuk menambahkan izin yang diperlukan atau melakukan operasi untuk Anda.
  2. Owner Account dari Kunci API memiliki izin operasi di Workspace tempat ia berada. Buka konsol Bailian, klik ruang kerja di pojok kiri bawah, alihkan ke ruang kerja yang sesuai, lalu klikimagePeriksa pengaturan izin penerapan model dari ruang kerja yang sesuai.
    Kesalahan panggilan API: Workspace access denied.
    Di panel navigasi kiri, klik Permission Management dan pastikan daftar pengguna mencakup akun pemilik Kunci API (dengan tipe primary account). Jika Anda dimintai izin yang tidak memadai, hubungi organisasi atau administrator TI Anda untuk menambahkan izin terkait atau melakukan operasi atas nama Anda.

Referensi API

Untuk panggilan API terperinci, lihat Detail API dan Referensi API penerapan lengkap.