對於資料標註、內容產生等無需即時響應的情境,即時推理API存在成本高、並發受限的問題。阿里雲百鍊的批量對話(Batch Chat)API ,保持了與即時API一致的同步調用方式,您只需發起請求等待最終結果返回。目前該功能享有 官網限時 5 折優惠 ,能將您的推理成本直接降低 50%。
本介面僅支援提交單個請求。如需一次性傳入多個請求,可通過檔案方式提交,詳情請參考OpenAI相容-Batch(檔案輸入)。
工作原理
-
請求提交:用戶端發起請求並建立串連。
-
串連保持:請求進入隊列排隊,用戶端保持串連等待。
-
同步返回:請求處理完成後,服務端通過之前持續連線,將完整結果一次性返回給用戶端。
如果超過最長等待時間,串連將自動斷開並返回逾時錯誤。
適用範圍
中國(北京)
- 文本產生模型:qwen4-max、qwen3.8-max、qwen3.8-flash、qwen3.7-max、qwen3.7-plus、qwen3.6-plus、qwen3.7-flash、qwen3.6-flash、qwen3.5-plus、qwen3.5-flash、qwen-plus、qwen-flash
- 映像與視頻理解模型:qwen4-max、qwen3.8-max、qwen3.8-flash、qwen3.7-plus、qwen3.6-plus、qwen3.7-flash、qwen3.6-flash、qwen3.5-plus、qwen3.5-flash、qwen3.5-omni-plus、qwen3.5-omni-flash、qwen3-vl-plus
重要
- 在Batch 情境下,
qwen3.8-max、qwen3.8-flash、qwen3.7-max、qwen3.7-plus、qwen3.6-plus、qwen3.7-flash、qwen3.6-flash、qwen3.5-plus、qwen3.5-flash、qwen3.5-omni-flash和qwen3.5-omni-plus單次請求的上下文 Token 數最大支援 256K,qwen3.5-omni-plus和qwen3.5-omni-flash不支援語音輸出。 - 部分模型支援思考模式,開啟後會產生思考
tokens導致成本增加。 qwen3.8、qwen3.7、qwen3.6和qwen3.5系列模型預設開啟思考模式。建議使用混合思考模型時,顯式設定enable_thinking參數(true開啟/false關閉)。- 在 JSONL 請求體中,
enable_thinking為body的頂層參數,須與model同級傳入,不能放在extra_body中。
如何使用
前提條件
-
已開通阿里雲百鍊服務,並已擷取 API Key。
建議配置API Key到環境變數中以降低API Key的泄露風險。
-
若通過OpenAI SDK進行調用,需要安裝SDK。
pip3 install -U openai
步驟1:配置 API 端點
只需修改 API 端點(base_url),即可輕鬆將現有的即時推理請求切換至批量推理。請根據調用方式,配置正確的 API 端點。
SDK配置:將base_url設定為https://batch.dashscope.aliyuncs.com/compatible-mode/v1
HTTP調用:請求端點為POST https://batch.dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
步驟2:發起調用
此處以文本對話為例,展示如何調用 Batch Chat 介面。
請求的預設等待逾時時間為3600秒(1小時),在多數情況下無需額外配置。
下方樣本展示如何主動設定一個自訂的逾時時間(60-3600秒)作為參考。
Python
請求樣本import os
from openai import OpenAI
client = OpenAI(
# 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx",但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险.
api_key=os.getenv("DASHSCOPE_API_KEY"),
base_url="https://batch.dashscope.aliyuncs.com/compatible-mode/v1", # 阿里云百炼Batch chat API 的 URL
).with_options(timeout=1800.0) # 设置1800秒(30分钟)的等待时间,最长3600秒
completion = client.chat.completions.create(
model="qwen-plus",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "你是谁?"},
]
)
print(completion.choices[0].message.content)
響應樣本我是千问,阿里巴巴集团旗下的超大规模语言模型。我能够回答问题、创作文字,比如写故事、写公文、写邮件、写剧本、逻辑推理、编程等等,还能表达观点,玩游戏等。如果你有任何问题或需要帮助,欢迎随时告诉我!
Java
請求樣本import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import java.time.Duration;
public class Main {
public static void main(String[] args) {
OpenAIClient client = OpenAIOkHttpClient.builder()
// 若没有配置环境变量,可用百炼API Key将下行替换为:.apiKey("sk-xxx")。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.baseUrl("https://batch.dashscope.aliyuncs.com/compatible-mode/v1") // # 阿里云百炼Batch chat API 的 URL
.timeout(Duration.ofSeconds(1800)) // 设置等待时间1800秒(半小时),最长3600秒
.build();
ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
.addUserMessage("你是谁")
.model("qwen-plus")
.build();
try {
ChatCompletion chatCompletion = client.chat().completions().create(params);
System.out.println(chatCompletion);
} catch (Exception e) {
System.err.println("Error occurred: " + e.getMessage());
e.printStackTrace();
}
}
}
響應樣本ChatCompletion{id=chatcmpl-a12c115e-15fc-94f9-a984-81bd65f0527b, choices=[Choice{finishReason=stop, index=0, logprobs=, message=ChatCompletionMessage{
content=我是千问,阿里巴巴集团旗下的超大规模语言模型。我可以帮助你回答问题、创作文字、提供信息查询等服务。很高兴认识你!, refusal=, role=assistant, annotations=, audio=, functionCall=, toolCalls=, additionalProperties={}}, additionalProperties={}}], created=1763609020, model=qwen-plus, object_=chat.completion, serviceTier=, systemFingerprint=, usage=CompletionUsage{completionTokens=33, promptTokens=10, totalTokens=43, completionTokensDetails=, promptTokensDetails=, additionalProperties={}}, additionalProperties={}}
Node.js
請求樣本import OpenAI from "openai";
const openai = new OpenAI(
{
// 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey: "sk-xxx",但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
apiKey: process.env.DASHSCOPE_API_KEY,
baseURL: "https://batch.dashscope.aliyuncs.com/compatible-mode/v1", // 阿里云百炼Batch chat API的 URL
// 在这里添加超时设置 (单位:毫秒)
// 1800秒 * 1000 = 1,800,000 毫秒,最长支持 3,600,000 毫秒
timeout: 1800 * 1000,
}
);
async function main() {
const completion = await openai.chat.completions.create({
model: "qwen-plus", //此处以qwen-plus为例,可按需更换模型名称。
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "你是谁?" }
],
});
console.log(JSON.stringify(completion))
}
main();
響應樣本{
"created": 1763618557,
"usage": {
"completion_tokens": 80,
"prompt_tokens": 22,
"total_tokens": 102
},
"model": "qwen-plus",
"id": "chatcmpl-af23c086-8662-91eb-b236-892032ddee92",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"role": "assistant",
"content": "我是千问,由阿里云研发的超大规模语言模型。我能够回答问题、创作文字,如写故事、公文、邮件、剧本等,还能进行逻辑推理、编程,表达观点,玩游戏等。我支持多种语言,包括中文、英文、德语、法语、西班牙语等。如果你有任何问题或需要帮助,欢迎随时告诉我!"
}
}
],
"object": "chat.completion"
}
Go
請求樣本package main
import (
"context"
"os"
"time"
"github.com/openai/openai-go"
"github.com/openai/openai-go/option"
)
func main() {
client := openai.NewClient(
option.WithAPIKey(os.Getenv("DASHSCOPE_API_KEY")),
// 阿里云百炼Batch chat API 的 URL
option.WithBaseURL("https://batch.dashscope.aliyuncs.com/compatible-mode/v1"),
)
// 设置超时时间:1800秒 = 30分钟,最长支持3600秒
ctx, cancel := context.WithTimeout(context.Background(), 3600*time.Second)
defer cancel()
chatCompletion, err := client.Chat.Completions.New(
ctx, openai.ChatCompletionNewParams{
Messages: []openai.ChatCompletionMessageParamUnion{
openai.UserMessage("你是谁"),
},
Model: "qwen-plus",
},
)
if err != nil {
panic(err.Error())
}
println(chatCompletion.Choices[0].Message.Content)
}
響應樣本我是千问,由阿里云研发的超大规模语言模型。我可以生成各种类型的文本,如文章、故事、诗歌、故事等,并能够根据不同的场景和需求进行变换和扩展。此外,我还能够回答各种问题,提供帮助和解决方案。很高兴为您服务!
C#(HTTP)
請求樣本using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
class Program
{
private static readonly HttpClient httpClient = new HttpClient
{
// 设置超时时间:1800秒 = 30分钟,最长支持3600秒
Timeout = TimeSpan.FromSeconds(1800)
};
static async Task Main(string[] args)
{
// 若没有配置环境变量,请用百炼API Key将下行替换为:string? apiKey = "sk-xxx";
string? apiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY");
if (string.IsNullOrEmpty(apiKey))
{
Console.WriteLine("API Key 未设置。请确保环境变量 'DASHSCOPE_API_KEY' 已设置。");
return;
}
// 设置请求 URL 和内容
string url = "https://batch.dashscope.aliyuncs.com/compatible-mode/v1/chat/completions"; // Batch chat API 的 URL
// 此处以qwen-plus为例,可按需更换模型名称。
string jsonContent = @"{
""model"": ""qwen-plus"",
""messages"": [
{
""role"": ""system"",
""content"": ""You are a helpful assistant.""
},
{
""role"": ""user"",
""content"": ""你是谁?""
}
]
}";
// 发送请求并获取响应
string result = await SendPostRequestAsync(url, jsonContent, apiKey);
// 输出结果
Console.WriteLine(result);
}
private static async Task<string> SendPostRequestAsync(string url, string jsonContent, string apiKey)
{
using (var content = new StringContent(jsonContent, Encoding.UTF8, "application/json"))
{
// 设置请求头
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
// 发送请求并获取响应
HttpResponseMessage response = await httpClient.PostAsync(url, content);
// 处理响应
if (response.IsSuccessStatusCode)
{
return await response.Content.ReadAsStringAsync();
}
else
{
return $"请求失败: {response.StatusCode}";
}
}
}
}
響應樣本{
"created": 1763620689,
"usage": {
"completion_tokens": 60,
"prompt_tokens": 22,
"total_tokens": 82
},
"model": "qwen-plus",
"id": "chatcmpl-db85828d-af47-97a3-a2f4-120b8f7d72d3",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"role": "assistant",
"content": "我是千问,阿里巴巴集团旗下的超大规模语言模型。我能够回答问题、创作文字,比如写故事、写公文、写邮件、写剧本、逻辑推理、编程等等,还能表达观点,玩游戏等。如果你有任何问题或需要帮助,欢迎随时告诉我!"
}
}
],
"object": "chat.completion"
}
PHP(HTTP)
請求樣本<?php
// 设置Batch Chat 请求 的 URL
$url = 'https://batch.dashscope.aliyuncs.com/compatible-mode/v1/chat/completions';
// 若没有配置环境变量,请用百炼API Key将下行替换为:$apiKey = "sk-xxx";
$apiKey = getenv('DASHSCOPE_API_KEY');
// 设置请求头
$headers = [
'Authorization: Bearer '.$apiKey,
'Content-Type: application/json'
];
// 设置请求体
$data = [
// 此处以qwen-plus为例,可按需更换模型名称。
"model" => "qwen-plus",
"messages" => [
[
"role" => "system",
"content" => "You are a helpful assistant."
],
[
"role" => "user",
"content" => "你是谁?"
]
]
];
// 初始化cURL会话
$ch = curl_init();
// 设置cURL选项
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
// 在此处设置Batch chat 请求的超时时间:1800秒 = 30分钟,最长支持3600秒
curl_setopt($ch, CURLOPT_TIMEOUT, 1800);
// 执行cURL会话
$response = curl_exec($ch);
// 检查是否有错误发生
if (curl_errno($ch)) {
echo 'Curl error: ' . curl_error($ch);
}
// 关闭cURL资源
curl_close($ch);
// 输出响应结果
echo $response;
?>
響應樣本{
"created": 1763621824,
"usage": {
"completion_tokens": 81,
"prompt_tokens": 22,
"total_tokens": 103
},
"model": "qwen-plus",
"id": "chatcmpl-b25aeb86-5cfe-93ea-ab03-aa3de1381c23",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"role": "assistant",
"content": "我是千问,由阿里云研发的超大规模语言模型。我能够回答问题、创作文字,如写故事、公文、邮件、剧本等,还能进行逻辑推理、编程,甚至表达观点和玩游戏。我支持多种语言,包括但不限于中文、英文、德语、法语、西班牙语等。如果你有任何问题或需要帮助,欢迎随时告诉我!"
}
}
],
"object": "chat.completion"
}
curl
請求樣本設定最長等待時間max-time為1800秒,最長支援3600秒。
curl -X POST https://batch.dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
--max-time 1800 \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen-plus",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "你是谁?"
}
]
}'
響應樣本{
"created": 1763622152,
"usage": {
"completion_tokens": 79,
"prompt_tokens": 22,
"total_tokens": 101
},
"model": "qwen-plus",
"id": "chatcmpl-daa344d2-60df-9b79-81a4-28c9a10a0a0e",
"choices": [
{
"finish_reason": "stop",
"index": 0,
"message": {
"role": "assistant",
"content": "我是千问,阿里巴巴集团旗下的超大规模语言模型。我能够回答问题、创作文字,如写故事、公文、邮件、剧本等,还能进行逻辑推理、编程,表达观点,玩游戏等。我支持多种语言,包括但不限于中文、英文、德语、法语、西班牙语等。如果你有任何问题或需要帮助,欢迎随时告诉我!"
}
}
],
"object": "chat.completion"
}
使用限制
-
等待時間:提交請求後,會同步等待結果,服務端最長會保持串連3600秒(1小時)。可根據實際需求設定自訂逾時時間,取值範圍為60-3600秒。
-
並發限制:單個賬戶為每個模型最多可維持10,000個等待中的請求。超出此限制的新請求將被拒絕並返回相應錯誤碼,直到有請求完成並釋放出可用位置。
-
調用速率:單個賬戶提交請求的頻率上限為 1000 QPS(10,000次 / 10秒)。
此上限為系統設定的理論最大值。在實際調用中,API的可用資源會受到整體系統負載的動態影響,建議您在代碼中實現重試邏輯。
計費說明
- 計費單價:按成功請求的輸入和輸出Token計費,目錄價與對應模型即時調用價格一致。官網限時為 Batch Chat 調用提供 5 折優惠,其最終費用為即時調用價格的 50%,具體請參見模型列表。
- 計費範圍:僅對任務中成功執行的請求進行計費。任何失敗的請求(包括系統錯誤或逾時)均不計費。
錯誤碼
如果模型調用失敗並返回報錯資訊,請參見錯誤碼進行解決。
常見問題
-
Batch Chat 請求耗時和即時 API 比較有區別嗎?
有區別。Batch Chat 請求需要排隊等待調度,因此端到端耗時通常高於即時 API。請求在服務端最長等待時間為1小時,逾時未執行將自動斷開並返回錯誤。
-
如何選擇使用 Batch Chat 還是Batch File?
當商務邏輯需要以 API 同步調用的方式、高並發地提交大量獨立的對話請求時,選擇 Batch Chat。當需要處理的是包含大量請求的單個大檔案,並且可以接受非同步擷取結果檔案,則選擇 Batch File。
-
Batch Chat 能保證請求全部完成嗎?
不保證。Batch Chat 使用的是 Batch 資源,完成情況取決於系統資源分派情況。如果系統資源繁忙,請求可能在隊列中等待。若超過最長等待時間仍未被調度執行,串連將逾時斷開,此時請求不會被計費,可以稍後重試。
相關文檔
- 查看模型即時調用的完整參數列表,請參閱OpenAI相容-Chat。
- 如需通過提交檔案進行批量處理,並非同步擷取結果,請參閱OpenAI相容-Batch(檔案輸入)。