批量推理（Batch Inference）适用于无需实时响应的推理场景，可以一次性离线处理大量数据。相比在线推理，批量推理提供更高额度的访问限制，用户无需关注单次请求的执行情况，适合于模型评测、批量回归等场景。

目前支持批量推理的模型见适用模型。

如您希望提升批量推理总配额，或者有其他的语言模型需要进行批量推理，您可以发起工单申请。

方舟为您提供两种方式使用批量推理服务。

• 批量推理任务：业界常规的批量、离线使用模式，使用离线链路。需要配合火山引擎对象存储（TOS）使用。
• 批量推理接入点：不需要依赖存储，直接请求方舟模型接口。和在线推理当前的使用方式接近。

选型推荐见 选择调用方式。

业界常规的批量、离线使用模式，使用离线链路。需要配合火山引擎对象存储（TOS）使用。

使用流程

1.准备与上传文件

请参照 数据文件格式说明准备包含您要进行推理的请求的输入文件，并确保账户已启用 TOS，之后将准备好的输入文件上传至您的 TOS 中。

2.创建批量推理任务

1. 在批量推理页面，单击 开始批量推理 按钮跳转至创建页。
2. 按照控制台提示，填写批量推理任务表单。

   这里调用方式选择 创建批量推理任务。

3. 查看与管理批量推理任务

可在批量推理任务列表页、或点击批量推理任务名称进入任务详情页，查看批量推理任务的信息，包括任务基本信息、状态、进度（包含已处理请求数量/总请求数量，以及已处理请求中失败的数量）、配置信息等。
批量推理任务状态与对应描述如下：

4.查看结果文件

在批量推理任务运行结束后，可点击 查看结果 按钮或在详情页的「使用量文件信息」中点击跳转至 TOS 页面查看并下载结果文件。
结果文件的 TOS 存储路径如下：
• 结果文件：{OutputDirectory}/{batch_job_id}/output/results.jsonl
• 错误信息文件：{OutputDirectory}/{batch_job_id}/error/errors.jsonl

5.订阅通知（可选）

您可以使用火山引擎消息通知服务（后简称 SNS） 来感知批量任务进度，包括批量推理任务完成或失败，通知的字段如下。

订阅流程

1. 申请开通 SNS ，请提交工单申请“SNS 开白”，并同步申请对应的消息事件：
   • BatchJobFinished：批量推理任务完成。
   • BatchJobFailed：批量推理任务失败。
2. 在 主题 页面创建主题。
   • 发布者选项指定账号：2100444922。
   • 服务选择：ark。

3. 在 云服务事件订阅 页面创建事件订阅。Topic TRN 选择刚刚创建的主题，事件选择BatchJobFinished、BatchJobFailed。

4. 在订阅页面，订阅前面创建的主题，推送类型选择 HTTP/HTTPS，并配置可接收端地址。

• 配置完订阅后，SNS 会向接收端发送对应的确认链接，需确认该链接来完成订阅，确认链接 demo 如下，需要回调下文中 SubscribeURL。

{
  "Type": "SubscriptionConfirmation",
  "MessageId": "f11b9a8f-****",
  "TopicTrn": "trn:sns:cn-beijing:2100000825:topic/test",
  "Message": "You have chosen to subscribe to the topic trn:sns:cn-beijing:2100000825:topic/wyy_test. To confirm the subscription, visit the SubscribeURL included in this message.",
  "Timestamp": "2025-01-14T07:18:59Z",
  "SignatureVersion": "1",
  "Signature": "MEUCIB3NsKw***=",
  "SigningCertURL": "https://sns-public-cn-beijing.tos-cn-beijing.volces.com/certificates/cn-beijing-a31d91fc-0683-****.pem",
  "SubscribeToken": "eyJhbGciOiJIUzI1Ni****",
  "SubscribeURL": "https://sns.cn-beijing.volcengineapi.com?Action=ConfirmSubscription&Version=2023-01-01&Token=eyJhbGc***"
}

您也可以使用函数服务订阅信息。在推送类型选择函数服务，通过函数自定义开发通知处理逻辑，与下游应用串联。

5. 回调成功后可在 订阅 页面看到对应的订阅状态为：已确认，表示订阅已完成。

订阅信息内容格式

批量推理任务完成

批量推理任务完成时通知的内容。

• EventID: 通知 ID。
• Project: 项目名称。
• EventName: BatchJobFinished。
• EventTime: 批量推理任务完成时间。
• AccountID: 用户的主账号 ID。
• JobInfo
  • JobID：批量推理任务 ID。
  • JobName：批量推理任务 ID。
  • Message：任务信息。
  • FailNum：失败数：此批量推理任务完成时，请求未成功执行的数量。
  • TotalNum：此批量推理任务提交的任务总数。
  • SuccessNum: 此批量推理任务完成时，请求成功执行的数量。
  • FailFileTOSPath：失败任务 TOS 文件路径。
    • BucketName：桶名。
    • ObjectKey：文件名。
  • SuccessFileTOSPath：成功任务TOS文件路径。
    • BucketName：桶名。
  • ObjectKey：文件名。

返回示例：

{
  "Type": "Notification",
  "MessageId": "7dfcdd57-****-****-****-618c4d4c6787",
  "TopicTrn": "trn:sns:cn-beijing:2100000825:topic/test",
  "Subject": "ark:BatchJobFinished",
  "Message": "{\"EventID\":\"bi-20250114161208-bk2hr\",\"Project\":\"default\",\"EventName\":\"BatchJobFinished\",\"EventTime\":\"2025-01-14T16:12:08+08:00\",\"AccountID\":2100000825,\"JobInfo\":{\"JobID\":\"bi-20250114161117-hjtpg\",\"JobName\":\"批量推理回归\",\"Message\":\"\",\"FailNum\":0,\"TotalNum\":1,\"SuccessNum\":1,\"FailFileTOSPath\":{\"BucketName\":\"\",\"ObjectKey\":\"\"},\"SuccessFileTOSPath\":{\"BucketName\":\"qa-data\",\"ObjectKey\":\"批量推理/result/\"}}}",
  "Timestamp": "2025-01-14T08:12:08Z",
  "SignatureVersion": "1",
  "Signature": "MEYCIQD****",
  "SigningCertURL": "https://sns-public-cn-beijing.tos-cn-beijing.volces.com/certificates/cn-beijing-****.pem",
  "UnsubscribeToken": "eyJhbGciO****",
  "UnsubscribeURL": "https://sns.cn-beijing.volcengineapi.com?Action=Unsubscribe&Version=2023-01-01&Token=eyJhbGciO****"
}

批量推理任务失败

批量推理任务执行失败时通知的内容。

• EventID: 通知 ID。
• Project: 项目名称。
• EventName: BatchJobFailed。
• EventTime: 批量推理任务完成时间。
• AccountID: 用户的主账号 ID。
• JobInfo
  • JobID：批量推理任务 ID。
  • JobName：批量推理任务 ID。
  • Message：失败原因。

{
  "Type": "Notification",
  "MessageId": "e350ff5b-****-****-****-41c3a44924bd",
  "TopicTrn": "trn:sns:cn-beijing:2100000825:topic/test",
  "Subject": "ark:BatchJobFailed",
  "Message": "{\"EventID\":\"bi-20250114154404-tztv4\",\"Project\":\"default\",\"EventName\":\"BatchJobFailed\",\"EventTime\":\"2025-01-14T15:44:04+08:00\",\"AccountID\":2100000825,\"JobInfo\":{\"JobID\":\"bi-20250114154324-hkd5t\",\"JobName\":\"wyy\",\"Message\":\"推理任务失败，第361行非json数据, err=\\\"Syntax error at index 91: invalid char\\\\n\\\\n\\\\tssages\\\\\\\":[\\\\\\\"role\\\\\\\":\\\\\\\"user\\\\\\\",\\\\\\\"content\\\\\\\"\\\\n\\\\t................^...............\\\\n\\\"\"}}",
  "Timestamp": "2025-01-14T07:44:04Z",
  "SignatureVersion": "1",
  "Signature": "MEUCIQ****",
  "SigningCertURL": "https://sns-public-cn-beijing.tos-cn-beijing.volces.com/certificates/cn-beijing-****.pem",
  "UnsubscribeToken": "eyJhbGciO****",
  "UnsubscribeURL": "https://sns.cn-beijing.volcengineapi.com?Action=Unsubscribe&Version=2023-01-01&Token=eyJhbGciO****"
}

数据文件格式说明

输入文件

输入文件为一个.jsonl文件，其中每行包含对 API 的单个请求的详细信息。
以下是包含 2 个请求的输入文件的示例。

{"custom_id": "request-1", "body": {"messages": [{"role": "user", "content": "天空为什么这么蓝？"}],"max_tokens": 1000,"top_p":1,"temperature":0.7}}
{"custom_id": "request-2", "body": {"messages": [{"role": "system", "content": "You are an unhelpful assistant."},{"role":"user", "content":"天空为什么这么蓝？"}],"max_tokens":1000}}

{"custom_id":"request-1","body":{"messages":[{"role":"user","content":[{"type":"text","text":"支持输入是图片的模型系列是哪个？"},{"type":"image_url","image_url":{"url":"https://ark-project.tos-cn-beijing.volces.com/doc_image/ark_demo_img_1.png"}}]}],"max_tokens":1000,"top_p":1,"temperature":0.7}}
{"custom_id":"request-2","body":{"messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"https://ark-project.tos-cn-beijing.volces.com/doc_image/ark_demo_img_1.png"}},{"type":"image_url","image_url":{"url":"https://ark-project.tos-cn-beijing.volces.com/doc_image/ark_demo_img_2.png"}},{"type":"text","text":"图片里都有什么？"}]}],"max_tokens":1000}}

{"custom_id":"request-1","body":{"messages":[{"role":"user","content":[{"type":"text","text":"视频里有什么？"},{"type":"video_url","video_url":{"url":"https://ark-project.tos-cn-beijing.volces.com/doc_video/ark_vlm_video_input.mp4"}}]}],"max_tokens":1000,"top_p":1,"temperature":0.7}}
{"custom_id":"request-2","body":{"messages":[{"role":"user","content":[{"type":"video_url","video_url":{"url":"https://ark-project.tos-cn-beijing.volces.com/doc_video/ark_vlm_video_input_2.mp4"}},{"type":"video_url","video_url":{"url":"https://ark-project.tos-cn-beijing.volces.com/doc_video/ark_vlm_video_input_3.mp4"}},{"type":"text","text":"视频里都有什么？"}]}],"max_tokens":1000}}

{"custom_id": "request-1", "body": {"input": ["天很蓝","海很深"]}}

{"custom_id": "request-1", "body": {"input": [{"text": "天很蓝，海很深","type": "text"},{"image_url": {"url": "https://ark-project.tos-cn-beijing.volces.com/images/view.jpeg"},"type": "image_url"}]}}

使用说明：

• 用户默认最大文件大小为 5 GB。

• 每个请求都必须包含一个唯一custom_id值（在jsonl文件中唯一，需为字符串类型），便于您使用该值在结果数据中找到对应的请求。

• 每条 request 都是独立的请求，独立发出，独立收到结果。如有多个请求有相同提示词，也需要在请求中都加上对应的相同的提示词。

• 每行body字段中的参数与底层模型调用 API 的 request body 中参数相同，为一个合法的JSON Object。下面是一些常见配置，完整API 请求体说明请参见对应 API 参考：对话(Chat) API、文本向量化 API、图像向量化 API。

  • 输出长度控制，配置 max_tokens。

    {"custom_id": "request-1", "body": {"messages": [{"role": "system", "content": "You are an unhelpful assistant."},{"role":"user", "content":"天空为什么这么蓝？"}],"max_tokens":1000}}
    

  • 关闭深度思考，设置 thinking 字段（需模型支持 thinking 字段）。

    {"custom_id": "request-1", "body": {"messages": [{"role": "system", "content": "You are an unhelpful assistant."},{"role":"user", "content":"天空为什么这么蓝？"}],"thinking":{"type":"disabled"}}}
    

  • 控制模型回复的丰富度，设置 temperature 、top_p 字段 。

    {"custom_id": "request-1", "body": {"messages": [{"role": "user", "content": "天空为什么这么蓝？"}],"top_p":1,"temperature":0.7}}
    

• 每个输入文件只能包含一个批量推理接入点的请求。

• 视觉理解批量任务，传入图片/视频的方式要求如下：

  • 支持 TOS（火山引擎对象存储）链接和TOS地址（tos://<bucket>/<object_key>），其中如果使用TOS地址需要在控制台完成TOS资源授权，具体请参见对象存储授权。
  • 不支持其他链接和 Base64 编码。

• 批量推理中包含的图片链接请保持长期可用（推荐7天），TOS 预签名链接默认过期时长为1小时，为避免图片链接过期导致批量推理任务失败，请手动变更过期时间（建议设置为7天），完整签名字段说明见TOS 预签名文档。

  ...
      # 1. 创建TOS客户端
      client = tos.TosClientV2(AK, SK, ENDPOINT, REGION)
  
      # 2. 生成“下载图片”的预签名URL（GET方法，有效时间3600秒）
      download_pre_signed = client.pre_signed_url(
          HttpMethodType.Http_Method_Get,  # 下载用GET方法（核心！）
          bucket_name=BUCKET_NAME,
          key=OBJECT_KEY,
          expires=604800  # 下载URL有效期，可按需调整（如86400=24小时）
      )
   ...
  

• 为避免因为文件格式错误，导致批量推理任务失败，为您提供了脚本进行校验，检测前请配置您的文件。

jsonl_linter.py

未知大小

输出文件

• 结果文件为results.jsonl，输入文件中的每个成功请求行对应结果文件中的一个响应行，示例如下：

{"id": "batch-req-123", "custom_id": "request-1", "response": {"status_code": 200, "request_id": "req1", "body": {"id": "chatcmpl-9P3WtvGUhW5Ty91CdlcBJPgqh1rGG", "object": "chat.completion", "created": 1711111111, "model": "doubao-pro-32k-240515", "choices": [{"index": 0, "message": {"role": "assistant", "content": "天空呈现蓝色是因为“瑞利散射”现象。简单来说，就是当太阳光进入地球大气层时，波长较长的红光、橙光、黄光能穿透大气层，直接射到地面，而波长较短的蓝、紫、靛等色光，很容易被悬浮在空气中的微粒阻挡，从而使光线散射向四方，使天空呈现出蔚蓝色。"}, "logprobs": null, "finish_reason": "stop"}], "usage": {"prompt_tokens": 20, "completion_tokens": 9, "total_tokens": 29}}}, "error": null}

• 任何失败的请求都会将其错误信息写入错误文件errors.jsonl，每个失败请求行对应错误文件中的一个响应行，示例如下：

{"id":"batch-req-456","custom_id":"request-2","response":null,"error":{"code":"AccessDenied","type":"Forbidden","message":"The request failed because you do not have access to the requested resource."}}

不需要依赖存储，直接请求方舟模型接口，和在线推理当前的使用方式接近。

使用流程

1.创建批量推理接入点并获取批量推理接入点ID

1. 打开批量推理创建页面。
2. 按照页面进行配置，在 调用方式 配置项，选择 创建批量推理接入点。
3. 返回到批量推理页面，点击右侧接入点页签，可以查看您批量推理接入点 ID。

批量推理接入点ID的格式为：ep-bi-***。

2.使用批量推理接入点 SDK 进行批量推理

具体调用方式请参考示例代码。

TPD 配额

10B TPD/模型

• 配额单位：是 TPD（Tokens Per Day），指 24 小时内可消耗的 token 配额。
• 配额共享：此配额是基于模型设定的，账户下使用同一模型的所有批量推理任务共享该额度。
  • 不区分子账号，即账户下所有子账号均共享配额。
  • 不区分版本，如 doubao-seed-1.6 下 250615、251015 版本共享配额。
• 配额隔离：额度与在线推理的模型限流（在线推理限流请参见开通管理页）隔离。运行批量推理任务不会消耗模型的在线推理限流。
• 超配额任务：当用户提交超 TPD 配额任务，会在平台资源空闲时尝试继续执行。

如您希望提升批量推理总配额，您可发起工单申请。

其他配额

账户维度还有如下配额：

• 提交任务数量限制：单项目下 7 天内提交的批量推理任务数量最多为 5000，超出时将暂时无法提交新的任务。
• 同时运行中的任务数量限制：单项目下同时处于「运行中」状态的批量推理任务数量最多为 20，超出时其余任务将处于「排队中」状态等待运行。

账号下实际同时运行的任务数量会受到平台总体资源的限制和任务调度策略的影响。

批量推理按 tokens 用量后付费，您仅需要为已处理的请求消耗的 token 量付费，具体用量可在批量推理任务详情页「Tokens 使用量」查看。

• 批量推理（SDK教程）：通过接口实现批量推理的教程。
• 批量推理任务最佳实践：如何通过控制台或者 API 使用批量推理能力，处理完成大规模数据处理任务。
• CreateBatchInferenceJob - 创建批量推理任务：使用 API 创建批量推理任务。
• ListBatchInferenceJobs - 获取批量推理任务列表：查看批量推理任务及任务状态。

• 在任务状态为：运行中，终止中，已终止，失败的情况时，是否会有部分成功的结果输出？
• 基于什么的准则，去判断“失败”这种状态，是成功与错误比例，还是发现错误即判断失败？
• 在子任务数量巨大，无法预估处理所需的时间的前提下，设置的最大等待时间是否有大小上限？
• 若由于超时使得批量推理任务状态为“已终止”，在终止之前所做的任务处理结果是否还有保留？
• 输出长度是4k还是6k，亦或是其他？
• 批量推理按 tokens 用量计费，是按照输入tokens，或是输出tokens，又或是两者之和？
• 对于处理失败的结果，也就是errors.jsonl中的结果，如何计费？