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:
Buat asisten: Saat membuat asisten, pilih model, masukkan instruksi, dan tambahkan alat seperti interpreter kode serta pemanggilan fungsi.
Buat thread: Buat thread sesi untuk mempertahankan kontinuitas percakapan ketika pengguna memulai dialog.
Kirim pesan ke thread: Tambahkan pesan pengguna ke thread sesi satu per satu.
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.

Langkah 1: Siapkan lingkungan pengembangan
| |
Langkah 2: Buat asistenSetelah mengimpor SDK DashScope, buat asisten menggunakan metode create dari kelas asisten. Tentukan parameter kunci berikut:
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. | |
Langkah 3: Buat threadDalam 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:
Dalam skenario asisten lukisan, thread melacak seluruh proses, termasuk
Ini memastikan prosesnya koheren dan dapat dilacak. Untuk panduan penggunaan, lihat Threads. | |
Langkah 4: Tambahkan pesan ke threadPesan masukan dari pengguna dilewatkan melalui objek pesan. API Asisten mendukung pengiriman beberapa pesan ke satu thread. Saat membuat pesan, tentukan parameter berikut:
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. | |
Langkah 5: Buat dan jalankan runSetelah 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:
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. | |
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.