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网络和交换机配置信息是否正确。检查网络安全组配置是否正确。
更多参数配置请参考:事件目标参数