Skip to main content
Assistant API (Deprecated)

Memulai dengan Assistant API (Tidak Digunakan Lagi)

Assistant API menyediakan serangkaian alat pengembangan untuk membantu Anda mengelola pesan percakapan dan memanggil tool secara mudah. Topik ini menggunakan contoh pembuatan asisten pelukis dari awal untuk membantu Anda mempelajari metode pengkodean dasar Assistant API dengan cepat.

Assistant API sudah tidak digunakan lagi. Migrasikan ke Responses API sebagai alternatif. Responses API mencakup beberapa tool bawaan dan mendukung manajemen konteks multi-turn.

Proses khas

Berikut adalah proses khas untuk membangun aplikasi agen (Assistant):
  1. Buat Assistant: Saat membuat assistant, pilih model, berikan instruksi, dan tambahkan tool, seperti code interpreter dan function calling.
  2. Buat Thread: Saat pengguna memulai percakapan, buat thread sesi untuk melacak riwayat percakapan.
  3. Kirim Pesan ke Thread: Tambahkan pesan pengguna ke percakapan.
  4. Mulai Run: Jalankan assistant pada thread sesi. Assistant mengurai pesan, memanggil tool atau layanan yang sesuai, menghasilkan respons, dan mengembalikannya kepada Anda.

Contoh skenario

Model generasi teks tidak dapat menghasilkan gambar secara mandiri. Biasanya diperlukan model teks-ke-gambar khusus untuk mengonversi teks menjadi gambar. Aplikasi agen yang dibuat dengan Assistant API dapat secara otomatis mengoptimalkan kata-kata deskriptif yang diberikan pengguna, memanggil tool teks-ke-gambar untuk menghasilkan gambar berkualitas tinggi. Misalnya, untuk menghasilkan gambar kucing peliharaan yang realistis, Anda hanya perlu memberikan deskripsi dasar. Asisten pelukis secara otomatis menyempurnakan prompt tersebut dan meneruskannya langsung ke tool teks-ke-gambar untuk menyelesaikan tugas pembuatan gambar secara efisien.

Prosedur

Langkah-langkah berikut memandu Anda melalui proses dalam Python untuk mode output non-streaming. Untuk kode SDK Python dan Java lengkap—baik untuk output streaming maupun non-streaming—lihat Kode lengkap di akhir topik ini.
image

Langkah 1: Siapkan lingkungan pengembangan

  • Minta izin untuk menggunakan plug-in: Anda harus terlebih dahulu meminta izin untuk menggunakan plug-in generasi gambar. Buka halaman Plug-ins di Konsol Model Studio dan klik Apply for Plug-in pada kartu yang sesuai.
  • Interpreter Python: Assistant API memerlukan Python 3.9 atau versi lebih baru. Anda dapat memeriksa versi Python Anda. Untuk menginstal versi Python tertentu, lihat Download Python.
  • DashScope SDK: Kami menyarankan Anda menggunakan versi terbaru DashScope SDK. Anda dapat menggunakan perintah di samping untuk memeriksa versi Anda. Untuk menginstal versi tertentu DashScope SDK, gunakan pip.
  • Kunci API: Assistant API memerlukan Kunci API Alibaba Cloud Model Studio. Anda dapat mendapatkan kunci API di sini. Saat pertama kali menggunakan DashScope SDK, kami menyarankan Anda mengonfigurasi kunci API sebagai Variabel lingkungan untuk menghindari paparan informasi sensitif.
# Periksa versi interpreter Python
python --version

# Periksa DashScope SDK
pip list | grep dashscope

# Instal DashScope SDK versi 1.17.0
pip install dashscope==1.17.0

Langkah 2: Buat Assistant

Setelah Anda mengimpor Dashscope SDK, gunakan metode create dari kelas Assistant untuk membuat agen Assistant. Proses ini melibatkan pengaturan parameter kunci berikut:
  • model: nama model bahasa besar, digunakan untuk mengonfigurasi LLM bagi agen
  • name: nama agen, digunakan untuk membedakannya
  • description: deskripsi fungsi agen
  • instructions: instruksi dalam bahasa alami yang menentukan peran dan tugas agen
  • tools: daftar tool yang dikonfigurasi untuk agen
Dalam contoh kami, tujuannya adalah membangun Assistant yang fokus pada melukis. Karena tool teks-ke-gambar memiliki persyaratan tinggi terhadap pemahaman bahasa, kami memilih Qwen-Max sebagai Model penalaran untuk meningkatkan kemampuan pemahaman semantik dan generasi teks Assistant.Rincian konfigurasi agen, termasuk nama, deskripsi fungsi, dan instruksinya, ditampilkan secara jelas dalam potongan kode yang menyertainya.Untuk memperkaya fungsionalitas dan kepraktisan agen, kami mengintegrasikan plug-in resmi yang telah dibuat sebelumnya Image Generation. Ini memastikan agen dapat secara otomatis menghasilkan konten gambar yang sesuai berdasarkan deskripsi teks yang diterima.Anda dapat membuat jumlah Assistant yang tidak terbatas. Namun, pemanggilan yang sering ke satu model tunggal dapat memicu Pembatasan laju. Kami menyarankan Anda mengonfigurasi model yang berbeda untuk Assistant Anda berdasarkan kasus penggunaannya.Untuk informasi selengkapnya tentang cara menggunakan API, lihat Assistants API.
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Buat asisten melukis baru menggunakan Qwen-Max
painting_assistant = dashscope.Assistants.create(
    model='qwen-max',  # Gunakan model Qwen-Max untuk pemahaman yang lebih baik. Daftar model: https://www.alibabacloud.com/help/en/model-studio/getting-started/models
    name='Art Maestro',  # Nama assistant adalah "Art Maestro"
    description='Asisten AI yang mengkhususkan diri dalam pengetahuan lukisan dan seni.',
    instructions='''Anda adalah asisten melukis ahli. Berikan informasi rinci tentang teknik melukis, sejarah seni, dan panduan kreatif.''',
    tools=[
        {
            'type': 'text_to_image',  # Tool untuk menghasilkan gambar berdasarkan deskripsi
            'description': 'Gunakan tool ini untuk membuat contoh visual gaya lukisan, teknik, atau konsep seni.'
        }
    ]
)

# Cetak ID assistant untuk mengonfirmasi pembuatan berhasil
print(f"Asisten melukis 'Art Maestro' berhasil dibuat, ID: {painting_assistant.id}")

Langkah 3: Buat Thread

Thread adalah konsep kunci dalam Assistant API yang merepresentasikan konteks percakapan berkelanjutan.Thread memungkinkan Anda membuat thread manajemen sesi saat pengguna memulai percakapan baru. Assistant dapat menggunakan Thread untuk memahami seluruh konteks percakapan dan memberikan respons yang lebih koheren dan relevan.Kami menyarankan Anda:
  • Buat Thread baru untuk setiap pengguna baru atau topik percakapan baru.
  • Lanjutkan menggunakan Thread yang sama saat Anda perlu mempertahankan konteks.
  • Pertimbangkan untuk membuat Thread baru saat topik percakapan berubah secara signifikan untuk menghindari kebingungan konteks.
Dalam skenario asisten melukis, Thread dapat melacak permintaan awal pengguna, saran awal Assistant, umpan balik pengguna, dan hasil lukisan akhir, membentuk proses kreasi yang lengkap. Hal ini memastikan koherensi dan jejakabilitas seluruh proses kreasi.Untuk informasi selengkapnya tentang cara menggunakan API, lihat Threads API.
from http import HTTPStatus
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

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

# Periksa apakah thread berhasil dibuat
if thread.status_code == HTTPStatus.OK:
    print(f"Thread berhasil dibuat. ID Thread: {thread.id}")
    print("Anda sekarang dapat memulai percakapan melukis dengan asisten AI.")
else:
    print(f"Pembuatan thread gagal. Kode status: {thread.status_code}")
    print(f"Kode error: {thread.code}")
    print(f"Pesan error: {thread.message}")

# Catatan: Thread kosong ini sekarang dapat digunakan untuk mempertahankan konteks diskusi proyek melukis Anda,
# termasuk pesan mendatang tentang kucing ragdoll atau subjek melukis lainnya.

Langkah 4: Tambahkan Pesan ke Thread

Input Anda diteruskan melalui objek Message. Assistant API mendukung pengiriman satu atau beberapa pesan ke satu Thread. Saat membuat Message, pertimbangkan parameter berikut:
  • ID unik Thread: thread_id
  • Konten pesan: content
Meskipun tidak ada batasan keras pada jumlah token yang dapat diterima Thread, jumlah token aktual yang diteruskan ke LLM harus mematuhi batas panjang input maksimum model. Untuk informasi selengkapnya, lihat dokumentasi resmi setiap model seri Qwen mengenai panjang konteks.Dalam skenario kami, Anda akan mengirim pesan pertama dalam Thread melalui Message: "Please help me draw a picture of a ragdoll cat." Anda perlu membuat kelas Message. Pengaturan parameter rinci disediakan dalam potongan kode yang menyertainya.Untuk informasi selengkapnya tentang cara menggunakan API, lihat Messages.
Setelah metode Messages.create() dieksekusi, pesan tersebut secara otomatis ditambahkan ke thread dan memicu spooling. Ini setara dengan menyelesaikan operasi pembuatan dan pengiriman pesan sekaligus, yang merupakan 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 assistant apa yang harus dilakukan.
message = dashscope.Messages.create(thread.id, content='Please help me draw a picture of a ragdoll cat.')

# Periksa apakah pesan berhasil dibuat
if message.status_code == HTTPStatus.OK:
    print('Pesan berhasil dibuat! ID Pesan: %s' % message.id)
else:
    print('Pembuatan pesan gagal. Kode status: %s, Kode error: %s, Pesan error: %s' % (message.status_code, message.code, message.message))

Langkah 5: Buat dan jalankan Run

Setelah pengguna menetapkan pesan ke Thread tertentu, Anda dapat memulai Run untuk mengaktifkan Assistant yang telah ditetapkan sebelumnya. Assistant menggunakan semua pesan dalam thread sebagai konteks, memanfaatkan model yang ditentukan dan plug-in yang tersedia untuk merespons pertanyaan pengguna secara cerdas, serta memasukkan jawaban yang dihasilkan ke dalam urutan pesan thread.Dalam skenario ini, lakukan langkah-langkah berikut:
  1. Inisialisasi objek run untuk menggerakkan asisten melukis, dengan meneruskan ID thread (thread.id) dan ID assistant (assistant.id).
  2. Gunakan metode wait objek run (Run.wait) hingga eksekusi selesai.
  3. Gunakan metode daftar pesan (Messages.list) untuk mengambil gambar kucing peliharaan yang digambar oleh assistant.
Rangkaian operasi ini memastikan alur pemrosesan otomatis untuk assistant, mulai dari menerima pertanyaan hingga mengeluarkan hasil.Untuk informasi selengkapnya tentang cara menggunakan API, lihat Runs API.
Banyak pengguna mungkin menggunakan model secara bersamaan, yang dapat memperpanjang waktu pemrosesan. Kami menyarankan Anda menunggu hingga status menunjukkan "complete" sebelum melakukan operasi berikutnya untuk memastikan proses berjalan lancar.
from http import HTTPStatus
import json
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Buat run baru untuk menjalankan pesan
run = dashscope.Runs.create(thread.id, assistant_id=painting_assistant.id)
if run.status_code != HTTPStatus.OK:
    print('Gagal membuat assistant, Kode status: %s, Kode error: %s, Pesan error: %s' % (run.status_code, run.code, run.message))
else:
    print('Assistant berhasil dibuat, ID: %s' % run.id)

# Tunggu hingga run selesai atau memerlukan aksi
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 error: %s, Pesan error: %s' % (run.status_code, run.code, run.message))
else:
    print(run)

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

Kode lengkap

  • Output non-streaming
  • Output 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 error: {component.code}, Pesan error: {component.message}")
        return False

# 1. Buat asisten melukis
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='Asisten AI untuk pengetahuan lukisan dan seni',
    instructions='''Berikan informasi tentang teknik melukis, sejarah seni, dan panduan kreatif.
    Gunakan tool untuk riset dan generasi gambar.''',
    tools=[
        {'type': 'text_to_image', 'description': 'Untuk membuat contoh visual'}
    ]
)

if not check_status(painting_assistant, "Pembuatan Assistant"):
    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='Please help me draw a picture of a ragdoll cat.')

if not check_status(message, "Pembuatan Pesan"):
    exit()

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

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

# 5. Tunggu hingga run selesai
print("Menunggu assistant 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 respons assistant
messages = dashscope.Messages.list(thread.id)

if check_status(messages, "Pengambilan Pesan"):
    if messages.data:
        # Tampilkan konten pesan terakhir (respons assistant)
        last_message = messages.data[0]
        print("\nRespons Assistant:")
        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 respons assistant.")

# Tip: Kode ini membuat asisten melukis, memulai percakapan tentang cara menggambar kucing ragdoll,
# dan menampilkan jawaban assistant.

Langkah selanjutnya

Untuk penjelasan parameter terperinci mengenai komponen Assistant API, lihat Assistant API development reference.
Mulai
Pengembangan aplikasi
Prompt
Data aplikasi
Basis Pengetahuan (RAG)
Plugin
Pemanggilan Aplikasi
Perizinan
Assistant API (Deprecated)
Dukungan