DashScope提供了一系列的API能力調用,其中部分接口因為相關能力需要比較長的處理時間或者一些其他的限制,采用了異步任務接口,即用戶調用對應的能力API將會提交一個相關的異步任務,接口將立刻返回并告知客戶任務提交的結果,如果提交成功,返回內容中將包含任務的序列號(task_id);隨后客戶可以通過任務狀態/結果查詢任務的情況,相關的接口詳細描述在對應的API詳情文檔中有詳細說明。DashScope針對這一類的異步任務,提供了一系列通用的異步任務管理接口方便客戶管控自己提交的異步任務,客戶可以使用對應的API在需要的時候直接查詢和管理隊列中的異步任務。同時,除了提供DashScope的平臺接口,異步任務模塊還接入了阿里云事件總線(EventBridge),用戶可以更加靈活地以消息等其他方式接收任務狀態的更新信息。
需要注意的是,DashScope的異步任務是賬號維度的,同樣的阿里云UID用戶可以查詢和管理該賬號下所有的異步任務:比如列出異步任務接口會列出該賬號在DashScope上所有的異步任務,包括所有模型和所有Apikey提交的任務。當然,接口也提供了相應的過濾選項,用戶可以根據自己的需求定制查詢。
異步任務管理接口
1. 異步任務查詢接口(結果獲取接口)
API描述
異步任務查詢接口是一個全局的調用接口,用戶在調用時候指定 task_id 即可獲取到任務的運行狀態,同時在任務結束(成功或者失敗)的時候獲取到任務的結果或者相應出錯信息。
重要用戶能查詢Apikey歸屬的阿里云主賬號的所有任務(包括阿里云主賬號下所有Apikey提交的任務),但無法查詢到其他主賬號下的任務。
不同類型的異步任務對于已經結束的任務有不同的保留時間(通常來說這個時間為 24 小時,具體的請參考特定任務的相關文檔),如果超出這個時間,則任務會被從系統中清除。
流量限制
對于普通客戶,異步任務查詢接口提供 20 QPS 的訪問流量限制,即每秒鐘每個賬號可以發起不超過20次的任務查詢API調用,如果有超出基礎限流的調用需求,可發送電子郵件至 dashscope@alibabacloud.com 額外申請。
HTTP方法
GET
URL
https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
請求參數
參數類型
參數
類型
必選
描述
示例值
Header
Authorization
String
是
API-Key,例如:Bearer d1**2a
Bearer d1**2a
Path
task_id
String
是
需要查詢任務的 task_id
a8532587-xxxx-xxxx-xxxx-0c46b17950d1
返回參數
參數
類型
描述
示例值
request_id
String
本次請求的系統唯一碼
7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51
output
Object
如果任務成功,包含模型生成的結果 object,根據實際任務的不同,output 可能包含有不同的內容;
如果任務失敗或者部分失敗,在 output 中根據不同的任務也會輸出響應的 code 和 message 信息指明失敗的原因,對于有的任務包含多個子任務,有可能會分別有多個成功和失敗的任務。
-
output.task_id
String
查詢任務的 task_id
a8532587-xxxx-xxxx-xxxx-0c46b17950d1
output.task_status
String
被查詢任務的任務狀態;
對于包含多個子任務的任務,只要有一個對應的任務成功任務即被標記為成功,對應失敗的子任務會在 output 部分根據不同的情況有詳細說明。
任務狀態:
PENDING 排隊中
RUNNING 處理中
SUCCEEDED 成功
FAILED 失敗
UNKNOWN 任務不存在或狀態未知
output.submit_time
String
任務提交時間
2023-12-20 21:36:31.896
output.scheduled_time
String
任務調度時間(開始運行時間)
2023-12-20 21:36:39.009
output.end_time
String
任務結束時間
2023-12-20 21:36:45.913
output.code
String
錯誤碼,任務失敗時返回
-
output.message
String
錯誤信息,任務失敗是返回
-
output.task_metrics
Object
任務指標,包含子任務狀態的統計信息。
{
"TOTAL": 4, //子任務總數
"SUCCEEDED": 3, //子任務成功數
"FAILED": 1 //子任務失敗數
}
usage
Object
本次請求產生的計量信息,根據實際任務的不同,相關的計量信息可能也有所不同。
"usage": {"image_count": 1}
請求示例
curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/73205176-xxxx-xxxx-xxxx-16bd5d902219' \ --header 'Authorization: Bearer <YOUR_API_KEY>'
響應示例
{ "request_id": "45ac7f13-xxxx-xxxx-xxxx-e03c35068d83", "output": { "task_id": "73205176-xxxx-xxxx-xxxx-16bd5d902219", "task_status": "SUCCEEDED", "submit_time": "2023-12-20 21:36:31.896", "scheduled_time": "2023-12-20 21:36:39.009", "end_time": "2023-12-20 21:36:45.913", "results": [ { "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx1.png" }, { "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx2.png" }, { "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx3.png" }, { "code": "DataInspectionFailed", "message": "Output data may contain inappropriate content.", } ], "task_metrics": { "TOTAL": 4, "SUCCEEDED": 3, "FAILED": 1 } }, "usage": { "image_count": 3 } }
2. 異步任務取消接口
API描述
異步任務取消接口用于用戶取消不再需要的任務。
重要異步任務取消接口只能操作非運行狀態和非結束狀態的接口,如果任務一旦開始運行或者已經完成,則無法再行取消;
取消接口能操作Apikey歸屬的阿里云主賬號的所有任務(包括阿里云主賬號下所有Apikey提交的任務),但無法操作到其他主賬號下的任務。
流量限制
對于普通客戶,異步任務取消接口提供 20 QPS 的訪問流量限制,即每秒鐘每個賬號可以發起不超過20次的任務取消API調用,如果有超出基礎限流的調用需求,可發送電子郵件至 dashscope@alibabacloud.com 額外申請。
HTTP方法
POST
URL
https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}/cancel
請求參數
參數類型
參數
類型
必選
描述
示例值
Header
Authorization
String
是
API-Key,例如:Bearer d1**2a
Bearer d1**2a
Path
task_id
String
是
需要查詢任務的 task_id
a8532587-xxxx-xxxx-xxxx-0c46b17950d1
返回參數
參數
類型
描述
示例值
request_id
String
本次請求的系統唯一碼
7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51
code
String
調用失敗的時候返回的錯誤碼
"code": "Throttling.RateQuota"
message
String
調用失敗的時候返回的錯誤信息
"message": "Requests rate limit exceeded, please try again later."
請求示例
curl -X POST 'https://dashscope.aliyuncs.com/api/v1/tasks/73205176-xxxx-xxxx-xxxx-16bd5d902219/cancel' \ --header 'Authorization: Bearer <YOUR_API_KEY>'
響應示例
{ "request_id": "45ac7f13-xxxx-xxxx-xxxx-e03c35068d83" }
3. 異步任務列表查詢接口
API描述
查詢用戶提交的所有異步任務,該接口提供多種查詢條件,用戶可以通過相關條件的組合獲取到自己的任務列表。異步任務列表查詢接口和結果查詢接口的限制條件一樣,用戶只能查詢屬于自己主賬號的任務并且已經結束的任務在達到超時限制之后會被系統清除則無法再被列出。
流量限制
對于普通客戶,異步任務列表查詢接口提供 20 QPS 的訪問流量限制,即每秒鐘每個賬號可以發起不超過20次的任務列表查詢API調用,如果有超出基礎限流的調用需求,可發送電子郵件至 dashscope@alibabacloud.com 額外申請。
HTTP方法
GET
URL
https://dashscope.aliyuncs.com/api/v1/tasks/?
請求參數
參數類型
參數
類型
必選
描述
示例值
Header
Authorization
String
是
API-Key,例如:Bearer d1**2a
Bearer d1**2a
Params
task_id
String
否
需要查詢任務的 task_id
a8532587-xxxx-xxxx-xxxx-0c46b17950d1
start_time
String
否
任務開始時間,格式為:YYYYMMDDhhmmss
若未指定開始時間(start_time為空),系統將查詢指定結束時間(end_time)前24小時的數據。
若未指定結束時間(end_time為空),系統將查詢指定開始時間(start_time)后24小時的數據。
若開始和結束時間均未指定(均為空),系統默認查詢最近24小時的數據。
請確保您設定的開始和結束時間的差距不超過24小時。
20230420193058 代表 2023 年 4 月 20 日 19 點 30 分 58 秒
end_time
String
否
任務結束時間,格式為:
YYYYMMDDhhmmss
model_name
String
否
模型名稱
wanx-v1
status
String
否
任務狀態:
PENDING:任務排隊中
RUNNING:任務處理中
SUCCEEDED:處理成功
FAILED:處理失敗
CANCELED:任務取消
page_no
Integer
否
當前頁,默認查詢第1頁
-
page_size
Integer
否
每頁查詢條數,默認查詢10條
-
返回參數
參數
類型
描述
示例值
request_id
String
本次請求的系統唯一碼
7574ee8f-xxxx-xxxx-xxxx-11c33ab46e51
data
Array
查詢結果列表
"data": [ { "api_key_id": "235", "caller_uid": "1808342417264262", "end_time": 1682527200093, "gmt_create": 1682514589152, "model_name": "paraformer-16k-1", "region": "cn-hangzhou", "request_id": "32b67b58-xxxx-xxxx-xxxx-230f0aee64d9", "start_time": 1682515862179, "status": "FAILED", "task_id": "cf52b16b-xxxx-xxxx-xxxx-17f9c211440c", "user_api_unique_key": "apikey:v1:audio:asr:transcription:paraformer-16k-1" } ]
data[].api_key_id
String
Apikey的id
data[].caller_uid
String
阿里云賬號
data[].gmt_create
Long
任務創建時間,Date時間毫秒數
data[].start_time
Long
任務開始時間,Date時間毫秒數
data[].end_time
Long
任務結束時間,Date時間毫秒數
data[].region
String
地域,例如:cn-hangzhou
data[].request_id
String
提交任務的請求id
data[].status
String
任務狀態:
PENDING:任務排隊中
RUNNING:任務處理中
SUCCEEDED:處理成功
FAILED:處理失敗
CANCELED:任務取消
data[].task_id
String
任務id
data[].user_api_unique_key
String
API 的唯一key(提交任務時,模型api的各要素唯一索引)
data[].model_name
String
模型名稱
page_no
Integer
當前頁
"page_no": 1
page_size
Integer
每頁查詢條數
"page_size": 10
total_page
Integer
總頁數
"total_page": 4
total
Integer
總條數
"total": 39
code
String
調用失敗的時候返回的錯誤碼
"code": "Throttling.RateQuota"
message
String
調用失敗的時候返回的錯誤信息
"message": "Requests rate limit exceeded, please try again later."
請求示例
curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/?start_time=xxx&end_time=xxx&api_key_id=xxx®ion=xxx&task_id=xxx&status=xxx' \ --header 'Authorization: Bearer <YOUR_API_KEY>'
響應示例
{ "request_id": "eeaf6e5e-xxxx-xxxx-xxxx-7b7c2d399c3f", "data": [ { "api_key_id": "123", "gmt_create": 1682514589152, "gmt_create": 1682514589152, "caller_uid": "xxxxxxxxx", "start_time": 1682515862179, "end_time": 1682527200093, "model_name": "paraformer-16k-1", "region": "cn-hangzhou", "request_id": "32b67b58-xxxx-xxxx-xxxx-230f0aee64d9", "status": "FAILED", "task_id": "cf52b16b-xxxx-xxxx-xxxx-17f9c211440c", "user_api_unique_key": "apikey:v1:audio:asr:transcription:paraformer-16k-1" } ], "total_page": 4, "total": 39, "page_no": 1, "page_size": 10 }
異步任務外部拓展
為了滿足客戶的多元化需求,DashScope異步任務系統還接入了阿里云事件總線——EventBridge。
當異步任務完成后,DashScope異步任務系統會將相應的消息發送給EventBridge,用戶可以在EventBridge控制臺配置自己的事件消息處理機制,比如指定的http回調url、投遞到指定的MQ隊列,以便更加高效處理已完成的DashScope異步任務。
1. EventBridge配置事件轉發
EventBridge的幾個核心概念:
事件:事件狀態變化的數據記錄。
事件源:事件的來源,負責生產事件。
事件目標:事件的處理終端,負責消費事件。
事件總線:事件的中轉站,負責事件的中間轉儲。
事件規則:用于監控特定類型的事件。當發生匹配事件時,事件會被路由到與事件規則關聯的事件目標。
關于詳細信息,請參見EventBridge幫助文檔。關于云控制臺,請登錄EventBridge控制臺。
EventBridge中配置事件接收的準備工作:
查詢DashScope異步任務事件
DashScope異步任務結束后,在EventBridge中可以查詢DashScope投遞的任務結束事件。
登錄阿里云主賬號,然后進入EventBridge控制臺,切換到北京地域,選擇左側事件總線導航,點擊default進入云服務專用總線。
DashScope所屬的事件總線為云服務專用總線——即default。
點擊事件追蹤,輸入查詢條件,查詢DashScope任務結束事件。
事件源:
acs.dashscope
事件類型:
dashscope:System:AsyncTaskFinish
點擊事件詳情,可以查看到DashScope任務結束的詳細信息:
{ "datacontenttype": "application/json;charset=utf-8", "aliyunaccountid": "xxxxx", "aliyunpublishtime": "2023-10-25T01:45:16.993Z", "data": { "start_time": "2023-10-25 09:45:09", "user_api_unique_key": "apikey:v1:audio:asr:transcription:paraformer-8k-v1", "task_status": "SUCCEEDED", "end_time": "2023-10-25 09:45:16", "task_id": "a154c328-xxxx-xxxx-xxxx-e52a9a7e9a35", "region": "cn-beijing", "request_id": "108f38f5-xxxx-xxxx-xxxx-6504db9080b3", "api_key_id": "1250" }, "aliyunoriginalaccountid": "xxxxxxxx", "specversion": "1.0", "aliyuneventbusname": "default", "id": "81765e5b-xxxx-xxxx-xxxx-bbad8dde2bd9", "source": "acs.dashscope", "time": "2023-1-25T01:45:16.969Z", "aliyunregionid": "cn-beijing", "type": "dashscope:System:AsyncTaskFinish" }
參數描述
參數 | 類型 | 描述 | 示例值 |
datacontenttype | String | 參數data的內容形式。datacontenttype只支持application/json格式。 |
|
aliyunaccountid | String | 阿里云賬號ID。 | 123456789098**** |
aliyunpublishtime | String | 接收事件的時間。 | 2020-11-19T21:04:42.179PRC |
data | Object | 事件內容。JSON對象,內容由發起事件的服務決定。CloudEvents可能包含事件發生時由事件生產者給定的上下文,data中封裝了這些信息。 | |
data[].start_time | String | 異步任務開始時間, 格式:yyyy-MM-dd HH:mm:ss | 2023-10-25 09:45:09 |
data[].end_time | String | 異步任務結束時間 格式:yyyy-MM-dd HH:mm:ss | 2023-10-25 09:45:16 |
data[].user_api_unique_key | String | API 的唯一key(提交任務時,模型api的五要素),組成格式為: apikey:version:group:task:function-call:model version:版本 group:分組 task:任務名稱 function-call:方法名稱 model:模型名稱 |
|
data[].task_status | String | 任務狀態 PENDING:任務排隊中 RUNNING:任務處理中 SUCCEEDED:處理成功 FAILED:處理失敗 CANCELED:任務取消 | SUCCEEDED |
data[].task_id | String | 任務ID | a154c328-xxxx-xxxx-xxxx-e52a9a7e9a35 |
data[].region | String | 任務所在地域 | cn-beijing |
data[].request_id | String | 請求ID | 108f38f5-xxxx-xxxx-xxxx-6504db9080b3 |
data[].api_key_id | String | Apikey ID | 1234 |
aliyunoriginalaccountid | String | 阿里云原始賬號ID | 123456789098**** |
specversion | String | CloudEvents協議版本 | 1.0 |
aliyuneventbusname | String | 接收事件的事件總線名稱 | default |
id | String | 事件ID,標識事件的唯一值。 | 45ef4dewdwe1-7c35-447a-bd93-fab**** |
source | String | 事件源。提供事件的服務。標識事件發生的內容。一般會包含事件源的類型,發布事件的機制或生產事件的過程。發送端必須確保每個事件的source+id是唯一的。 | acs.dashscope |
time | String | 事件產生的時間。如果無法確定事件發生的時間,CloudEvents生產者可以把time設置為其他時間(例如當前時間),但是同一個source的所有生產者設置的值必須是一致的。 | 2020-11-19T21:04:41+08:00 |
aliyunregionid | String | 接收事件的地域。 | cn-beijing |
type | String | 事件類型。描述事件源相關的事件類型。該參數用于路由、事件查詢和策略執行等。格式由生產者定義且包含版本等信息。 | dashscope:System:AsyncTaskFinish |
創建轉發規則
這里可以自定義規則,將DashScope任務轉發到不同的接收點。
規則名稱和描述可以自定義。
配置事件模式
需要選擇DashScope的事件源和DashScope任務結束的事件類型。
事件源:acs.dashscope 代表DashScope云產品。
事件類型:dashscope:System:AsyncTaskFinish 代表DashScope 異步任務結束。
模式內容:用來過濾相關事件的模式定義,可以根據指定字段的值進行過濾,具體模式定義參考事件模式。
例如,只轉發模型名稱為paraformer-8k-v1的事件:
{ "source": ["acs.dashscope"], "type": ["dashscope:System:AsyncTaskFinish"], "data": { "user_api_unique_key": [ {"suffix": ":paraformer-8k-v1"} ] } }
配置事件目標
2. HTTP回調接口
使用http接口的形式接收EventBridge事件,需要提供一個公網或者阿里云專有網絡的http的服務。
打開配置EventBridge的事件目標界面
服務類型:選擇http。
URL:填寫http服務地址。
Body:完整事件。
網絡類型:根據服務地址選擇。
http支持公網和專用網絡兩種類型,當選擇專用網絡時,需要配置VPC、vSwitch和SecurityGroup信息。
如果選擇完整事件,事件總線 EventBridge 將會把全部的事件內容路由到目標。點擊事件內容轉換查看使用示例。
點擊確認即可完成規則的修改,查看事件目標,如果有http樣式,則代表配置成功
3. RocketMQ消息隊列
通過RocketMQ消息隊列接收EventBridge事件,需要先準備好RocketMQ隊列。
進入RocketMQ的管理控制臺,創建RocketMQ的實例(如果已經有RocketMQ隊列,可以跳過此步)
下圖中,rmq-cn-nwy*******為實例ID
創建對應實例的Topic和Group
下圖中,rmq-cn-nwy*******為實例ID
RocketMQ創建完成后,打開配置EventBridge的事件目標界面,選擇已配置的RocketMQ實例
服務類型:消息隊列RocketMQ版。
版本:創建完成的RocketMQ版本。
實例ID:創建完成的RocketMQ的實例ID。
Topic:創建完成的Topic。
配置完成后,提交異步任務,待任務完成后,在配置的RocketMQ的Topic中查看消息
RocketMQ在線查看消息需要開通消息一鍵收發體驗功能。
消息一鍵收發體驗功能是基于函數計算的產品能力實現的,運行 SDK 示例如果超過了計費概述會產生少量費用,點擊計費概述查看函數計算收費規則。
通過RocketMQ的SDK,接收消息。
說明請參見SDK參考
RocketMQ 5.0版本,java客戶端代碼實例如下:
Maven項目中,引入以下依賴:
<dependency> <groupId>org.apache.rocketmq</groupId> <artifactId>rocketmq-client-java</artifactId> <version>5.0.4</version> </dependency>
消費MQ消息代碼:
package com.test; import com.alibaba.fastjson2.JSON; import org.apache.rocketmq.client.apis.*; import org.apache.rocketmq.client.apis.consumer.ConsumeResult; import org.apache.rocketmq.client.apis.consumer.FilterExpression; import org.apache.rocketmq.client.apis.consumer.FilterExpressionType; import org.apache.rocketmq.client.apis.consumer.PushConsumer; import org.apache.rocketmq.shaded.org.slf4j.Logger; import org.apache.rocketmq.shaded.org.slf4j.LoggerFactory; import java.io.IOException; import java.nio.ByteBuffer; import java.util.Collections; /** * @author xxx */ public class ConsumerExample { private static final Logger LOGGER = LoggerFactory.getLogger(ConsumerExample.class); private ConsumerExample() { } public static void main(String[] args) throws ClientException, IOException, InterruptedException { /* 實例接入點,從控制臺實例詳情頁的接入點頁簽中獲取。 如果是在阿里云ECS內網訪問,建議填寫VPC接入點。 如果是在本地公網訪問,或者是線下IDC環境訪問,可以使用公網接入點。使用公網接入點訪問,必須開啟實例的公網訪問功能。 */ String endpoints = "xxxx"; //指定需要訂閱哪個目標Topic,Topic需要提前在控制臺創建,如果不創建直接使用會返回報錯。 String topic = "xxxx"; //為消費者指定所屬的消費者分組,Group需要提前在控制臺創建,如果不創建直接使用會返回報錯。 String consumerGroup = "xxxx"; final ClientServiceProvider provider = ClientServiceProvider.loadService(); ClientConfigurationBuilder builder = ClientConfiguration.newBuilder().setEndpoints(endpoints); /* 如果是使用公網接入點訪問,configuration還需要設置實例的用戶名和密碼。用戶名和密碼在控制臺實例詳情頁獲取。 如果是在阿里云ECS內網訪問,無需填寫該配置,服務端會根據內網VPC信息智能獲取。 */ builder.setCredentialProvider(new StaticSessionCredentialsProvider("xxxx", "xxxx")); ClientConfiguration clientConfiguration = builder.build(); //訂閱消息的過濾規則,表示訂閱所有Tag的消息。 String tag = "*"; FilterExpression filterExpression = new FilterExpression(tag, FilterExpressionType.TAG); //初始化SimpleConsumer,需要綁定消費者分組ConsumerGroup、通信參數以及訂閱關系。 PushConsumer pushConsumer = provider.newPushConsumerBuilder() .setClientConfiguration(clientConfiguration) //設置消費者分組。 .setConsumerGroup(consumerGroup) //設置預綁定的訂閱關系。 .setSubscriptionExpressions(Collections.singletonMap(topic, filterExpression)) //設置消費監聽器。 .setMessageListener(messageView -> { try { //處理消息并返回消費結果。 ByteBuffer buffer = messageView.getBody(); ByteBuffer newBuffer = ByteBuffer.allocate(buffer.capacity()); for (int i = 0; i < buffer.capacity(); i++) { newBuffer.put(buffer.get(i)); } String result = new String(newBuffer.array()); LOGGER.info("Consume message={}", JSON.toJSONString(result)); System.out.println(result); return ConsumeResult.SUCCESS; } catch (Exception e) { LOGGER.error("deal message has error", e); return ConsumeResult.FAILURE; } }) .build(); Thread.sleep(Long.MAX_VALUE); //如果不需要再使用PushConsumer,可關閉該進程。 pushConsumer.close(); } }
4. 常見問題
配置完成了事件規則,但是接收不到事件?
檢查配置的事件轉發規則的地域和事件所屬地域是否一致,比如北京地域配置的事件轉發規則只能轉發北京地域的事件,無法轉發上海地域的事件。
一個事件規則可以配置多個事件目標嗎?
可以,同一個事件規則可以配置多個事件目標。如果配置多個事件目標,則同一個事件會投遞到配置的每個事件目標中。
HTTP/HTTPS服務請求超時或者請求錯誤?
檢查HTTP/HTTPS服務狀態;
檢查事件目標配置的url是否正確;
檢查事件目標配置的Network類型:
PublicNetwork:公網;
PrivateNetwork:VPC網絡,如果選擇此項,需要配置VPC、vSwitch和SecurityGroup信息;
檢查VPC網絡和交換機配置信息是否正確。檢查網絡安全組配置是否正確。
更多參數配置請參考:事件目標參數