Assistant API 為您提供了一套 Assistant 的開發工具,協助您方便地管理對話訊息,以及調用工具。本文以從零開始構建繪畫智能助手為例,協助您快速掌握 Assistant API 的基礎編碼方法。
典型流程
構建智能體應用(Assistant)的典型流程如下:
建立 Assistant:建立智能體時,您需要選擇模型、輸入指令並添加工具 + 生產力,如代碼解譯器和函數調用。
建立 Thread:當使用者發起對話時,建立一個會話線程來追蹤連續的對話歷史。
發送 Message 到 Thread:將使用者發送的訊息添加到對話中。
發起 Run:在會話線程上運行智能體,它會解析訊息,調用相應的工具或服務,產生響應並返回給您。
樣本情境
文本產生模型自身不具備產生映像的功能,一般需要通過特定的文生圖模型,可以將文本轉化為映像。藉助 Assistant API 建立的智能體應用,能夠自動最佳化使用者提供的描述詞,調用文生圖工具產生高品質映像。例如,為了產生一幅栩栩如生的寵物貓映像,您只需提供基礎描述,繪圖助手將自動完善提示詞,並直接輸入至文生圖工具中,高效完成映像繪製任務。
操作步驟
以下是在非流式輸出模式下,以 Python 為例的詳細流程指引。本文末尾還介紹了流式和非流式輸出的 Python 及 Java SDK 完整代碼。

第一步:準備開發環境
| |
第二步:建立 Assistant匯入 Dashscope SDK 後,您需使用 Assistant 類的 create 方法建立 Assistant 智能體。這一過程涉及以下關鍵參數的設定:
具體到我們的案例,目標是構建一個專註於繪畫的 Assistant。基於文生圖工具對語言理解能力的較高要求,我們選用了通義千問-Max作為文本推理模型,以此強化 Assistant 的語義理解和文本產生能力。 智能體的配置細節,包括其名稱、功能描述及指令,均在隨附的程式碼片段中有明確展示。 為了豐富智能體的功能性和實用性,我們整合了官方預置外掛程式圖片產生,確保智能體能夠根據接收到的文字描述,自動產生相應的映像內容。 建立 Assistant 沒有數量限制,但頻繁調用單一模型可能會觸發限流,建議根據 Assistant 的使用情境配置不同的模型。 相關使用方法請參考Assistants API。 | |
第三步:建立 ThreadThread(線程)是 Assistant API 中的一個關鍵概念,它代表了一個持續的對話上下文。 Thread 允許您在使用者啟動新對話時建立一個會話管理線程。Assistant 可以通過 Thread 理解整個對話的上下文,從而提供更加連貫和相關的回應。 建議您:
在繪畫助手的情境中,Thread 可以跟蹤使用者的初始請求、Assistant 的初步建議、使用者的反饋,以及最終的繪畫結果,形成一個完整的創作過程。這確保了整個創作過程的連貫性和可追溯性。 相關使用方法請參考Threads API。 | |
第四步:添加 Message 到 Thread您輸入的內容將通過 Message 對象傳遞。 Assistant API 支援向單一 Thread 發送一個或多個訊息。建立 Message 時,您需要考慮以下參數:
儘管 Thread 可接收的 Token 數量無硬性限制,但實際傳遞給大模型的 Token 數量需符合該模型的最大輸入長度限制,具體參照各通義千問系列模型的官方文檔中關於上下文長度的說明。 在我們的情境中,您將通過 Message 在 Thread 中發出第一條訊息:“請幫我畫一隻布偶貓的圖片”。您需要建立一個 Message 類,詳細參數設定均在隨附的程式碼片段中。 相關使用方法請參考Messages。 說明 Messages.create()方法執行後會自動將訊息加入線程並觸發幕後處理,相當於同時完成訊息建立和發送兩個操作,這是 API 的預設行為。 | |
第五步:建立 Run 並執行使用者將訊息分配至特定 Thread 後,可以通過啟動一個運行(Run)來啟用預設的助手(Assistant)。該助手會以線程內的所有訊息為背景,利用指定的模型和可用的外掛程式,智能地回應使用者的問題,並將產生的答案插入到線程的訊息序列中。 在本情境中,您需執行以下步驟:
這一系列操作確保了助手從接收問題到輸出結果的自動化處理流程。 相關使用方法請參考Runs API。 說明 考慮到可能會有大量使用者同時使用模型,導致處理時間延長,建議等候狀態顯示為"complete"後再執行下一步操作,以確保流程順暢。 | |
完整代碼
非流式輸出
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} 成功。")
return True
else:
print(f"{operation} 失敗。狀態代碼:{component.status_code},錯誤碼:{component.code},錯誤資訊:{component.message}")
return False
# 1. 建立繪畫助手
painting_assistant = dashscope.Assistants.create(
# 模型列表:https://www.alibabacloud.com/help/zh/model-studio/getting-started/models
model='qwen-max',
name='Art Maestro',
description='用於繪畫和藝術知識的AI助手',
instructions='''提供繪畫技巧、藝術史和創意指導的資訊。
使用工具進行研究和產生映像。''',
tools=[
{'type': 'text_to_image', 'description': '用於建立視覺樣本'}
]
)
if not check_status(painting_assistant, "助手建立"):
exit()
# 2. 建立一個新線程
thread = dashscope.Threads.create()
if not check_status(thread, "線程建立"):
exit()
# 3. 向線程發送訊息
message = dashscope.Messages.create(thread.id, content='請幫我畫一幅布偶貓的畫。')
if not check_status(message, "訊息建立"):
exit()
# 4. 線上程上運行助手
run = dashscope.Runs.create(thread.id, assistant_id=painting_assistant.id)
if not check_status(run, "運行建立"):
exit()
# 5. 等待運行完成
print("等待助手處理請求...")
run = dashscope.Runs.wait(run.id, thread_id=thread.id)
if check_status(run, "運行完成"):
print(f"運行完成,狀態:{run.status}")
else:
print("運行未完成。")
exit()
# 6. 檢索並顯示助手的響應
messages = dashscope.Messages.list(thread.id)
if check_status(messages, "訊息檢索"):
if messages.data:
# 顯示最後一條訊息的內容(助手的響應)
last_message = messages.data[0]
print("\n助手的回應:")
print(json.dumps(last_message, ensure_ascii=False, default=lambda o: o.__dict__, sort_keys=True, indent=4))
else:
print("線上程中未找到訊息。")
else:
print("未能檢索到助手的響應。")
# 提示: 這段代碼建立了一個繪畫助手,開始了一段關於如何繪製布偶貓的對話,
# 並展示了助手的回答。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 + " 成功。");
return true;
} else {
System.out.println(operation + " 失敗。");
return false;
}
}
public static void main(String[] args) {
try {
// 1. 建立繪畫助手
Assistants assistants = new Assistants();
AssistantParam assistantParam = AssistantParam.builder()
// 模型列表:https://www.alibabacloud.com/help/zh/model-studio/getting-started/models
.model("qwen-max")
.name("Art Maestro")
.description("用於繪畫和藝術知識的AI助手")
.instructions("提供繪畫技巧、藝術史和創意指導的資訊。使用工具進行研究和產生映像。")
.tools(Arrays.asList(ToolQuarkSearch.builder().build(),Text2Image.builder().build()))
.build();
Assistant paintingAssistant = assistants.create(assistantParam);
if (!checkStatus(paintingAssistant, "助手建立")) {
System.exit(1);
}
// 2. 建立一個新線程
Threads threads = new Threads();
AssistantThread thread = threads.create(ThreadParam.builder().build());
if (!checkStatus(thread, "線程建立")) {
System.exit(1);
}
// 3. 向線程發送訊息
Messages messages = new Messages();
ThreadMessage message = messages.create(thread.getId(),
TextMessageParam.builder()
.role("user")
.content("請幫我畫一幅布偶貓的畫。")
.build());
if (!checkStatus(message, "訊息建立")) {
System.exit(1);
}
// 4. 線上程上運行助手
Runs runs = new Runs();
RunParam runParam = RunParam.builder().assistantId(paintingAssistant.getId()).build();
Run run = runs.create(thread.getId(), runParam);
if (!checkStatus(run, "運行建立")) {
System.exit(1);
}
// 5. 等待運行完成
System.out.println("等待助手處理請求...");
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, "運行完成")) {
System.out.println("運行完成,狀態:" + run.getStatus());
} else {
System.out.println("運行未完成。");
System.exit(1);
}
// 6. 檢索並顯示助手的響應
ListResult<ThreadMessage> messagesList = messages.list(thread.getId(), GeneralListParam.builder().build());
if (checkStatus(messagesList, "訊息檢索")) {
if (!messagesList.getData().isEmpty()) {
// 顯示最後一條訊息(助手的響應)
ThreadMessage lastMessage = messagesList.getData().get(0);
System.out.println("\n助手的回應:");
System.out.println(lastMessage.getContent());
} else {
System.out.println("線上程中未找到訊息。");
}
} else {
System.out.println("未能檢索到助手的響應。");
}
} catch (ApiException | NoApiKeyException | InputRequiredException | InvalidateParameter | InterruptedException e) {
e.printStackTrace();
}
}
}
流式輸出
Java SDK 暫不支援流式調用圖片產生工具。
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} 成功。")
return True
else:
print(f"{operation} 失敗。狀態代碼:{response.status_code},錯誤碼:{response.code},錯誤資訊:{response.message}")
sys.exit(response.status_code)
# 1. 建立繪畫助手
def create_painting_assistant():
return dashscope.Assistants.create(
# 模型列表:https://www.alibabacloud.com/help/zh/model-studio/getting-started/models
model='qwen-max',
name='Art Maestro',
description='AI助手,用於繪畫和藝術知識',
instructions='''提供繪畫技巧、藝術史和創意指導的資訊。
使用工具進行研究和產生映像。''',
tools=[
{'type': 'text_to_image', 'description': '用於建立視覺樣本'}
]
)
if __name__ == '__main__':
# 建立繪畫助手
painting_assistant = create_painting_assistant()
print(painting_assistant)
check_status(painting_assistant, "助手建立")
# 建立一個帶有初始訊息的新線程
thread = dashscope.Threads.create(
messages=[{
'role': 'user',
'content': '請幫我畫一幅布偶貓的畫。'
}]
)
print(thread)
check_status(thread, "線程建立")
# 建立流式輸出的運行
run_iterator = dashscope.Runs.create(
thread.id,
assistant_id=painting_assistant.id,
stream=True
)
# 迭代事件和訊息
print("處理請求中...")
for event, msg in run_iterator:
print(event)
print(msg)
# 檢索並顯示助手的響應
messages = dashscope.Messages.list(thread.id)
check_status(messages, "訊息檢索")
print("\n助手的回應:")
print(json.dumps(messages, ensure_ascii=False, default=lambda o: o.__dict__, sort_keys=True, indent=4))
# 提示: 這個指令碼建立了一個流式輸出的繪畫助手,開始一段關於繪製布偶貓的對話,
# 並即時顯示助手的回應。
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 + " 成功。");
return true;
} else {
System.out.println(operation + " 失敗。");
return false;
}
}
private static Assistant createPaintingAssistant() throws ApiException, NoApiKeyException {
Assistants assistants = new Assistants();
AssistantParam assistantParam = AssistantParam.builder()
// 模型列表:https://www.alibabacloud.com/help/zh/model-studio/getting-started/models
.model("qwen-max")
.name("Art Maestro")
.description("用於繪畫和藝術知識的AI助手")
.instructions("提供繪畫技巧、藝術史和創意指導的資訊。使用工具進行研究和產生映像。")
.tools(Arrays.asList(ToolQuarkSearch.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, "線程建立")) {
System.exit(1);
}
Messages messages = new Messages();
ThreadMessage message = messages.create(thread.getId(),
TextMessageParam.builder()
.role("user")
.content("請幫我畫一幅布偶貓的畫。")
.build());
if (!checkStatus(message, "訊息建立")) {
System.exit(1);
}
Runs runs = new Runs();
RunParam runParam = RunParam.builder().assistantId(assistantId).stream(true).build();
try {
System.out.println("嘗試流式輸出助手的響應...");
Flowable<AssistantStreamMessage> runFlowable = runs.createStream(thread.getId(), runParam);
runFlowable.blockingForEach(assistantStreamMessage -> {
System.out.println("事件:" + assistantStreamMessage.getEvent());
System.out.println("資料:" + assistantStreamMessage.getData());
});
} catch (Exception e) {
System.out.println("流式輸出失敗,切換為非流式輸出方法。");
e.printStackTrace();
// 切換到非流式輸出方法
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.getStatus());
}
// 檢索並顯示助手的響應
GeneralListParam listParam = GeneralListParam.builder().limit(100L).build();
ListResult<ThreadMessage> messagesList = messages.list(thread.getId(), listParam);
if (checkStatus(messagesList, "訊息檢索")) {
if (!messagesList.getData().isEmpty()) {
System.out.println("\n助手的回應:");
for (ThreadMessage threadMessage : messagesList.getData()) {
System.out.println(threadMessage.getContent());
}
} else {
System.out.println("線上程中未找到訊息。");
}
} else {
System.out.println("未能檢索到助手的響應。");
}
}
public static void main(String[] args) {
try {
Assistant paintingAssistant = createPaintingAssistant();
if (!checkStatus(paintingAssistant, "助手建立")) {
System.exit(1);
}
runPaintingAssistant(paintingAssistant.getId());
} catch (ApiException | NoApiKeyException | InputRequiredException | InvalidateParameter | InterruptedException e) {
System.out.println("運行繪畫助手時發生錯誤:");
e.printStackTrace();
}
}
}
後續操作
如需深入瞭解 Assistant API 各組件的參數解釋,請參閱Assistant API 開發參考。