全部产品
Search
文档中心

Alibaba Cloud Model Studio:Memulai dengan Assistant API

更新时间:Oct 16, 2025

API Asisten menyediakan pengembang dengan seperangkat alat untuk mengelola pesan percakapan dan penggunaan alat. Topik ini menjelaskan teknik pemrograman dasar API Asisten dengan membimbing Anda melalui pembuatan asisten dari awal.

Proses tipikal

Proses tipikal dalam mengembangkan asisten adalah sebagai berikut:

  1. Buat asisten: Saat membuat asisten, pilih model, masukkan instruksi, dan tambahkan alat seperti interpreter kode serta pemanggilan fungsi.

  2. Buat thread: Buat thread sesi untuk mempertahankan kontinuitas percakapan ketika pengguna memulai dialog.

  3. Kirim pesan ke thread: Tambahkan pesan pengguna ke thread sesi satu per satu.

  4. Mulai run: Jalankan asisten pada thread sesi. Asisten akan menafsirkan pesan, menggunakan alat atau layanan yang sesuai, menghasilkan tanggapan, dan mengirimkannya kepada pengguna.

Skenario contoh

Model generasi teks saja tidak dapat menghasilkan gambar. Sebagai gantinya, model teks-ke-gambar diperlukan untuk menghasilkan gambar dari teks. Asisten yang dibangun dengan API Asisten dapat secara otomatis meningkatkan prompt yang diberikan pengguna dan menggunakan alat teks-ke-gambar untuk membuat gambar berkualitas tinggi.

Prosedur

Berikut ini adalah panduan komprehensif dalam Python untuk mode keluaran non-streaming. Kode sampel lengkap untuk keluaran streaming dan non-streaming dalam Python dan Java disajikan di akhir topik ini, lihat Kode Sampel Lengkap.

image

Langkah 1: Siapkan lingkungan pengembangan

  • Ajukan permohonan plug-in: Anda pertama-tama perlu mengajukan permohonan alat pembuatan gambar : Pergi ke Plug-ins, temukan Image Generation dan klik Apply.

  • Interpreter Python: API Asisten membutuhkan versi interpreter Python 3.8 atau lebih tinggi. Untuk memeriksa versi Python Anda, atau untuk menginstal versi tertentu, kunjungi Download Python.

  • SDK DashScope: API Asisten membutuhkan versi SDK DashScope 1.17.0 atau lebih tinggi. Jalankan perintah sampel untuk memverifikasi versi atau instal SDK DashScope.

  • Kunci API: API Asisten membutuhkan kunci API Model Studio. Dapatkan kunci API di sini. Kami juga merekomendasikan Anda atur kunci API sebagai variabel lingkungan untuk mencegah kebocoran.

# Periksa versi interpreter Python
python --version 
# Periksa SDK DashScope
pip list | grep dashscope 
# Instal SDK DashScope Versi 1.17.0
pip install dashscope==1.17.0

Langkah 2: Buat asisten

Setelah mengimpor SDK DashScope, buat asisten menggunakan metode create dari kelas asisten. Tentukan parameter kunci berikut:

  • model: Nama model yang digunakan untuk asisten.

  • name: Nama asisten.

  • description: Deskripsi fungsi asisten.

  • instructions: Instruksi yang mendefinisikan peran dan tugas asisten dalam bahasa alami.

  • tools: Alat yang dikonfigurasikan untuk asisten.

Karena alat teks-ke-gambar memiliki persyaratan pemahaman bahasa yang tinggi, Qwen-Max dipilih sebagai model inferensi teks untuk meningkatkan kemampuan pemahaman semantik dan generasi teks asisten.

Detail asisten, termasuk nama, deskripsi fungsi, dan instruksi, ditampilkan dalam kode sampel.

Plug-in resmi Image Generation dikonfigurasikan untuk asisten sehingga dapat menghasilkan gambar berdasarkan deskripsi teks secara otomatis.

Anda dapat membuat sejumlah asisten tanpa batas. Namun, panggilan sering ke model tunggal dapat memicu batas laju. Anda dapat mengonfigurasikan model yang berbeda untuk Asisten Anda berdasarkan skenario mereka.

Untuk panduan penggunaan, lihat Asisten.

import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Buat asisten lukisan dengan Qwen-Max
painting_assistant = dashscope.Assistants.create(
    model='qwen-max',  # Gunakan Qwen-Max untuk kemampuan pemahaman yang ditingkatkan. Daftar model: https://www.alibabacloud.com/help/en/model-studio/getting-started/models
    name='Art Maestro',  # Nama asisten
    description='AI assistant untuk pengetahuan melukis dan seni',
    instructions='''Berikan informasi tentang teknik melukis, sejarah seni, dan panduan kreatif.''',
    tools=[
        {
            'type': 'text_to_image',  # Alat yang menghasilkan gambar berdasarkan deskripsi
            'description': 'Gunakan alat ini untuk membuat contoh visual gaya melukis, teknik, atau konsep seni.'
        }
    ]
)

# Cetak ID asisten untuk konfirmasi
print(f"Art Maestro dibuat, ID: {painting_assistant.id}")

Langkah 3: Buat thread

Dalam API Asisten, thread mewakili konteks percakapan yang berkelanjutan.

Asisten menggunakan thread untuk memahami konteks percakapan dan memberikan tanggapan yang lebih koheren dan relevan.

Kami merekomendasikan Anda:

  • Buat thread baru untuk setiap pengguna baru atau topik percakapan.

  • Gunakan thread yang sama untuk mempertahankan konteks.

  • Pertimbangkan untuk membuat thread baru ketika topik percakapan berubah secara signifikan untuk mencegah kebingungan konteks.

Dalam skenario asisten lukisan, thread melacak seluruh proses, termasuk

  • Permintaan awal pengguna

  • Saran dari asisten

  • Umpan balik pengguna

  • Hasil lukisan akhir

Ini memastikan prosesnya koheren dan dapat dilacak.

Untuk panduan penggunaan, lihat Threads.

from http import HTTPStatus
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Buat thread kosong
thread = dashscope.Threads.create()

# Periksa apakah thread telah dibuat
if thread.status_code == HTTPStatus.OK:
    print(f"Thread dibuat, ID: {thread.id}")
    print("Anda sekarang dapat memulai dialog Anda dengan asisten")
else:
    print(f"Gagal membuat thread. Kode status: {thread.status_code}")
    print(f"Kode kesalahan: {thread.code}")
    print(f"Pesan kesalahan: {thread.message}")

# Catatan: thread kosong ini dapat digunakan untuk mempertahankan konteks diskusi Anda, 
# termasuk pesan masa depan apa pun tentang kucing Ragdoll atau subjek lukisan lainnya.

Langkah 4: Tambahkan pesan ke thread

Pesan masukan dari pengguna dilewatkan melalui objek pesan. API Asisten mendukung pengiriman beberapa pesan ke satu thread. Saat membuat pesan, tentukan parameter berikut:

  • thread_id: ID thread.

  • content: Isi pesan.

Jumlah token yang dapat diterima oleh thread tidak terbatas. Namun, token yang dilewatkan ke model dibatasi pada panjang input maksimum model. Untuk informasi lebih lanjut, lihat Ikhtisar model generasi teks.

Dalam skenario asisten lukisan, buat pesan dan kirim "Gambar seekor kucing Ragdoll." dalam thread.

Untuk panduan penggunaan, lihat Pesan

Catatan

Metode Messages.create() secara otomatis menambahkan pesan ke thread dan memicu pemrosesan latar belakang setelah eksekusi, melakukan operasi pembuatan dan pengiriman pesan secara bersamaan. Ini adalah perilaku default API.

from http import HTTPStatus
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Buat pesan untuk memberi tahu asisten apa yang harus dilakukan
message = dashscope.Messages.create(thread.id, content='Gambar seekor kucing Ragdoll.')

# Periksa apakah pesan telah dibuat
if message.status_code == HTTPStatus.OK:
    print('Pesan dibuat, ID: %s' % message.id)
else:
    print('Gagal membuat pesan. Kode status: %s, kode kesalahan: %s, pesan kesalahan: %s' % (message.status_code, message.code, message.message))

Langkah 5: Buat dan jalankan run

Setelah pesan ditetapkan ke thread tertentu, mulailah run untuk mengaktifkan asisten. Asisten secara cerdas menggunakan model dan plug-in yang ditentukan untuk menjawab pertanyaan berdasarkan konteks. Kemudian, asisten menyisipkan tanggapan ke dalam urutan pesan thread.

Lakukan langkah-langkah berikut:

  1. Inisialisasi objek run untuk mengaktifkan asisten lukisan dan lewati ID thread (thread.id) dan ID asisten (assistant.id).

  2. Gunakan metode Run.wait untuk menunggu hingga eksekusi selesai.

  3. Ambil gambar yang digambar dari asisten menggunakan metode Messages.list.

Seri operasi ini mengotomatiskan alur pemrosesan untuk asisten, dari menerima pertanyaan hingga menghasilkan hasil.

Untuk panduan penggunaan, lihat Runs.

Catatan

Karena beberapa pengguna mungkin menggunakan model secara bersamaan, yang berpotensi memperpanjang waktu pemrosesan, kami sarankan Anda menunggu hingga status menjadi "selesai" sebelum melanjutkan.

from http import HTTPStatus
import json
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Buat run baru untuk mengeksekusi pesan
run = dashscope.Runs.create(thread.id, assistant_id=assistant.id)
if run.status_code != HTTPStatus.OK:
    print('Gagal membuat asisten. Kode status: %s, kode kesalahan: %s, pesan kesalahan: %s' % (run.status_code, run.code, run.message))
else:
    print('Asisten dibuat, ID: %s' % run.id)

# Tunggu run selesai atau memerlukan tindakan
run = dashscope.Runs.wait(run.id, thread_id=thread.id)
if run.status_code != HTTPStatus.OK:
    print('Gagal mendapatkan status run. Kode status: %s, kode kesalahan: %s, pesan kesalahan: %s' % (run.status_code, run.code, run.message))
else:
    print(run)

# Ambil pesan thread untuk mendapatkan keluaran run
msgs = dashscope.Messages.list(thread.id)
if msgs.status_code != HTTPStatus.OK:
    print('Gagal mengambil pesan. Kode status: %s, kode kesalahan: %s, pesan kesalahan: %s' % (msgs.status_code, msgs.code, msgs.message))
else:
    print(json.dumps(msgs, default=lambda o: o.__dict__, sort_keys=True, indent=4))

Kode sampel lengkap

Keluaran non-streaming

import dashscope
from http import HTTPStatus
import json
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

def check_status(component, operation):
    if component.status_code == HTTPStatus.OK:
        print(f"{operation} berhasil.")
        return True
    else:
        print(f"{operation} gagal. Kode status: {component.status_code}, Kode kesalahan: {component.code}, Pesan kesalahan: {component.message}")
        return False


# 1. Buat asisten lukisan
painting_assistant = dashscope.Assistants.create(
    # Daftar model: https://www.alibabacloud.com/help/en/model-studio/getting-started/models
    model='qwen-max',
    name='Art Maestro',
    description='AI assistant untuk pengetahuan melukis dan seni',
    instructions='''Berikan informasi tentang teknik melukis, sejarah seni, dan panduan kreatif.
    Gunakan alat untuk menghasilkan gambar.''',
    tools=[
        {'type': 'text_to_image', 'description': 'Untuk membuat contoh visual'}
    ]
)

if not check_status(painting_assistant, "Pembuatan asisten"):
    exit()

# 2. Buat thread baru
thread = dashscope.Threads.create()

if not check_status(thread, "Pembuatan thread"):
    exit()

# 3. Kirim pesan ke thread
message = dashscope.Messages.create(thread.id, content='Gambar seekor kucing Ragdoll.')

if not check_status(message, "buat pesan"):
    exit()

# 4. Jalankan asisten pada thread
run = dashscope.Runs.create(thread.id, assistant_id=painting_assistant.id)

if not check_status(run, "Pembuatan run"):
    exit()

# 5. Tunggu run selesai
print("Menunggu asisten memproses permintaan...")
run = dashscope.Runs.wait(run.id, thread_id=thread.id)

if check_status(run, "Penyelesaian run"):
    print(f"Run selesai, status: {run.status}")
else:
    print("Run belum selesai.")
    exit()

# 6. Ambil dan tampilkan tanggapan asisten
messages = dashscope.Messages.list(thread.id)

if check_status(messages, "Pengambilan pesan"):
    if messages.data:
        # Tampilkan isi pesan terakhir (tanggapan asisten)
        last_message = messages.data[0]
        print("\nTanggapan asisten:")
        print(json.dumps(last_message, ensure_ascii=False, default=lambda o: o.__dict__, sort_keys=True, indent=4))
    else:
        print("Tidak ada pesan yang ditemukan dalam thread.")
else:
    print("Gagal mengambil tanggapan asisten.")

# Catatan: Kode ini membuat asisten lukisan, memulai percakapan tentang menggambar kucing Ragdoll,
# dan menampilkan tanggapan asisten.
package com.example;
import java.util.Arrays;
import com.alibaba.dashscope.protocol.Protocol;

import com.alibaba.dashscope.assistants.Assistant;
import com.alibaba.dashscope.assistants.AssistantParam;
import com.alibaba.dashscope.assistants.Assistants;
import com.alibaba.dashscope.common.GeneralListParam;
import com.alibaba.dashscope.common.ListResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.threads.AssistantThread;
import com.alibaba.dashscope.threads.ThreadParam;
import com.alibaba.dashscope.threads.Threads;
import com.alibaba.dashscope.threads.messages.Messages;
import com.alibaba.dashscope.threads.messages.TextMessageParam;
import com.alibaba.dashscope.threads.messages.ThreadMessage;
import com.alibaba.dashscope.threads.runs.Run;
import com.alibaba.dashscope.threads.runs.RunParam;
import com.alibaba.dashscope.threads.runs.Runs;
import com.alibaba.dashscope.tools.T2Image.Text2Image;
import com.alibaba.dashscope.tools.search.ToolQuarkSearch;
import com.alibaba.dashscope.utils.Constants;

public class PaintingAssistant {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    private static boolean checkStatus(Object response, String operation) {
        if (response != null) {
            System.out.println(operation + " berhasil.");
            return true;
        } else {
            System.out.println(operation + " gagal.");
            return false;
        }
    }

    public static void main(String[] args) {
        try {
            // 1. Buat asisten lukisan
            Assistants assistants = new Assistants();
            AssistantParam assistantParam = AssistantParam.builder()
                    // Daftar model: https://www.alibabacloud.com/help/en/model-studio/getting-started/models
                    .model("qwen-max")
                    .name("Art Maestro")
                    .description("AI assistant untuk pengetahuan melukis dan seni")
                    .instructions("Berikan informasi tentang teknik melukis, sejarah seni, dan panduan kreatif. Gunakan alat untuk meneliti dan menghasilkan gambar.")
                    .tools(Arrays.asList(ToolQuarkSearch.builder().build(),Text2Image.builder().build()))
                    .build();

            Assistant paintingAssistant = assistants.create(assistantParam);
            if (!checkStatus(paintingAssistant, "Pembuatan asisten")) {
                System.exit(1);
            }

            // 2. Buat thread baru
            Threads threads = new Threads();
            AssistantThread thread = threads.create(ThreadParam.builder().build());
            if (!checkStatus(thread, "Pembuatan thread")) {
                System.exit(1);
            }

            // 3. Kirim pesan ke thread
            Messages messages = new Messages();
            ThreadMessage message = messages.create(thread.getId(),
                    TextMessageParam.builder()
                            .role("user")
                            .content("Gambar seekor kucing Ragdoll.")
                            .build());
            if (!checkStatus(message, "buat pesan")) {
                System.exit(1);
            }

            // 4. Jalankan asisten pada thread
            Runs runs = new Runs();
            RunParam runParam = RunParam.builder().assistantId(paintingAssistant.getId()).build();
            Run run = runs.create(thread.getId(), runParam);
            if (!checkStatus(run, "Pembuatan run")) {
                System.exit(1);
            }

            // 5. Tunggu run selesai
            System.out.println("Menunggu asisten memproses permintaan...");
            while (true) {
                if (run.getStatus().equals(Run.Status.COMPLETED) ||
                        run.getStatus().equals(Run.Status.FAILED) ||
                        run.getStatus().equals(Run.Status.CANCELLED) ||
                        run.getStatus().equals(Run.Status.REQUIRES_ACTION) ||
                        run.getStatus().equals(Run.Status.EXPIRED)) {
                    break;
                }
                Thread.sleep(1000);
                run = runs.retrieve(thread.getId(), run.getId());
            }

            if (checkStatus(run, "Penyelesaian run")) {
                System.out.println("Run selesai, status: " + run.getStatus());
            } else {
                System.out.println("Run belum selesai.");
                System.exit(1);
            }

            // 6. Ambil dan tampilkan tanggapan asisten
            ListResult<ThreadMessage> messagesList = messages.list(thread.getId(), GeneralListParam.builder().build());
            if (checkStatus(messagesList, "Pengambilan pesan")) {
                if (!messagesList.getData().isEmpty()) {
                    // Tampilkan pesan terakhir (tanggapan asisten)
                    ThreadMessage lastMessage = messagesList.getData().get(0);
                    System.out.println("\nTanggapan asisten:");
                    System.out.println(lastMessage.getContent());
                } else {
                    System.out.println("Tidak ada pesan yang ditemukan dalam thread.");
                }
            } else {
                System.out.println("Gagal mengambil tanggapan asisten.");
            }

        } catch (ApiException | NoApiKeyException | InputRequiredException | InvalidateParameter | InterruptedException e) {
            e.printStackTrace();
        }
    }
}

Keluaran streaming

SDK Java saat ini tidak mendukung alat pembuatan gambar dalam mode keluaran streaming.

import dashscope
from http import HTTPStatus
import json
import sys
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

def check_status(response, operation):
    if response.status_code == HTTPStatus.OK:
        print(f"{operation} berhasil.")
        return True
    else:
        print(f"{operation} gagal. Kode status: {response.status_code}, Kode kesalahan: {response.code}, Pesan kesalahan: {response.message}")
        sys.exit(response.status_code)

# 1. Buat asisten lukisan
def create_painting_assistant():
    return dashscope.Assistants.create(
        model='qwen-max',
        name='Art Maestro',
        description='AI assistant untuk pengetahuan melukis dan seni',
        instructions='''Berikan informasi tentang teknik melukis, sejarah seni, dan panduan kreatif.
        Gunakan alat untuk meneliti dan menghasilkan gambar.''',
        tools=[
            {'type': 'text_to_image', 'description': 'Untuk membuat contoh visual'}
        ]
    )

if __name__ == '__main__':
    # Buat asisten lukisan
    painting_assistant = create_painting_assistant()
    print(painting_assistant)
    check_status(painting_assistant, "Pembuatan asisten")

    # Buat thread baru dengan pesan awal
    thread = dashscope.Threads.create(
        messages=[{
            'role': 'user',
            'content': 'Gambar seekor kucing Ragdoll.'
        }]
    )
    print(thread)
    check_status(thread, "Pembuatan thread")

    # Buat run streaming
    run_iterator = dashscope.Runs.create(
        thread.id,
        assistant_id=painting_assistant.id,
        stream=True
    )

    # Iterasi atas event dan pesan
    print("Memproses permintaan...")
    for event, msg in run_iterator:
        print(event)
        print(msg)

    # Ambil dan tampilkan tanggapan asisten
    messages = dashscope.Messages.list(thread.id)
    check_status(messages, "Pengambilan pesan")

    print("\nTanggapan asisten:")
    print(json.dumps(messages, ensure_ascii=False, default=lambda o: o.__dict__, sort_keys=True, indent=4))

# Catatan: Skrip ini membuat asisten lukisan streaming, memulai percakapan tentang menggambar kucing Ragdoll,
# dan menampilkan tanggapan asisten secara real-time.

Apa yang harus dilakukan selanjutnya

Untuk informasi lebih lanjut tentang parameter, lihat API Asisten.