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.
PentingAssistant 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):
- Buat Assistant: Saat membuat assistant, pilih model, berikan instruksi, dan tambahkan tool, seperti code interpreter dan function calling.
- Buat Thread: Saat pengguna memulai percakapan, buat thread sesi untuk melacak riwayat percakapan.
- Kirim Pesan ke Thread: Tambahkan pesan pengguna ke percakapan.
- 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.
Langkah 1: Siapkan lingkungan pengembangan
| |
Langkah 2: Buat AssistantSetelah Anda mengimpor Dashscope SDK, gunakan metode create dari kelas Assistant untuk membuat agen Assistant. Proses ini melibatkan pengaturan parameter kunci berikut:
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. | |
Langkah 3: Buat ThreadThread 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:
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. | |
Langkah 4: Tambahkan Pesan ke ThreadInput Anda diteruskan melalui objek Message. Assistant API mendukung pengiriman satu atau beberapa pesan ke satu Thread. Saat membuat Message, pertimbangkan parameter berikut:
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. CatatanSetelah 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. | |
Langkah 5: Buat dan jalankan RunSetelah 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:
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. CatatanBanyak 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. | |
Kode lengkap
Output 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 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.
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 + " successful.");
return true;
} else {
System.out.println(operation + " failed.");
return false;
}
}
public static void main(String[] args) {
try {
// 1. Membuat asisten melukis
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 for painting and art knowledge")
.instructions("Provide information on painting techniques, art history, and creative guidance. Use tools for research and image generation.")
.tools(Arrays.asList(ToolQuarkSearch.builder().build(),Text2Image.builder().build()))
.build();
Assistant paintingAssistant = assistants.create(assistantParam);
if (!checkStatus(paintingAssistant, "Assistant creation")) {
System.exit(1);
}
// 2. Membuat thread baru
Threads threads = new Threads();
AssistantThread thread = threads.create(ThreadParam.builder().build());
if (!checkStatus(thread, "Thread creation")) {
System.exit(1);
}
// 3. Mengirim pesan ke thread
Messages messages = new Messages();
ThreadMessage message = messages.create(thread.getId(),
TextMessageParam.builder()
.role("user")
.content("Please help me draw a picture of a ragdoll cat.")
.build());
if (!checkStatus(message, "Message creation")) {
System.exit(1);
}
// 4. Menjalankan 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, "Run creation")) {
System.exit(1);
}
// 5. Menunggu hingga run selesai
System.out.println("Waiting for the assistant to process the request...");
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, "Run completion")) {
System.out.println("Run completed, status: " + run.getStatus());
} else {
System.out.println("Run not completed.");
System.exit(1);
}
// 6. Mengambil dan menampilkan tanggapan asisten
ListResult<ThreadMessage> messagesList = messages.list(thread.getId(), GeneralListParam.builder().build());
if (checkStatus(messagesList, "Message retrieval")) {
if (!messagesList.getData().isEmpty()) {
// Menampilkan pesan terakhir (tanggapan asisten)
ThreadMessage lastMessage = messagesList.getData().get(0);
System.out.println("\nAssistant's response:");
System.out.println(lastMessage.getContent());
} else {
System.out.println("No messages found in the thread.");
}
} else {
System.out.println("Failed to retrieve the assistant's response.");
}
} catch (ApiException | NoApiKeyException | InputRequiredException | InvalidateParameter | InterruptedException e) {
e.printStackTrace();
}
}
}
Output streaming
SDK Java saat ini tidak mendukung panggilan streaming untuk tool generasi gambar.
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 error: {response.code}, Pesan error: {response.message}")
sys.exit(response.status_code)
# 1. Buat asisten melukis
def create_painting_assistant():
return 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 __name__ == '__main__':
# Buat asisten melukis
painting_assistant = create_painting_assistant()
print(painting_assistant)
check_status(painting_assistant, "Pembuatan Assistant")
# Buat thread baru dengan pesan awal
thread = dashscope.Threads.create(
messages=[{
'role': 'user',
'content': 'Please help me draw a picture of a ragdoll cat.'
}]
)
print(thread)
check_status(thread, "Pembuatan Thread")
# Buat run dengan output streaming
run_iterator = dashscope.Runs.create(
thread.id,
assistant_id=painting_assistant.id,
stream=True
)
# Iterasi melalui event dan pesan
print("Memproses permintaan...")
for event, msg in run_iterator:
print(event)
print(msg)
# Ambil dan tampilkan respons assistant
messages = dashscope.Messages.list(thread.id)
check_status(messages, "Pengambilan Pesan")
print("\nRespons Assistant:")
print(json.dumps(messages, ensure_ascii=False, default=lambda o: o.__dict__, sort_keys=True, indent=4))
# Tip: Skrip ini membuat asisten melukis dengan output streaming, memulai percakapan tentang menggambar kucing ragdoll,
# dan menampilkan respons assistant secara real time.
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.AssistantStreamMessage;
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 io.reactivex.Flowable;
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;
}
}
private static Assistant createPaintingAssistant() throws ApiException, NoApiKeyException {
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("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(Arrays.asList(ToolQuarkSearch.builder().build(), Text2Image.builder().build()))
.build();
return assistants.create(assistantParam);
}
private static void runPaintingAssistant(String assistantId) throws ApiException, NoApiKeyException, InvalidateParameter, InputRequiredException, InterruptedException {
Threads threads = new Threads();
AssistantThread thread = threads.create(ThreadParam.builder().build());
if (!checkStatus(thread, "Pembuatan Thread")) {
System.exit(1);
}
Messages messages = new Messages();
ThreadMessage message = messages.create(thread.getId(),
TextMessageParam.builder()
.role("user")
.content("Please help me draw a picture of a ragdoll cat.")
.build());
if (!checkStatus(message, "Pembuatan Pesan")) {
System.exit(1);
}
Runs runs = new Runs();
RunParam runParam = RunParam.builder().assistantId(assistantId).stream(true).build();
try {
System.out.println("Mencoba melakukan streaming respons assistant...");
Flowable<AssistantStreamMessage> runFlowable = runs.createStream(thread.getId(), runParam);
runFlowable.blockingForEach(assistantStreamMessage -> {
System.out.println("Event: " + assistantStreamMessage.getEvent());
System.out.println("Data: " + assistantStreamMessage.getData());
});
} catch (Exception e) {
System.out.println("Streaming gagal, beralih ke metode non-streaming.");
e.printStackTrace();
// Beralih ke metode non-streaming
Run run = runs.create(thread.getId(), RunParam.builder().assistantId(assistantId).build());
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());
}
System.out.println("Run selesai, status: " + run.getStatus());
}
// Ambil dan tampilkan respons assistant
GeneralListParam listParam = GeneralListParam.builder().limit(100L).build();
ListResult<ThreadMessage> messagesList = messages.list(thread.getId(), listParam);
if (checkStatus(messagesList, "Pengambilan Pesan")) {
if (!messagesList.getData().isEmpty()) {
System.out.println("\nRespons Assistant:");
for (ThreadMessage threadMessage : messagesList.getData()) {
System.out.println(threadMessage.getContent());
}
} else {
System.out.println("Tidak ada pesan yang ditemukan dalam thread.");
}
} else {
System.out.println("Gagal mengambil respons assistant.");
}
}
public static void main(String[] args) {
try {
Assistant paintingAssistant = createPaintingAssistant();
if (!checkStatus(paintingAssistant, "Pembuatan Assistant")) {
System.exit(1);
}
runPaintingAssistant(paintingAssistant.getId());
} catch (ApiException | NoApiKeyException | InputRequiredException | InvalidateParameter | InterruptedException e) {
System.out.println("Terjadi kesalahan saat menjalankan asisten melukis:");
e.printStackTrace();
}
}
}
Langkah selanjutnya
Untuk penjelasan parameter terperinci mengenai komponen Assistant API, lihat Assistant API development reference.