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

OpenAI Batch接口兼容

更新时间：
产品详情
我的收藏

为支持熟悉OpenAI的开发者使用OpenAI接口来访问DashScope中与Batch相关的API服务，DashScope提供了与OpenAI兼容的接口。用户通过一个文件发送任务，任务将会被异步调度执行，在任务成功运行结束之前，你可以通过API进行任务状态查询，当任务结束后，可以通过API获取结果。

前提条件

  • 请开通灵积服务并获得API-KEY：API-KEY的获取与配置。

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

    pip3 install -U openai

  • 我们推荐您将API-KEY配置到环境变量中以降低API-KEY的泄露风险，配置方法可参考通过环境变量配置API-KEY。

支持的模型列表

OpenAI兼容Batch接口支持的通义千问系列模型如下表所示。

模型分类

模型名称

通义千问

qwen-turbo

qwen-plus

qwen-max

创建Batch任务

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

Python

请求示例

from openai import OpenAI
import os

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

是

上传文件的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

请求示例

from openai import OpenAI
import os

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

请求示例

from openai import OpenAI
import os

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

请求示例

from openai import OpenAI
import os

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

否

错误信息

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