文档

OpenAI Batch接口兼容

更新时间:

阿里云百炼提供了与OpenAI兼容的Batch接口。您可以通过文件方式提交批量任务,任务将异步执行,在24小时内返回结果,费用为实时调用的50%。在任务运行结束前,您可以通过API进行任务状态查询,当任务结束后,可以通过API获取结果。

前提条件

  • 请开通阿里云百炼服务并获得API-KEY:获取API Key

  • 如果您通过OpenAI Python SDK使用,请通过以下命令安装最新版OpenAI SDK。

    pip3 install -U openai
  • 我们推荐您将API-KEY配置到环境变量中以降低API-KEY的泄露风险,配置方法可参考配置API Key到环境变量

支持的模型

  • qwen-turbo

  • qwen-plus

  • qwen-max

计费

Batch调用的费用为实时调用的50%,具体请参见模型列表

创建Batch任务

创建Batch任务前需要准备输入文件,通过上传文件上传后获取file_id(文件的purpose属性需要为batch),输入文件格式参考本文档后续章节。单个Batch任务最多包含50k个请求,Batch文件的大小最大100 MB

Python

请求示例

import os
from openai import OpenAI


client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您没有配置环境变量,请在此处用您的API Key进行替换
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # 填写DashScope服务的base_url
)

batch = client.batches.create(
    input_file_id="file-abc123",
    endpoint="/v1/chat/completions",
    completion_window="24h"
)
print(batch)

输入参数配置

字段

类型

传参方式

必选

描述

input_file_id

String

Body

上传文件的id,以file-batch开头

文件的purpose属性需要为batch

endpoint

string

Body

访问路径

completion_window

String

Body

超时时间,当前只支持24h

metadata

Map

Body

附加信息,键值对

返回示例

{
  "id": "batch_cf957e2b-3295-4357-83af-5fb22ac17e81",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-batch-ADvrUmLWW8TFuKNjGDUUig1c",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1722503223,
  "in_progress_at": null,
  "expires_at": null,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": {}
}

返回参数

字段

类型

描述

id

String

batch任务id

object

String

对象类型,固定值batch

endpoint

String

访问路径

errors

Map

错误信息

input_file_id

String

上传的文件id

completion_window

String

超时时间,当前只支持24h

status

String

任务状态:validating, in_progress, finalizing, completed, expired, cancelling, cancelled, failed

output_file_id

String

执行成功请求的输出文件id

error_file_id

String

执行错误请求的输出文件id

created_at

Integer

任务创建的Unix 时间戳(秒)

in_progress_at

Integer

任务开始运行的Unix时间戳(秒)

expires_at

Integer

任务开始超时的时间戳(秒)

finalizing_at

Integer

任务最后开始时间戳(秒)

completed_at

Integer

任务完成的时间戳(秒)

failed_at

Integer

任务失败的时间戳(秒)

expired_at

Integer

任务超时的时间戳(秒)

cancelling_at

Integer

任务设置为取消中的时间戳(秒)

cancelled_at

Integer

任务取消的时间戳(秒)

request_counts

Map

不同状态的请求数量

metadata

Map

附加信息,键值对

HTTP

需要配置的endpoint

POST https://dashscope.aliyuncs.com/compatible-mode/v1/files

请求示例

curl https://dashscope.aliyuncs.com/compatible-mode/v1/batches \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

输入参数配置

字段

类型

传参方式

必选

描述

input_file_id

String

Body

上传文件的file_id,以file-batch开头

文件的purpose属性为batch

endpoint

string

Body

访问路径

completion_window

String

Body

超时时间,当前只支持24h

metadata

Map

Body

附加信息,键值对

返回示例

{
  "id": "batch_cf957e2b-3295-4357-83af-5fb22ac17e81",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-batch-ADvrUmLWW8TFuKNjGDUUig1c",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1722503223,
  "in_progress_at": null,
  "expires_at": null,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": {}
}

返回参数

字段

类型

描述

id

String

batch任务id

object

String

对象类型,固定值batch

endpoint

String

访问路径

errors

Map

错误信息

input_file_id

String

上传的文件id

completion_window

String

超时时间,当前只支持24h

status

String

任务状态:validating, in_progress, finalizing, completed, expired, cancelling, cancelled, failed

output_file_id

String

执行成功请求的输出文件id

error_file_id

String

执行错误请求的输出文件id

created_at

Integer

任务创建的Unix 时间戳(秒)

in_progress_at

Integer

任务开始运行的Unix时间戳(秒)

expires_at

Integer

任务开始超时的时间戳(秒)

finalizing_at

Integer

任务最后开始时间戳(秒)

completed_at

Integer

任务完成的时间戳(秒)

failed_at

Integer

任务失败的时间戳(秒)

expired_at

Integer

任务超时的时间戳(秒)

cancelling_at

Integer

任务设置为取消中的时间戳(秒)

cancelled_at

Integer

任务取消的时间戳(秒)

request_counts

Map

不同状态的请求数量

metadata

Map

附加信息,键值对

查询Batch任务

Python

请求示例

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您没有配置环境变量,请在此处用您的API Key进行替换
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # 填写DashScope服务的base_url
)
batch = client.batches.retrieve("batch_abc123")
print(batch)

输入参数配置

字段

类型

传参方式

必选

描述

batch_id

String

Path

需要查询的batch任务id

返回示例

参见创建Batch任务返回示例。

返回参数

参见创建Batch任务返回示例。

返回参数中output_file_id和error_file_id可以通过下载文件获取内容。

HTTP

需要配置的endpoint

GET https://dashscope.aliyuncs.com/compatible-mode/v1/batches/{batch_id}

请求示例

curl --request GET 'https://dashscope.aliyuncs.com/compatible-mode/v1/batches/batch_xxx' \
 -H "Authorization: Bearer $DASHSCOPE_API_KEY"

输入参数配置

字段

类型

传参方式

必选

描述

batch_id

String

Path

需要查询的batch任务id

返回示例

参见创建Batch任务返回示例

返回参数

参见创建Batch任务返回示例

取消Batch任务

Python

请求示例

import os
from openai import OpenAI


client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您没有配置环境变量,请在此处用您的API Key进行替换
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # 填写DashScope服务的base_url
)
batch = client.batches.cancel("batch_abc123")
print(batch)

输入参数配置

字段

类型

传参方式

必选

描述

batch_id

String

Path

需要取消的batch任务id

返回示例

参见创建Batch任务返回示例。

返回参数

参见创建Batch任务返回示例。

HTTP

需要配置的endpoint

POST https://dashscope.aliyuncs.com/compatible-mode/v1/batches/{batch_id}/cancel

请求示例

curl --request POST 'https://dashscope.aliyuncs.com/compatible-mode/v1/batches/batch_xxx/cancel' \
 -H "Authorization: Bearer $DASHSCOPE_API_KEY"

输入参数配置

字段

类型

传参方式

必选

描述

batch_id

String

Path

需要取消的batch任务id

返回示例

参见创建Batch任务返回示例

返回参数

参见创建Batch任务返回示例

查询Batch任务列表

Python

请求示例

import os
from openai import OpenAI


client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您没有配置环境变量,请在此处用您的API Key进行替换
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # 填写DashScope服务的base_url
)
batches = client.batches.list()
print(batches)

输入参数配置

字段

类型

传参方式

必选

描述

after

String

Query

查询此batch id之前的任务,翻页查询时把返回结果中的last_id设置到此参数中

limit

Integer

Query

返回数量,范围[1,100],默认20

返回示例

{
  "object": "list",
  "data": [
    {
      "id": "batch_b8b6a83e-00a3-4068-81d9-0a1705bf6b2c",
      "object": "batch",
      "endpoint": "/v1/chat/completions",
      "errors": null,
      "input_file_id": "file-batch-IvxTEDheD70YmyXfqrkE2t64",
      "completion_window": "24h",
      "status": "completed",
      "output_file_id": "file-batch_output-fUy6gxJCyHzT0WHDg2SInyTp",
      "error_file_id": null,
      "created_at": 1722234109,
      "in_progress_at": 1722234109,
      "expires_at": null,
      "finalizing_at": 1722234165,
      "completed_at": 1722234165,
      "failed_at": null,
      "expired_at": null,
      "cancelling_at": null,
      "cancelled_at": null,
      "request_counts": {
        "total": 100,
        "completed": 95,
        "failed": 5
      },
      "metadata": {}
    },
    { ... }
  ],
  "first_id": "batch_b8b6a83e-00a3-4068-81d9-0a1705bf6b2c",
  "last_id": "batch_ca912d83-e9e8-4cf2-89a4-d29743e334e4",
  "has_more": true
}

返回参数

字段

类型

描述

object

String

类型,固定值list

data

Array

batch任务对象,参见创建batch任务出参

first_id

String

当前页第一个id

last_id

String

当前页最后一个id

has_more

Boolean

是否有下一页

HTTP

需要配置的endpoint

GET https://dashscope.aliyuncs.com/compatible-mode/v1/batches?limit=2&after={batch_id}

请求示例

curl --request GET  'https://dashscope.aliyuncs.com/compatible-mode/v1/batches?limit=2&after=batch_xxx' \
 -H "Authorization: Bearer $DASHSCOPE_API_KEY"

输入参数配置

字段

类型

传参方式

必选

描述

after

String

Query

查询此batch id之前的任务,翻页查询时把返回结果中的last_id设置到此参数中

limit

Integer

Query

返回数量,范围[1,100],默认20

返回示例

{
  "object": "list",
  "data": [
    {
      "id": "batch_b8b6a83e-00a3-4068-81d9-0a1705bf6b2c",
      "object": "batch",
      "endpoint": "/v1/chat/completions",
      "errors": null,
      "input_file_id": "file-batch-IvxTEDheD70YmyXfqrkE2t64",
      "completion_window": "24h",
      "status": "completed",
      "output_file_id": "file-batch_output-fUy6gxJCyHzT0WHDg2SInyTp",
      "error_file_id": null,
      "created_at": 1722234109,
      "in_progress_at": 1722234109,
      "expires_at": null,
      "finalizing_at": 1722234165,
      "completed_at": 1722234165,
      "failed_at": null,
      "expired_at": null,
      "cancelling_at": null,
      "cancelled_at": null,
      "request_counts": {
        "total": 100,
        "completed": 95,
        "failed": 5
      },
      "metadata": {}
    },
    { ... }
  ],
  "first_id": "batch_b8b6a83e-00a3-4068-81d9-0a1705bf6b2c",
  "last_id": "batch_ca912d83-e9e8-4cf2-89a4-d29743e334e4",
  "has_more": true
}

返回参数

字段

类型

描述

object

String

类型,固定值list

data

Array

batch任务对象,参见创建batch任务出参

first_id

String

当前页第一个id

last_id

String

当前页最后一个id

has_more

Boolean

是否有下一页

输入文件格式

JSONL文件,每一行一个JSON。

示例

{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "qwen-turbo", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is 2+2?"}]}}

参数

字段

类型

必选

描述

custom_id

String

用户自定义的请求id,文件中唯一

method

String

请求方法,当前只支持POST

url

String

API关联的URL,当前支持:/v1/chat/completions

body

Object

模型调用的请求体

输出文件格式

JSONL文件,每一行一个JSON。

示例

{"id": "batch_req_wnaDys", "custom_id": "request-2", "response": {"status_code": 200, "request_id": "req_c187b3", "body": {"id": "chatcmpl-9758Iw", "object": "chat.completion", "created": 1711475054, "model": "qwen-max", "choices": [{"index": 0, "message": {"role": "assistant", "content": "2 + 2 equals 4."}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 24, "completion_tokens": 15, "total_tokens": 39}, "system_fingerprint": null}}, "error": null}

参数

字段

类型

必选

描述

id

String

请求id

custom_id

String

用户自定义的请求id

response

Object

请求结果

error

Object

异常响应结果

error.code

String

错误码

error.message

String

错误信息

常见问题

  1. 这几个模块的Batch定价,对应的模型也有基础限流吗?

    答:实时调用才会有QPM(Queries Per Minute:每分钟处理请求数)限流,Batch调用没有 QPM 限流。

  2. 使用Batch调用,是否需要下单,在哪里下单?

    答:Batch是一种调用方式,无需额外下单。该调用方式为后付费计价模式,按照Batch接口调用直接付费。

  3. 提交的Batch调用请求,后台如何处理? 是根据提交请求的先后顺序来执行吗?

    答:不是排队机制,是调度机制,根据资源情况来调度和执行Batch请求任务。

  4. 报错如何处理?

    答:请参见错误码