AI 助理
备案控制台
文档
产品文档
输入文档关键字查找
首页 大模型服务平台百炼 开发参考 OpenAI接口兼容 Batch

OpenAI Batch接口兼容

更新时间：
一键部署
产品详情
我的收藏

为支持熟悉OpenAI的开发者使用OpenAI接口来访问阿里云百炼中与Batch相关的API服务，阿里云百炼提供了与OpenAI兼容的接口。您通过一个文件发送任务，任务将会被异步执行，在24小时内返回结果。在任务运行结束前，您可以通过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 $OPENAI_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 <YOUR-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 <YOUR-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 <YOUR-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请求任务。

上一篇：File下一篇：Embedding
文档推荐