# 创建批量推理任务

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`POST https://ark.cn-beijing.volcengineapi.com/?Action=CreateBatchInferenceJob&Version=2024-01-01`

创建批量推理任务。为了避免异常情况下重复提交任务带来额外推理和计费，平台在创建批量推理任务时提供幂等控制：当用户、项目名（Project Name）、存储桶（bucket）和输入文件名（object-key）完全相同时，平台仅保留一个任务处于活跃状态（运行或排队），其他重复提交将报错，并在错误信息中包含在运行或排队中任务的 ID，供用户查询。

> **说明：注意**
>
> 批量推理任务有以下使用约束：
> - 输入文件需为 JSONL 格式，每行一个请求；输出为模型推理结果。
> - 输入与输出存储桶均需位于华北 2-北京地域（`cn-beijing`），且与任务在同一账号下。
> - 同一用户、项目、存储桶和输入文件下，平台仅保留一个活跃任务（运行或排队），重复提交会报错并返回已存在任务的 ID。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* Access Key 鉴权，请在 [Access Key 管理](https://console.volcengine.com/iam/keymanage) 页面，获取 Access Key。本接口仅支持 Access Key 鉴权。

---

<span id="request-parameters"></span>
## 请求参数

### Body 参数

**InputFileTosLocation** `object` `必选` | 输入文件

批量推理输入文件的 TOS 位置。文件需为 JSONL 格式，且存储桶位于 `cn-beijing` 地域。

**BucketName** `string` `必选` | TOS 桶名称

`InputFileTosLocation.BucketName`

TOS 桶名称。当前火山方舟仅支持华北 2-北京地域（`cn-beijing`）的 TOS 桶。

**ObjectKey** `string` `必选` | 对象路径

`InputFileTosLocation.ObjectKey`

TOS 对象路径。输入为 JSONL 文件的完整 object key；输出文件夹路径建议以 `/` 结尾。

**ModelReference** `object` `必选` | 模型引用

批量推理任务选择的模型。*CustomModelId*（定制模型）与 *FoundationModel*（基础模型）二者需且仅需指定其一。

**CustomModelId** `string` | 定制模型 ID

`ModelReference.CustomModelId`

定制模型 ID。与 *FoundationModel* 二选一，仅需指定其一。

**FoundationModel** `object` | 基础模型引用

`ModelReference.FoundationModel`

基础模型引用对象。与 *CustomModelId* 二选一，仅需指定其一。

**ModelVersion** `string` `必选` | 模型版本

`ModelReference.FoundationModel.ModelVersion`

基础模型版本号，例如 `240615`。

**Name** `string` `必选` | 模型名称

`ModelReference.FoundationModel.Name`

基础模型名称，例如 `doubao-seed-2-1-pro-260628`。

**Name** `string` `必选` | 任务名称

批量推理任务名称，用于在控制台与查询接口中标识该任务。

**OutputDirTosLocation** `object` `必选` | 输出文件夹

批量推理任务结果输出的 TOS 文件夹路径。存储桶需与输入文件位于同一地域。

**BucketName** `string` `必选` | TOS 桶名称

`OutputDirTosLocation.BucketName`

TOS 桶名称。当前火山方舟仅支持华北 2-北京地域（`cn-beijing`）的 TOS 桶。

**ObjectKey** `string` `必选` | 对象路径

`OutputDirTosLocation.ObjectKey`

TOS 对象路径。输入为 JSONL 文件的完整 object key；输出文件夹路径建议以 `/` 结尾。

**CompletionWindow** `string` | 最大等待时间

批量推理任务的最大等待时间，超过该时间任务仍未完成则自动终止。常见取值如 `1d`（1 天）。

**Description** `string` | 任务描述

批量推理任务的描述信息，便于业务侧标注任务用途。

**DryRun** `boolean` `默认值 false` | 预检请求

是否仅对此请求进行预检。`true` 表示发送检查请求，仅校验参数合法性与权限，不实际创建任务；`false` 表示发送正常请求，执行创建操作。

**ProjectName** `string` `默认值 default` | 项目名称

资源所属的项目名称。若资源不在默认项目中，需填写正确的项目名称，获取方式请参考 [如何获取项目名称](/docs/modelark-faq)。

**Tags** `object[]` | 任务标签

批量推理任务绑定的标签列表，可用于资源分组与计费分摊。

**Key** `string` `必选` | 标签键

`Tags.Key`

**Value** `string` `必选` | 标签值

`Tags.Value`

## 响应参数

**Id** `string` | 任务 ID

创建成功后返回的批量推理任务 ID，可用于 *GetBatchInferenceJob* 等接口查询任务状态。


## 代码示例

## 默认

### cURL

#### Request

```bash
curl 'https://ark.cn-beijing.volcengineapi.com/?Action=CreateBatchInferenceJob&Version=2024-01-01' \
  -H 'Content-Type: application/json' \
  -H 'X-Date: <X-Date>' \
  -H 'X-Content-Sha256: <X-Content-Sha256>' \
  -H 'Authorization: HMAC-SHA256 Credential=<AK>/<X-Date>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<Signature>' \
  -d '{
    "Name": "批量推理任务",
    "Description": "这是一个批量推理任务",
    "ModelReference": {
      "FoundationModel": {
        "Name": "doubao-seed-2-0-pro",
        "ModelVersion": "260215"
      }
    },
    "InputFileTosLocation": {
      "BucketName": "my-bucket-name",
      "ObjectKey": "batch-inference-job/dataset/my-job.jsonl"
    },
    "OutputDirTosLocation": {
      "ObjectKey": "batch-inference-job/output/",
      "BucketName": "my-bucket-name"
    },
    "ProjectName":"default",
    "CompletionWindow": "1d",
    "Tags": [
      {
        "Key": "test_key",
        "Value": "test_value"
      }
    ]
}
'
```

#### Response

```
{
  "ResponseMetadata": {
    "RequestId": "20240918194640ECB302768CB287CEDA",
    "Action": "CreateBatchInferenceJob",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "bi-20240918194641-r2nwq"
  }
}
```