Assistant API 旨在簡化 Assistant(一種大模型應用)的構建流程。本文詳細介紹了 Assistant API 提供的各項 Assistant 管理方法,包括 Assistant 的建立、列舉、檢索、更新和刪除操作。
功能介紹:如果您想瞭解 Assistant API 的功能和基本用法,請參考Assistant API功能概覽。
有效期間限:所有 Assistant 執行個體均儲存在阿里雲百鍊伺服器上,目前沒有失效日期,您可通過 assistant.id 檢索智能體。
建立智能體
建立一個新的智能體。
HTTP
程式碼範例
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/assistants' \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"model": "qwen-max",
"name": "Intelligent assistant",
"description": "This is an intelligent assistant",
"instructions": "You are an intelligent assistant that can call different tools based on user query and then give responses. Please use tools when needed.",
"tools": [
{
"type": "code_interpreter"
}
],
"metadata": {}
}'輸入參數
參數名 | 描述 | 參數類型 | 是否必須 |
model | 智能體所使用的模型 | str | 是 |
name | 智能體使用的名字 | str | 否 |
description | 用於描述智能體的文字 | str | 否 |
instructions | System prompt 用於智能體裡的大模型 | str | 否 |
tools | 一個可以被智能體調用tools list. 自訂外掛程式的鑒權資訊傳遞 | Optional[List[Dict]] | 否(default=[]) |
metadata | 其他相關參數用於智能體,用於儲存其他相關參數 | Dict | 否 |
temperature | 用於控制隨機性和多樣性的程度。 | float | 否 |
top_p | 產生時,核採樣方法的機率閾值。 | float | 否 |
top_k | 產生時,採樣候選集的大小。 | integer | 否 |
返回結果
{
"id": "asst_49079f4b-d1e8-4015-a12e-2dcdd1f18d84",
"object": "assistant",
"created_at": 1711713885724,
"model": "qwen-max",
"name": "智能小助手",
"description": "這是一個智能小助手",
"instructions": "你是一個智能小助手,你可以根據使用者的需求去調用不同的工具,進而給出回答。請酌情使用工具。",
"tools": [
{
"type": "code_interpreter"
}
],
"metadata": {},
"temperature": null,
"top_p": null,
"top_k": null,
"max_tokens": null,
"request_id": "b1778226-3865-9006-9e95-56329a710322"
}輸出參數
一個智能體對象。
SDK
程式碼範例
from dashscope import Assistants
import os
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
assistant = Assistants.create(
# 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 此處以qwen-max為例,可按需更換模型名稱。模型列表:https://www.alibabacloud.com/help/zh/model-studio/getting-started/models
model='qwen-max',
name='smart helper',
description='A tool helper.',
instructions='You are a helpful assistant. When asked a question, use tools wherever possible.',
tools=[{
'type': 'search'
}, {
'type': 'function',
'function': {
'name': 'big_add',
'description': 'Add to number',
'parameters': {
'type': 'object',
'properties': {
'left': {
'type': 'integer',
'description': 'The left operator'
},
'right': {
'type': 'integer',
'description': 'The right operator.'
}
},
'required': ['left', 'right']
}
}
}],
)
print(assistant)
import com.alibaba.dashscope.assistants.Assistant;
import com.alibaba.dashscope.assistants.AssistantParam;
import com.alibaba.dashscope.assistants.Assistants;
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 java.lang.System;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
public class Main {
static {
Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
}
public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
Assistants assistants = new Assistants();
// build assistant parameters
AssistantParam param = AssistantParam.builder()
// 此處以qwen-max為例,可按需更換模型名稱。模型列表:https://www.alibabacloud.com/help/zh/model-studio/getting-started/models
.model("qwen-max")
.name("intelligent guide")
.description("a smart guide")
.instructions("You are a helpful assistant.")
// 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.build();
Assistant assistant = assistants.create(param);
System.out.println(JsonUtils.toJson(assistant));
// use assistant
}
}輸入參數
參數 | 類型 | 預設值 | 說明 |
model | string | - | 指定用於智能體所使用的模型 |
name | string | - | 指定智能體名稱 |
description | string | - | 智能體描述 |
instructions | string | - | 指定智能體功能資訊 |
tools | array | [] | 智能體使用的tools 說明 自訂tool鑒權資訊傳遞
assistant在請求外掛程式時會將bearer放在 |
metadata | object | None | 智能體關聯資訊 |
workspace | string | None | 阿里雲百鍊的Workspace ID,僅當 api_key 為子業務空間 API Key 時才需要傳入。 |
api_key | string | None | 阿里雲百鍊的API Key,建議您配置API Key到環境變數(準備下線,併入配置 API Key)。 |
返回結果
{
"tools":[
{
"type":"search"
},
{
"function":{
"name":"big_add",
"description":"Add to number",
"parameters":{
"type":"object",
"properties":{
"left":{
"type":"integer",
"description":"The left operator"
},
"right":{
"type":"integer",
"description":"The right operator."
}
},
"required":[
"left",
"right"
]
}
},
"type":"function"
}
],
"id":"asst_714cac72-81b2-49bf-a75d-c575b90a9398",
"object":"assistant",
"created_at":1726033638848,
"model":"qwen-max",
"name":"smart helper",
"description":"A tool helper.",
"instructions":"You are a helpful assistant. When asked a question, use tools wherever possible.",
"file_ids":[
],
"metadata":{
},
"temperature":"None",
"top_p":"None",
"top_k":"None",
"max_tokens":"None",
"request_id":"00f5962e-8d9f-92fd-9320-3173fa1525d6",
"status_code":200
}輸出參數
欄位名 | 欄位類型 | 欄位描述 |
status_code | integer | 為調用http status code,200表示調用成功,其他表示調用出錯。 |
name | string | 智能體名稱。 |
id | string | 智能體ID,為uuid字串。 |
model | string | 智能體使用的模型名稱。 |
description | string | 智能體描述資訊。 |
instructions | string | 指定智能體功能資訊。 |
metadata | object | 智能體的中繼資料。 |
tools | array | 智能體可以用的tool列表。 |
created_at | integer | 智能體建立的時間戳記表示。 |
code | string | 表示請求失敗,表示錯誤碼,請求成功時忽略。只有在通過Python調用失敗時會顯示。 |
message | string | 失敗,表示失敗詳細資料,成功忽略。只有在通過Python調用失敗時會顯示。 |
列出智能體
用於返回智能體列表。
HTTP
程式碼範例
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/assistants?limit=2&order=desc' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"輸入參數
輸入參數名字 | 輸入參數的描述 | 參數類型 | 是否必須 |
limit | 建立智能體的數量 | int | 否 |
order | 按照建立時間升序或降序 | str | 否(預設為 |
返回結果
{
"object": "list",
"data": [
{
"id": "asst_0678aa33-43e2-4268-95e6-b0010f9f7937",
"object": "assistant",
"created_at": 1711435564909,
"model": "qwen-max",
"name": "智能小助手",
"description": "這是一個智能小助手",
"instructions": "你是一個智能小助手,你可以根據使用者的需求去調用不同的工具,進而給出回答。請酌情使用工具。",
"tools": [
{
"type": "search"
},
{
"type": "text_to_image"
},
{
"type": "code_interpreter"
}
],
"metadata": {}
},
{
"id": "asst_7af23142-52bc-4218-aa98-dfdb1128f19c",
"object": "assistant",
"created_at": 1711422620443,
"model": "qwen-max",
"name": "helpful assistant",
"description": "",
"instructions": "You are a helpful assistant.",
"tools": [
{
"type": "text_to_image"
}
],
"file_ids": [],
"metadata": {}
}
],
"first_id": "asst_0678aa33-43e2-4268-95e6-b0010f9f7937",
"last_id": "asst_7af23142-52bc-4218-aa98-dfdb1128f19c",
"has_more": true,
"request_id": "bc257359-ce86-9547-98be-d804effba8d1"
}輸出參數
輸出一個智能體對象列表。
SDK
程式碼範例
import dashscope
from dashscope import Assistants
import os
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
assistants = Assistants.list(
# 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
limit=1,
order='desc'
)import com.alibaba.dashscope.assistants.Assistant;
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.utils.Constants;
public class Main {
static {
Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
}
public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
Assistants assistants = new Assistants();
GeneralListParam listParam = GeneralListParam.builder()
// 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.limit(10l)
.build();
ListResult<Assistant> assistant = assistants.list(listParam);
}
}輸入參數
參數 | 類型 | 預設值 | 說明 |
limit | string | None | 指定列出assistant的數目,如果未指定則使用服務端預設值。 |
order | string | None | 排序方式,可選值:desc(降序)、asc(升序),如果未指定則使用服務端預設值。 |
workspace | string | None | 阿里雲百鍊的Workspace ID,僅當 api_key 為子業務空間 API Key 時才需要傳入。 |
api_key | string | None | 阿里雲百鍊的API Key,建議您配置API Key到環境變數(準備下線,併入配置 API Key)。 |
輸出參數
欄位名 | 欄位類型 | 欄位描述 |
has_more | boolean | 表示是否還有更多資料可以擷取。 |
last_id | string | data中最後一個assistant的ID。 |
first_id | string | data中第一個assistant的ID。 |
data | array | 智能體對象列表。 |
object | string | data的資料格式,如 |
request_id | string | 本次請求的ID。 |
status_code | integer | 請求狀態代碼。 |
檢索智能體
HTTP
程式碼範例
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/assistants/asst_0678aa33-43e2-4268-95e6-b0010f9f7937' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"輸入參數
輸入參數名字 | 輸入參數的描述 | 參數類型 | 是否必須 |
assistant_id | 待檢索的智能體 ID | str | 是 |
返回結果
{
"id": "asst_0678aa33-43e2-4268-95e6-b0010f9f7937",
"object": "assistant",
"created_at": 1711435564909,
"model": "qwen-max",
"name": "智能小助手",
"description": "這是一個智能小助手",
"instructions": "你是一個智能小助手,你可以根據使用者的需求去調用不同的工具,進而給出回答。請酌情使用工具。",
"tools": [
{
"type": "search"
},
{
"type": "text_to_image"
},
{
"type": "code_interpreter"
}
],
"metadata": {},
"request_id": "f0ec05b0-8813-984c-81b5-1166ae3478d1"
}輸出參數
輸出檢索到的智能體對象。
SDK
程式碼範例
from dashscope import Assistants
import dashscope
import os
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'from dashscope import Assistants
assistant = Assistants.retrieve(
assistant_id='your_assistant_id',
# 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY")
)
print(assistant)
import com.alibaba.dashscope.assistants.Assistant;
import com.alibaba.dashscope.assistants.Assistants;
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.utils.Constants;
public class Main {
static {
Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
}
public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
Assistants assistants = new Assistants();
// 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
String apiKey = System.getenv("DASHSCOPE_API_KEY");
Assistant assistant = assistants.retrieve("assistant_id", apiKey);
}
}
輸入參數
參數 | 類型 | 預設值 | 說明 |
assistant_id | string | - | 指定要查詢的智能體 ID |
workspace | string | None | 阿里雲百鍊的Workspace ID,僅當 api_key 為子業務空間 API Key 時才需要傳入。 |
api_key | string | None | 阿里雲百鍊的API Key,建議您配置API Key到環境變數(準備下線,併入配置 API Key)。 |
輸出參數
請參考智能體對象。
更新智能體
HTTP
程式碼範例
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/assistants/asst_0678aa33-43e2-4268-95e6-b0010f9f7937' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
"instructions": "You are a search assistant",
"name": "New Application-assistantAPI",
"description": "",
"model": "qwen-max"
}'輸入參數
輸入參數名字 | 輸入參數的描述 | 參數類型 | 是否必須 |
assistant_id | 待檢索的智能體 ID | str | 是 |
* | 其他可選的輸入參數 | str | 否 |
model | 智能體所使用的大模型 ID | str | 是 |
name | 智能體使用的名字 | str | 否 |
description | 用於描述智能體的文字 | str | 否 |
instructions | System prompt 用於智能體裡的大模型 | str | 否 |
tools | 一個可以被智能體調用tools list,使用者需要在阿里雲百鍊中被註冊 | Optional[List[Dict]] | 否(default=[]) |
metadata | 其他相關參數用於智能體,用於儲存其他相關參數 | Dict | 否 |
返回結果
{
"id": "asst_0678aa33-43e2-4268-95e6-b0010f9f7937",
"object": "assistant",
"created_at": 1711435564909,
"model": "qwen-max",
"name": "建立應用-assistantAPI",
"description": "",
"instructions": "你是一個搜尋助手",
"tools": [
{
"type": "search"
},
{
"type": "text_to_image"
},
{
"type": "code_interpreter"
}
],
"metadata": {},
"request_id": "b0993831-a98b-9e71-b235-75174df9046e"
}輸出參數
輸出更新後的智能體對象。
SDK
程式碼範例
from dashscope import Assistants
import dashscope
import os
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'from dashscope import Assistants
assistants = Assistants.update(
'assistant_id',
model='new_model_name',
# 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY")
)
import com.alibaba.dashscope.assistants.Assistant;
import com.alibaba.dashscope.assistants.AssistantParam;
import com.alibaba.dashscope.assistants.Assistants;
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.utils.Constants;
public class Main {
static {
Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
}
public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
Assistants assistants = new Assistants();
AssistantParam param = AssistantParam.builder()
.model("qwen-max")
.name("intelligent guide")
.description("a smart guide")
.instructions("You are a helpful assistant. When asked a question, use tools wherever possible.")
// 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.build();
Assistant assistant = assistants.update("assistant_id", param);
}
}輸入參數
參數 | 類型 | 預設值 | 說明 |
assistant_id | string | - | 指定需要更新的assistant ID |
model | string | - | 指定用於智能體所使用的模型 |
name | string | None | 指定智能體名稱 |
description | string | None | 智能體描述 |
instructions | string | None | 指定智能體功能資訊。 |
tools | array | [] | 智能體使用的tools |
metadata | object | None | 智能體關聯資訊 |
workspace | string | None | 阿里雲百鍊的Workspace ID,僅當 api_key 為子業務空間 API Key 時才需要傳入。 |
api_key | string | None | 阿里雲百鍊的API Key,建議您配置API Key到環境變數(準備下線,併入配置 API Key)。 |
輸出參數
請參考智能體對象。
刪除智能體
HTTP
程式碼範例
curl --location --request DELETE 'https://dashscope-intl.aliyuncs.com/api/v1/assistants/asst_0678aa33-43e2-4268-95e6-b0010f9f7937' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"輸入參數
輸入參數名字 | 輸入參數的描述 | 參數類型 | 是否必須 |
assistant_id | 待檢索的智能體 ID | str | 是 |
返回結果
{
"id": "asst_0678aa33-43e2-4268-95e6-b0010f9f7937",
"object": "assistant.deleted",
"deleted": true,
"request_id": "6af9320f-0430-9d01-b92f-d1beb6424dc5"
}輸出參數
輸出刪除智能體後的狀態。
SDK
程式碼範例
from dashscope import Assistants
import dashscope
import os
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
assistants = Assistants.delete(
'assistant_id',
# 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY")
)import com.alibaba.dashscope.assistants.Assistants;
import com.alibaba.dashscope.common.DeletionStatus;
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.utils.Constants;
public class Main {
static {
Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
}
public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
Assistants assistants = new Assistants();
// 建議您優先配置環境變數。若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
String apiKey = System.getenv("DASHSCOPE_API_KEY");
DeletionStatus assistant = assistants.delete("assistant_id", apiKey);
}
}輸入參數
參數 | 類型 | 預設值 | 說明 |
assistant_id | string | - | 指定要刪除的智能體 ID |
workspace | string | None | 阿里雲百鍊的Workspace ID,僅當 api_key 為子業務空間 API Key 時才需要傳入。 |
api_key | string | None | 阿里雲百鍊的API Key,建議您配置API Key到環境變數(準備下線,併入配置 API Key)。 |
輸出參數
欄位名 | 欄位類型 | 欄位描述 |
id | string | 刪除的對象的ID |
object | string | 本次請求目標,樣本: |
deleted | boolean | 是否刪除 |
request_id | string | 本次請求的ID。 |
status_code | integer | 請求狀態代碼。 |
智能體對象
一個能夠調用模型並使用工具的Assistant對象。
智能體對象樣本
{
"id": "asst_49079f4b-d1e8-4015-a12e-2dcdd1f18d84",
"object": "assistant",
"created_at": 1711713885724,
"model": "qwen-max",
"name": "智能小助手",
"description": "這是一個智能小助手",
"instructions": "你是一個智能小助手,你可以根據使用者的需求去調用不同的工具,進而給出回答。請酌情使用工具。",
"tools": [
{
"type": "code_interpreter"
}
],
"metadata": {},
"temperature": null,
"top_p": null,
"top_k": null,
"max_tokens": null,
"request_id": "b1778226-3865-9006-9e95-56329a710322"
}參數名 | 資料類型 | 描述 |
id | string | 智能體唯一識別碼,即 assistant ID。 |
object | string | 物件類型,始終為 |
created_at | integer | 建立智能體時的 Unix 13位時間戳記(以毫秒為單位)。 |
model | string | 智能體使用的模型名。您可以在Assistant API功能概覽查看所有可用模型,或者查看模型列表以瞭解它們的詳情。 |
name | string | 智能體的名稱。 |
description | string | 智能體的描述。 |
instructions | string | 智能體使用的系統指令。 |
tools | array | 智能體上啟用的工具列表。工具的類型可以是官方外掛程式(code_interpreter 代碼解譯器、quark_search 夸克搜尋、text_to_image 文生圖)、知識檢索增強(RAG)或函數調用(Function Calling)。 |
metadata | dict | 以結構化格式儲存的智能體對象的附加資訊。 |
temperature | float | 採樣溫度,其取值在 0 到 2 之間。較高的值(如 1)會使輸出更加隨機;而較低的值(如 0.2)則會使輸出更加集中和確定。 |
top_p | float | 一種替代溫度採樣的方法,稱為核採樣。在這種採樣方法中,大模型選取具有前 top_p 的累積機率品質的Token結果。其值為 0.1 表示僅考慮構成前 10% 機率品質的Token。 通常建議調整此參數或 |
top_k | integer | 與top_p類似,但樣本是從 k 個最高機率的Token中選取的,而不考慮它們的累積機率品質。 不要同時調整此參數和 |
max_tokens | integer | 智能體能夠一次性產生Token的最大數量。 |
request_id | string | 智能體關聯的調用的唯一識別碼。 |
錯誤碼
如果模型調用失敗並返回報錯資訊,請參見錯誤資訊進行解決。