Skip to main content

Compatível com OpenAI - Batch (entrada de arquivo)

O Alibaba Cloud Model Studio oferece uma API de Arquivo em Lote (Batch File API) compatível com a OpenAI, que permite enviar solicitações em massa por meio de arquivos. O sistema processa todas as solicitações de forma assíncrona e retorna os resultados após a conclusão de todas as solicitações ou quando o tempo máximo de espera é atingido. Os custos correspondem a apenas 50% das chamadas em tempo real. Isso é adequado para cenários como análise de dados e avaliação de modelos que não são sensíveis ao tempo, mas exigem processamento em grande escala.

Para usar o console, consulte Inferência em lote.

Fluxo de trabalho

image

Pré-requisitos

É possível chamar a API de Arquivo em Lote por meio do SDK da OpenAI (Python, Node.js) ou da API HTTP.

Escopo

  • Singapore
  • China (Beijing)
Modelos suportados:
  • Modelos de geração de texto
    • Qwen Max: qwen3.8-max, qwen-max
    • Qwen Plus: qwen3.7-plus, qwen-plus
    • Qwen Flash: qwen-flash
  • Modelos multimodais
  • Em cenários de lote, 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 e qwen3.5-omni-plus suportam no máximo 256 K tokens de contexto por solicitação; qwen3.5-omni-plus e qwen3.5-omni-flash não oferecem suporte à saída de voz.
  • Alguns modelos oferecem suporte ao modo de raciocínio (thinking). Quando ativado, são gerados tokens de raciocínio, o que aumenta os custos.
  • Os modelos das séries qwen3.8, qwen3.7, qwen3.6 e qwen3.5 têm o modo de raciocínio ativado por padrão. Ao usar um modelo de raciocínio híbrido, recomendamos definir explicitamente o parâmetro enable_thinking (true para ativar / false para desativar).
  • No corpo da solicitação JSONL, enable_thinking é um parâmetro de nível superior de body e deve ser passado no mesmo nível de model; não pode ser colocado em extra_body.

Início rápido

Antes de processar tarefas de produção, use o modelo de teste batch-test-model para um teste de ponta a ponta. Esse modelo ignora o processo de inferência e retorna diretamente uma resposta de sucesso fixa, usada para verificar se a cadeia de chamadas de API e o formato dos dados estão corretos.
Limitações do modelo de teste (batch-test-model):
  • Os arquivos de teste devem atender aos requisitos do arquivo de entrada, com tamanho de no máximo 1 MB e no máximo 100 linhas.
  • Limite de concorrência: até 2 tarefas simultâneas.
  • Tarifas: o modelo de teste não gera custos de inferência de modelo.

Etapa 1: Preparar o arquivo de entrada

Prepare um arquivo chamado test_model.jsonl com o seguinte conteúdo:
{"custom_id":"1","method":"POST","url":"/v1/chat/ds-test","body":{"model":"batch-test-model","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"你好!有什么可以帮助你的吗?"}]}}
{"custom_id":"2","method":"POST","url":"/v1/chat/ds-test","body":{"model":"batch-test-model","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"}]}}
Entrada via codificação Base64:

Etapa 2: Executar o código

Com base na linguagem de programação que você usa, selecione um dos exemplos de código a seguir, salve-o no mesmo diretório do arquivo de entrada e execute-o. O código cobre o fluxo de trabalho completo: upload do arquivo, criação da tarefa, consulta de status e download dos resultados.
Para alterar o caminho do arquivo ou outros parâmetros, modifique o código conforme necessário.
Reutilizar um ID de arquivo existente: O ID retornado após o upload do arquivo (como file-batch-xxx) pode ser reutilizado. Se o conteúdo de entrada não for alterado, não é necessário fazer o upload novamente a cada vez; você pode criar diretamente uma tarefa com o ID existente:
batch = client.batches.create(
    input_file_id="file-batch-xxx",  # 直接使用已有文件 ID,无需重新上传
    endpoint="/v1/chat/completions",
    completion_window="24h"
)
É possível consultar os IDs de arquivos Batch enviados por meio da API client.files.list(purpose="batch").
OpenAI Python SDK
import os
from pathlib import Path
from openai import OpenAI
import time

# 初始化客户端
client = OpenAI(
    # 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx",但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
    # 新加坡和北京地域的API Key不同。
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下是新加坡地域的base_url,如果使用北京地域的模型,需要将base_url替换为:https://dashscope.aliyuncs.com/compatible-mode/v1
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"  # 阿里云百炼服务的base_url
)

def upload_file(file_path):
    print(f"正在上传包含请求信息的JSONL文件...")
    file_object = client.files.create(file=Path(file_path), purpose="batch")
    print(f"文件上传成功。得到文件ID: {file_object.id}\n")
    return file_object.id

def create_batch_job(input_file_id):
    print(f"正在基于文件ID,创建Batch任务...")
    # 请注意:此处endpoint参数值需和输入文件中的url字段保持一致.测试模型(batch-test-model)填写/v1/chat/ds-test,Embedding文本向量模型填写/v1/embeddings,其他模型填写/v1/chat/completions
    batch = client.batches.create(input_file_id=input_file_id, endpoint="/v1/chat/ds-test", completion_window="24h")
    print(f"Batch任务创建完成。 得到Batch任务ID: {batch.id}\n")
    return batch.id

def check_job_status(batch_id):
    print(f"正在检查Batch任务状态...")
    batch = client.batches.retrieve(batch_id=batch_id)
    print(f"Batch任务状态: {batch.status}\n")
    return batch.status

def get_output_id(batch_id):
    print(f"正在获取Batch任务中执行成功请求的输出文件ID...")
    batch = client.batches.retrieve(batch_id=batch_id)
    print(f"输出文件ID: {batch.output_file_id}\n")
    return batch.output_file_id

def get_error_id(batch_id):
    print(f"正在获取Batch任务中执行错误请求的输出文件ID...")
    batch = client.batches.retrieve(batch_id=batch_id)
    print(f"错误文件ID: {batch.error_file_id}\n")
    return batch.error_file_id

def download_results(output_file_id, output_file_path):
    print(f"正在打印并下载Batch任务的请求成功结果...")
    content = client.files.content(output_file_id)
    # 打印部分内容以供测试
    print(f"打印请求成功结果的前1000个字符内容: {content.text[:1000]}...\n")
    # 保存结果文件至本地
    content.write_to_file(output_file_path)
    print(f"完整的输出结果已保存至本地输出文件result.jsonl\n")

def download_errors(error_file_id, error_file_path):
    print(f"正在打印并下载Batch任务的请求失败信息...")
    content = client.files.content(error_file_id)
    # 打印部分内容以供测试
    print(f"打印请求失败信息的前1000个字符内容: {content.text[:1000]}...\n")
    # 保存错误信息文件至本地
    content.write_to_file(error_file_path)
    print(f"完整的请求失败信息已保存至本地错误文件error.jsonl\n")

def main():
    # 文件路径
    input_file_path = "test_model.jsonl"  # 可替换为您的输入文件路径
    output_file_path = "result.jsonl"  # 可替换为您的输出文件路径
    error_file_path = "error.jsonl"  # 可替换为您的错误文件路径
    try:
        # Step 1: 上传包含请求信息的JSONL文件,得到输入文件ID
        input_file_id = upload_file(input_file_path)
        # Step 2: 基于输入文件ID,创建Batch任务
        batch_id = create_batch_job(input_file_id)
        # Step 3: 检查Batch任务状态直到结束
        status = ""
        while status not in ["completed", "failed", "expired", "cancelled"]:
            status = check_job_status(batch_id)
            print(f"等待任务完成...")
            time.sleep(10)  # 等待10秒后再次查询状态
        # 如果任务失败,则打印错误信息并退出
        if status == "failed":
            batch = client.batches.retrieve(batch_id)
            print(f"Batch任务失败。错误信息为:{batch.errors}\n")
            print(f"参见错误码文档: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
            return
        # Step 4: 下载结果:如果输出文件ID不为空,则打印请求成功结果的前1000个字符内容,并下载完整的请求成功结果到本地输出文件;
        # 如果错误文件ID不为空,则打印请求失败信息的前1000个字符内容,并下载完整的请求失败信息到本地错误文件.
        output_file_id = get_output_id(batch_id)
        if output_file_id:
            download_results(output_file_id, output_file_path)
        error_file_id = get_error_id(batch_id)
        if error_file_id:
            download_errors(error_file_id, error_file_path)
            print(f"参见错误码文档: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")
    except Exception as e:
        print(f"An error occurred: {e}")
        print(f"参见错误码文档: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == "__main__":
    main()

Etapa 3: Verificar o resultado do teste

Após a conclusão bem-sucedida da tarefa, o arquivo de resultados result.jsonl contém a resposta fixa {"content":"This is a test result."}:
{"id":"a2b1ae25-21f4-4d9a-8634-99a29926486c","custom_id":"1","response":{"status_code":200,"request_id":"a2b1ae25-21f4-4d9a-8634-99a29926486c","body":{"created":1743562621,"usage":{"completion_tokens":6,"prompt_tokens":20,"total_tokens":26},"model":"batch-test-model","id":"chatcmpl-bca7295b-67c3-4b1f-8239-d78323bb669f","choices":[{"finish_reason":"stop","index":0,"message":{"content":"This is a test result."}}],"object":"chat.completion"}},"error":null}
{"id":"39b74f09-a902-434f-b9ea-2aaaeebc59e0","custom_id":"2","response":{"status_code":200,"request_id":"39b74f09-a902-434f-b9ea-2aaaeebc59e0","body":{"created":1743562621,"usage":{"completion_tokens":6,"prompt_tokens":20,"total_tokens":26},"model":"batch-test-model","id":"chatcmpl-1e32a8ba-2b69-4dc4-be42-e2897eac9e84","choices":[{"finish_reason":"stop","index":0,"message":{"content":"This is a test result."}}],"object":"chat.completion"}},"error":null}

Executar tarefas formais

Requisitos do arquivo de entrada

  • Formato: JSONL codificado em UTF-8 (um objeto JSON independente por linha)
  • Limites de tamanho: No máximo 50.000 solicitações por arquivo e no máximo 500 MB
  • Limites por linha: Cada objeto JSON não deve exceder 6 MB e não deve exceder o comprimento de contexto do modelo
  • Requisitos de consistência: Todas as solicitações no mesmo arquivo devem usar o mesmo modelo e o mesmo modo de raciocínio (se aplicável)
  • Identificador exclusivo: Cada solicitação deve conter um campo custom_id exclusivo dentro do arquivo, usado para corresponder solicitações a resultados
Cenário 1: Chat de texto Conteúdo do arquivo de exemplo:
{"custom_id":"1","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-plus","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"Hello!"}]}}
{"custom_id":"2","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-plus","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"}]}}
Cenário 2: Compreensão de imagem e vídeo Método de entrada com codificação Base64.
As strings Base64 dos exemplos foram omitidas; use o código Python abaixo para gerar a codificação completa.
  1. Converta o arquivo local para codificação Base64:
#  编码函数: 将本地文件转换为 Base64 编码的字符串
import base64
def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")

# 将xxxx/eagle.png替换为你本地图像的绝对路径
base64_image = encode_image("xxx/eagle.png")
  1. Construa o formato Data URL: data:[MIME_type];base64,{base64_image};
    1. MIME_type deve ser substituído pelo tipo de mídia real, garantindo que corresponda ao valor de MIME Type (por exemplo, image/jpeg, image/png);
    2. base64_image é a string Base64 gerada na etapa anterior.
Para detalhes completos (incluindo limites de arquivo, tipos MIME e métodos de codificação), consulte Passar arquivos locais (codificados em Base64 ou caminho de arquivo).
Ferramenta de geração de arquivo JSONL para inferência em lote A inferência em lote exige a construção de um arquivo JSONL, com cada linha sendo uma solicitação independente. O script Python a seguir pode ser executado diretamente para gerar um arquivo JSONL que está em conformidade com o formato.

Uso

  1. Salve o código a seguir como generate_batch_jsonl.py
  2. Modifique o conteúdo das solicitações da lista TASKS no script
  3. Execute python generate_batch_jsonl.py
  4. O arquivo batch_input.jsonl gerado pode ser usado diretamente para tarefas de inferência em lote

Script de geração de JSONL para modelos de geração de texto

#!/usr/bin/env python3
"""
Batch 推理 JSONL 文件生成工具

支持的地域与模型请参见上方“适用范围”。

文件大小限制:单行 ≤6MB,总文件 ≤500MB,建议 ≤10000 行

使用方式:
  1. 修改下方 TASKS 列表
  2. 运行: python generate_batch_jsonl.py
  3. 输出: batch_input.jsonl
"""
import json

# ═══════════════════════════════════════════════════════
# 配置区:修改以下内容来生成您需要的 JSONL
# ═══════════════════════════════════════════════════════

MODEL = "qwen-max"          # 选择模型(参见上方“适用范围”)
ENABLE_THINKING = False     # 是否开启思考模式(仅部分模型支持)
THINKING_BUDGET = 50        # 思考 token 预算(思考模式下生效)

# 任务列表:每个 dict 代表一条用户消息
TASKS = [
    {"role": "user", "content": "你好!请介绍一下自己。"},
    {"role": "user", "content": "What is 2+2?"},
    {"role": "user", "content": "请用Python写一个快速排序算法"},
]

# ═══════════════════════════════════════════════════════
# 以下为生成逻辑,一般无需修改
# ═══════════════════════════════════════════════════════

def build_request(custom_id: str, model: str, messages: list,
                  enable_thinking: bool = False, thinking_budget: int = 50) -> dict:
    """构造单条 Batch 请求"""
    body = {"model": model, "messages": messages}
    if enable_thinking:
        body["enable_thinking"] = True
        body["thinking_budget"] = thinking_budget
        body["stream"] = True  # 思考模式需开启 stream
    return {
        "custom_id": custom_id,
        "method": "POST",
        "url": "/v1/chat/completions",
        "body": body
    }

def main():
    output_file = "batch_input.jsonl"
    with open(output_file, "w", encoding="utf-8") as f:
        for i, task in enumerate(TASKS, 1):
            messages = [
                {"role": "system", "content": "You are a helpful assistant."},
                task
            ]
            req = build_request(
                custom_id=f"request-{i}",
                model=MODEL,
                messages=messages,
                enable_thinking=ENABLE_THINKING,
                thinking_budget=THINKING_BUDGET
            )
            f.write(json.dumps(req, ensure_ascii=False) + "\n")
    print(f"已生成 {output_file},共 {len(TASKS)} 条请求")

if __name__ == "__main__":
    main()

Formato de solicitação para modelos multimodais

Para modelos multimodais, o campo content está em formato de array, contendo objetos de mídia e prompts de texto. As URLs de mídia em cada linha de solicitação devem ser do mesmo tipo (imagem, vídeo ou áudio). Substitua TASKS no script acima pelo seguinte formato:
# 多模态模型配置示例

# 多模态任务:content 为数组格式
TASKS = [
    {"role": "user", "content": [
        {"type": "image_url", "image_url": {"url": "https://example.com/image1.jpg"}},
        {"type": "image_url", "image_url": {"url": "https://example.com/image2.jpg"}},
        {"type": "text", "text": "这些图描绘了什么内容?"}
    ]},
]

# {"type": "input_audio", "input_audio": {"data": "https://example.com/audio.wav", "format": "wav"}}
# {"type": "video_url", "video_url": "https://example.com/video.mp4"}

# 注意:
# - 其他多模态模型包含 system 角色,thinking_budget 设置为 50
# - 思考模式需额外设置 ENABLE_THINKING = True

Formato de solicitação para modelos de embedding de texto

Os modelos de embedding de texto usam a API /v1/embeddings, e seu formato de solicitação é diferente do formato dos modelos de geração de texto. Você pode usar o script independente a seguir para gerá-lo:
#!/usr/bin/env python3
"""文本向量模型 Batch JSONL 生成(使用 /v1/embeddings 接口)"""
import json

MODEL = "text-embedding-v3"  # 向量模型,可选型号参见上方“适用范围”

TEXTS = [
    "衣服的质量杠杠的,很漂亮,不枉我等了这么久啊,喜欢,以后还来这里买。",
    "风急天高猿啸哀",
    "The quick brown fox jumps over the lazy dog",
]

output_file = "batch_embedding.jsonl"
with open(output_file, "w", encoding="utf-8") as f:
    for i, text in enumerate(TEXTS, 1):
        req = {
            "custom_id": f"emb-{i}",
            "method": "POST",
            "url": "/v1/embeddings",
            "body": {"model": MODEL, "input": text, "encoding_format": "float"}
        }
        f.write(json.dumps(req, ensure_ascii=False) + "\n")
print(f"已生成 {output_file},共 {len(TEXTS)} 条请求")

1. Modifique o arquivo de entrada

  • Você pode modificar diretamente o arquivo test_model.jsonl usado para teste, definir o parâmetro model como o modelo formal de destino e configurar o campo URL:

    Tipo de modelo

    url

    Modelos de geração de texto/multimodais

    /v1/chat/completions

    Modelos de embedding de texto

    /v1/embeddings

  • Como alternativa, use a "ferramenta de geração de JSONL em lote" acima para gerar um novo arquivo para a tarefa formal. O essencial é garantir que os campos model e url estejam corretos.

2. Modifique o código do Início rápido

  1. Altere o caminho do arquivo de entrada para o nome do seu arquivo
  2. Altere o valor do parâmetro endpoint para o valor consistente com o campo url no arquivo de entrada

3. Execute o código e aguarde os resultados

Após a conclusão da tarefa, os resultados das solicitações bem-sucedidas são salvos no arquivo local result.jsonl. Se alguma solicitação falhar, os detalhes do erro serão salvos no arquivo error.jsonl.
  • Resultados bem-sucedidos (output_file_id): cada linha corresponde a uma solicitação original bem-sucedida, contendo custom_id e response.
{"id":"3a5c39d5-3981-4e4c-97f2-e0e821893f03","custom_id":"req-001","response":{"status_code":200,"request_id":"3a5c39d5-3981-4e4c-97f2-e0e821893f03","body":{"created":1768306034,"usage":{"completion_tokens":654,"prompt_tokens":14,"total_tokens":668},"model":"qwen-plus","id":"chatcmpl-3a5c39d5-3981-4e4c-97f2-e0e821893f03","choices":[{"finish_reason":"stop","index":0,"message":{"role":"assistant","content":"你好!杭州西湖是中国著名的风景名胜区,位于浙江省杭州市西部,因此得名“西湖”。它是中国十大风景名胜之一,也是世界文化遗产(2011年被联合国教科文组织列入《世界遗产名录》),以其秀丽的自然风光与深厚的人文底蕴闻名于世。\n\n### 一、自然景观\n西湖三面环山,一面邻城,湖面面积约6.39平方公里,形似如意,碧波荡漾。湖中被孤山、白堤、苏堤、杨公堤等自然或人工分隔成多个水域,形成“一山二塔三岛三堤”的格局。\n\n主要景点包括:\n- **苏堤春晓**:北宋大文豪苏东坡任杭州知州时主持疏浚西湖,用挖出的淤泥堆筑成堤,后人称为“苏堤”。春天桃红柳绿,景色如画。\n- **断桥残雪**:位于白堤东端,是白蛇传中“断桥相会”的发生地,冬日雪后银装素裹,尤为著名。\n- **雷峰夕照**:雷峰塔在夕阳映照下金光熠熠,曾是“西湖十景”之一。\n- **三潭印月**:湖中小瀛洲上的三座石塔,中秋夜可在塔内点灯,月影、灯光、湖光交相辉映。\n- **平湖秋月**:位于白堤西端,是观赏湖上明月的绝佳地点。\n- **花港观鱼**:以赏花和观鱼著称,园内牡丹、锦鲤相映成趣。\n\n### 二、人文历史\n西湖不仅风景优美,还承载着丰富的历史文化:\n- 自唐宋以来,众多文人墨客如白居易、苏东坡、林逋、杨万里等在此留下诗篇。\n- 白居易曾主持修建“白堤”,疏浚西湖,造福百姓。\n- 西湖周边有众多古迹,如岳王庙(纪念民族英雄岳飞)、灵隐寺(千年古刹)、六和塔、龙井村(中国十大名茶龙井茶的产地)等。\n\n### 三、文化象征\n西湖被誉为“人间天堂”的代表,是中国传统山水美学的典范。它融合了自然美与人文美,体现了“天人合一”的哲学思想。许多诗词、绘画、戏曲都以西湖为题材,成为中国文化的重要符号。\n\n### 四、旅游建议\n- 最佳游览季节:春季(3-5月)桃红柳绿,秋季(9-11月)天高气爽。\n- 推荐方式:步行、骑行(环湖绿道)、乘船游湖。\n- 周边美食:西湖醋鱼、龙井虾仁、东坡肉、片儿川等。\n\n总之,杭州西湖不仅是一处自然美景,更是一座活着的文化博物馆,值得细细品味。如果你有机会到杭州,一定不要错过这个“淡妆浓抹总相宜”的人间仙境。"}}],"object":"chat.completion"}},"error":null}
{"id":"628312ba-172c-457d-ba7f-3e5462cc6899","custom_id":"req-002","response":{"status_code":200,"request_id":"628312ba-172c-457d-ba7f-3e5462cc6899","body":{"created":1768306035,"usage":{"completion_tokens":25,"prompt_tokens":18,"total_tokens":43},"model":"qwen-plus","id":"chatcmpl-628312ba-172c-457d-ba7f-3e5462cc6899","choices":[{"finish_reason":"stop","index":0,"message":{"role":"assistant","content":"春风拂柳绿,  \n夜雨润花红。  \n鸟语林间闹,  \n山川处处同。"}}],"object":"chat.completion"}},"error":null}
  • Detalhes das solicitações com falha (error_file_id): contêm as informações das linhas de solicitação que falharam ao ser processadas e as causas do erro. Consulte Códigos de erro para solução de problemas.

Processo detalhado

O fluxo de trabalho da Batch API consiste em quatro etapas: upload de arquivos, criação de tarefas, consulta do status da tarefa e download dos resultados.
Antes de criar uma tarefa em lote, faça o upload de um arquivo JSONL que atenda aos requisitos de formato por meio da API de upload de arquivos para obter o file_id.
Ao fazer o upload de um arquivo, purpose deve ser batch.
Reutilizar um ID de arquivo existente: O ID retornado após o upload do arquivo (como file-batch-xxx) pode ser reutilizado. Se o conteúdo de entrada não for alterado, não é necessário fazer o upload novamente a cada vez; você pode criar diretamente uma tarefa com o ID existente:
batch = client.batches.create(
    input_file_id="file-batch-xxx",  # 直接使用已有文件 ID,无需重新上传
    endpoint="/v1/chat/completions",
    completion_window="24h"
)
É possível consultar os IDs de arquivos Batch enviados por meio da API client.files.list(purpose="batch").
  • OpenAI Python SDK
  • OpenAI Node.js SDK
  • Java(HTTP)
  • curl(HTTP)

Exemplo de requisição

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
    # 新加坡和北京地域的API Key不同。
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下是新加坡地域base_url,如果使用北京地域的模型,需要将base_url替换为:https://dashscope.aliyuncs.com/compatible-mode/v1
    # 注意:切换地域时,API Key也需要对应更换
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

# test.jsonl 是一个本地示例文件,purpose必须是batch
file_object = client.files.create(file=Path("test.jsonl"), purpose="batch")

print(file_object.model_dump_json())

Exemplo de resposta

{
    "id": "file-batch-xxx",
    "bytes": 437,
    "created_at": 1742304153,
    "filename": "test.jsonl",
    "object": "file",
    "purpose": "batch",
    "status": "processed",
    "status_details": null
}
Use o ID do arquivo retornado pelo upload de arquivos para criar uma tarefa em lote.
  • OpenAI Python SDK
  • OpenAI Node.js SDK
  • Java(HTTP)
  • curl(HTTP)

Exemplo de requisição

import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
    # 新加坡和北京地域的API Key不同。
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下是新加坡地域base_url,如果使用北京地域的模型,需要将base_url替换为:https://dashscope.aliyuncs.com/compatible-mode/v1
    # 注意:切换地域时,API Key也需要对应更换
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

batch = client.batches.create(
    input_file_id="file-batch-xxx",  # 上传文件返回的id
    endpoint="/v1/chat/completions",  # # 测试模型batch-test-model填写/v1/chat/ds-test,文本向量模型填写/v1/embeddings,文本生成/多模态模型填写/v1/chat/completions
    completion_window="24h",
    metadata={'ds_name':"任务名称",'ds_description':'任务描述'} # metadata数据,非必填字段,用于创建任务名称、描述
)
print(batch)

Parâmetros de entrada

Campo

Tipo

Método de passagem

do parâmetro

Obrigatório

Descrição

input_file_id

String

Body

Sim

Especifica o ID do arquivo usado como arquivo de entrada para a tarefa em lote.

Use o ID do arquivo retornado pela interface Preparar e enviar arquivos, como file-batch-xxx.

endpoint

String

Body

Sim

O caminho de acesso, que deve corresponder ao campo URL no arquivo de entrada.

  • Para o modelo de teste batch-test-model, insira /v1/chat/ds-test

  • Para outros modelos, insira /v1/chat/completions

completion_window

String

Body

Sim

O tempo de espera, mínimo de 24h e máximo de 336h; apenas números inteiros são aceitos.

Aceita duas unidades: "h" e "d", como "24h" ou "14d".

metadata

Map

Body

Não

Metadados de extensão da tarefa para anexar informações adicionais como pares chave-valor.

metadata.ds_name

String

Body

Não

Nome da tarefa.

Exemplo: "ds_name": "Batch task"

Limite: até 100 caracteres.

Se este campo for definido repetidamente, o último valor passado prevalece.

metadata.ds_description

String

Body

Não

Descrição da tarefa.

Exemplo: "ds_description": "Batch inference task test"

Limite: até 200 caracteres.

Se este campo for definido repetidamente, o último valor passado prevalece.

Exemplo de resposta

{
    "id": "batch_xxx",
    "object": "batch",
    "endpoint": "/v1/chat/completions",
    "errors": null,
    "input_file_id": "file-batch-xxx",
    "completion_window": "24h",
    "status": "validating",
    "output_file_id": null,
    "error_file_id": null,
    "created_at": 1742367779,
    "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": {
        "ds_name": "任务名称",
        "ds_description": "任务描述"
    }
}

Parâmetros da resposta

Campo

Tipo

Descrição

id

String

O ID da tarefa em lote criada desta vez.

object

String

O tipo de objeto, com valor fixo batch.

endpoint

String

O caminho de acesso.

errors

Map

A mensagem de erro.

input_file_id

String

O ID do arquivo.

completion_window

String

O tempo de espera. O tempo mínimo de espera é 24h e o máximo é 336h; apenas números inteiros são aceitos.

Aceita duas unidades: "h" e "d", como "24h" ou "14d".

status

String

O status da tarefa. Valores possíveis: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled.

output_file_id

String

O ID do arquivo de saída para solicitações bem-sucedidas.

error_file_id

String

O ID do arquivo de erro para solicitações com falha.

created_at

Integer

Timestamp Unix (em segundos) de criação da tarefa.

in_progress_at

Integer

Timestamp Unix (em segundos) em que a tarefa começou a ser executada.

expires_at

Integer

Timestamp Unix (em segundos) previsto para a expiração da tarefa.

finalizing_at

Integer

Timestamp Unix (em segundos) em que a tarefa começou a agregar os resultados.

completed_at

Integer

Timestamp Unix (em segundos) de conclusão da tarefa.

failed_at

Integer

Timestamp Unix (em segundos) da falha da tarefa.

expired_at

Integer

Timestamp Unix (em segundos) de expiração da tarefa.

cancelling_at

Integer

Timestamp Unix (em segundos) em que o cancelamento da tarefa foi iniciado.

cancelled_at

Integer

Timestamp Unix (em segundos) da conclusão do cancelamento da tarefa.

request_counts

Map

Estatísticas de contagem de solicitações por status.

metadata

Map

Metadados adicionais em pares chave-valor.

metadata.ds_name

String

Nome da tarefa.

metadata.ds_description

String

Descrição da tarefa.

Após a criação de uma tarefa, você pode usar as seguintes operações de API para consultar seu status, listar tarefas históricas ou cancelar tarefas em andamento.
Informe um ID de tarefa em lote para consultar os detalhes de uma tarefa específica. Atualmente, apenas tarefas em lote criadas nos últimos 30 dias podem ser consultadas.
  • OpenAI Python SDK
  • OpenAI Node.js SDK
  • Java(HTTP)
  • curl(HTTP)

Exemplo de requisição

import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
    # 新加坡和北京地域的API Key不同。
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下是新加坡地域base_url,如果使用北京地域的模型,需要将base_url替换为:https://dashscope.aliyuncs.com/compatible-mode/v1
    # 注意:切换地域时,API Key也需要对应更换
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
batch = client.batches.retrieve("batch_id")  # 将batch_id替换为Batch任务的id
print(batch)

Exemplo de resposta

Após uma consulta bem-sucedida, os detalhes da tarefa em lote são retornados. A seguir, um exemplo de resposta para uma tarefa no estado concluído:
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "completed",
  "output_file_id": "file-batch_output-xyz789",
  "error_file_id": "file-batch_error-xyz789",
  "created_at": 1711402400,
  "in_progress_at": 1711402450,
  "expires_at": 1711488800,
  "finalizing_at": 1711405000,
  "completed_at": 1711406000,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 95,
    "failed": 5
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job"
  }
}
O objeto JSON retornado contém as informações completas da tarefa em lote, incluindo o status da tarefa, o ID do arquivo de saída, as estatísticas de solicitações e mais. Consulte a tabela abaixo para obter as descrições dos campos.

Campo

Tipo

Descrição

id

String

ID da tarefa em lote.

status

String

Status da tarefa. Os valores possíveis incluem:

  • validating: O arquivo de entrada está sendo validado

  • in_progress: A tarefa está sendo processada

  • finalizing: O processamento foi concluído e o arquivo de saída está sendo gerado

  • completed: A tarefa foi concluída com sucesso

  • failed: A tarefa falhou devido a um erro crítico

  • expired: A tarefa expirou porque não foi concluída dentro do completion_window

  • cancelling: A tarefa está sendo cancelada

  • cancelled: A tarefa foi cancelada

output_file_id

String

O ID do arquivo de resultados de sucesso, gerado após a conclusão da tarefa.

error_file_id

String

O ID do arquivo de resultados de falha, gerado quando a tarefa é concluída e há solicitações com falha.

request_counts

Object

O objeto de estatísticas de contagem de solicitações, contendo os campos total, completed e failed.

Você pode usar o método batches.list() para consultar a lista de tarefas em lote e recuperar a lista completa de tarefas progressivamente por meio de paginação.
  • OpenAI Python SDK
  • OpenAI Node.js SDK
  • Java(HTTP)
  • curl(HTTP)

Exemplo de requisição

import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
    # 新加坡和北京地域的API Key不同。
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下是新加坡地域base_url,如果使用北京地域的模型,需要将base_url替换为:https://dashscope.aliyuncs.com/compatible-mode/v1
    # 注意:切换地域时,API Key也需要对应更换
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
batches = client.batches.list(after="batch_xxx", limit=2,extra_query={'ds_name':'任务名称','input_file_ids':'file-batch-xxx,file-batch-xxx','status':'completed,expired','create_after':'20250304000000','create_before':'20250306123000'})
print(batches)

Parâmetros de entrada

Campo

Tipo

Método de passagem

Obrigatório

Descrição

after

String

Query

Não

O cursor usado para paginação, cujo valor é o ID da última tarefa da página anterior.

limit

Integer

Query

Não

O número de tarefas retornadas por página, intervalo [1, 100], padrão 20.

ds_name

String

Query

Não

Correspondência difusa por nome da tarefa.

input_file_ids

String

Query

Não

Filtro por ID de arquivo. Vários IDs são separados por vírgulas, até 20.

status

String

Query

Não

Filtro por status da tarefa. Vários status são separados por vírgulas.

create_after

String

Query

Não

Filtra tarefas criadas após este ponto no tempo, no formato yyyyMMddHHmmss.

create_before

String

Query

Não

Filtra tarefas criadas antes deste ponto no tempo, no formato yyyyMMddHHmmss.

Exemplo de resposta

{
  "object": "list",
  "data": [
    {
      "id": "batch_xxx",
      "object": "batch",
      "endpoint": "/v1/chat/completions",
      "errors": null,
      "input_file_id": "file-batch-xxx",
      "completion_window": "24h",
      "status": "completed",
      "output_file_id": "file-batch_output-xxx",
      "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_xxx",
  "last_id": "batch_xxx",
  "has_more": true
}

Parâmetros da resposta

Campo

Tipo

Descrição

object

String

O tipo, com valor fixo list.

data

Array

O objeto de tarefa em lote. Consulte os parâmetros de resposta da criação de uma tarefa em lote.

first_id

String

O ID da primeira tarefa em lote da página atual.

last_id

String

O ID da última tarefa em lote da página atual.

has_more

Boolean

Indica se há uma próxima página.

Cancele uma tarefa em andamento ou na fila. Após uma chamada bem-sucedida, o status da tarefa muda para cancelling e, eventualmente, para cancelled. Antes que a tarefa seja totalmente cancelada, a parte concluída ainda é cobrada.
  • OpenAI Python SDK
  • OpenAI Node.js SDK
  • Java(HTTP)
  • curl(HTTP)

Exemplo de requisição

import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
    # 新加坡和北京地域的API Key不同。
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下是新加坡地域base_url,如果使用北京地域的模型,需要将base_url替换为:https://dashscope.aliyuncs.com/compatible-mode/v1
    # 注意:切换地域时,API Key也需要对应更换
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
batch = client.batches.cancel("batch_id")  # 将batch_id替换为Batch任务的id
print(batch)

Exemplo de resposta

Após o cancelamento bem-sucedido da tarefa, os detalhes da tarefa em lote são retornados. A seguir, um exemplo de resposta no estado cancelling:
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "cancelling",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1711402400,
  "in_progress_at": 1711402450,
  "expires_at": 1711488800,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": 1711403000,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 23,
    "failed": 1
  },
  "metadata": null
}
Após cancelar a tarefa, o status muda primeiro para cancelling, aguardando a conclusão das solicitações em andamento; eventualmente muda para cancelled. Os resultados das solicitações concluídas ainda são salvos no arquivo de saída.
Após a conclusão da tarefa, um arquivo de resultados (output_file_id) e possivelmente um arquivo de erros (error_file_id) são gerados; ambos são obtidos por meio da mesma API de download de arquivos.Somente o arquivo correspondente ao file_id que começa com file-batch_output pode ser baixado.
  • OpenAI Python SDK
  • OpenAI Node.js SDK
  • Java(HTTP)
  • curl(HTTP)
Você pode usar o método content para recuperar o conteúdo do arquivo de resultados do lote e o método write_to_file para salvá-lo localmente.

Exemplo de requisição

import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
    # 新加坡和北京地域的API Key不同。
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下是新加坡地域base_url,如果使用北京地域的模型,需要将base_url替换为:https://dashscope.aliyuncs.com/compatible-mode/v1
    # 注意:切换地域时,API Key也需要对应更换
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
content = client.files.content(file_id="file-batch_output-xxx")
# 打印结果文件内容
print(content.text)
# 保存结果文件至本地
content.write_to_file("result.jsonl")

Exemplo de resposta

{"id":"c308ef7f-xxx","custom_id":"1","response":{"status_code":200,"request_id":"c308ef7f-0824-9c46-96eb-73566f062426","body":{"created":1742303743,"usage":{"completion_tokens":35,"prompt_tokens":26,"total_tokens":61},"model":"qwen-plus","id":"chatcmpl-c308ef7f-0824-9c46-96eb-73566f062426","choices":[{"finish_reason":"stop","index":0,"message":{"content":"你好!当然可以。无论是需要信息查询、学习资料、解决问题的方法,还是其他任何帮助,我都在这里为你提供支持。请告诉我你需要什么方面的帮助?"}}],"object":"chat.completion"}},"error":null}
{"id":"73291560-xxx","custom_id":"2","response":{"status_code":200,"request_id":"73291560-7616-97bf-87f2-7d747bbe84fd","body":{"created":1742303743,"usage":{"completion_tokens":7,"prompt_tokens":26,"total_tokens":33},"model":"qwen-plus","id":"chatcmpl-73291560-7616-97bf-87f2-7d747bbe84fd","choices":[{"finish_reason":"stop","index":0,"message":{"content":"2+2 equals 4."}}],"object":"chat.completion"}},"error":null}

Exemplo de resposta

Resultado de uma única resposta:
{
    "id": "c308ef7f-xxx",
    "custom_id": "1",
    "response": {
        "status_code": 200,
        "request_id": "c308ef7f-0824-9c46-96eb-73566f062426",
        "body": {
            "created": 1742303743,
            "usage": {
                "completion_tokens": 35,
                "prompt_tokens": 26,
                "total_tokens": 61
            },
            "model": "qwen-plus",
            "id": "chatcmpl-c308ef7f-0824-9c46-96eb-73566f062426",
            "choices": [
                {
                    "finish_reason": "stop",
                    "index": 0,
                    "message": {
                        "content": "你好!当然可以。无论是需要信息查询、学习资料、解决问题的方法,还是其他任何帮助,我都在这里为你提供支持。请告诉我你需要什么方面的帮助?"
                    }
                }
            ],
            "object": "chat.completion"
        }
    },
    "error": null
}

Parâmetros da resposta

Campo

Tipo

Descrição

id

String

ID da solicitação.

custom_id

String

ID definido pelo usuário.

response

Object

Resultado da solicitação.

status_code

Integer

Código de status. 200 indica uma solicitação bem-sucedida.

request_id

String

O ID exclusivo gerado pelo servidor para esta solicitação.

completion_tokens

Integer

O número de tokens consumidos pelo conteúdo de resposta gerado pelo modelo (completion).

prompt_tokens

Integer

O número de tokens consumidos pelo conteúdo de entrada (prompt) enviado ao modelo.

total_tokens

Integer

O número total de tokens consumidos por esta chamada.

model

String

O nome do modelo usado por esta chamada.

error

Object

O objeto de mensagem de erro. Se a chamada de API for bem-sucedida, este valor é null. Se ocorrer um erro, ele contém o código de erro e a mensagem de erro detalhada.

error.code

String

Informações da linha de erro e causas do erro. Consulte códigos de erro para solução de problemas.

error.message

String

A mensagem de erro.

Recursos avançados

Configurar notificações de conclusão de tarefa

A consulta contínua (polling) de tarefas de longa duração consome recursos desnecessários. Recomendamos configurar notificações assíncronas para que o sistema o notifique proativamente quando uma tarefa for concluída.
O recurso de notificação de conclusão de tarefa é suportado apenas na região de Pequim.
  • Callback: Especifique uma URL publicamente acessível ao criar uma tarefa
  • Fila de mensagens do EventBridge: Profundamente integrada ao ecossistema do Alibaba Cloud, sem necessidade de IP público
Especifique uma URL publicamente acessível por meio de metadata ao criar uma tarefa. Após a conclusão da tarefa, o sistema envia uma solicitação POST contendo o status da tarefa para essa URL:
  • OpenAI Python SDK
  • curl(HTTP)
import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,可用阿里云百炼API Key将下行替换为:api_key="sk-xxx"。但不建议在生产环境中直接将API Key硬编码到代码中,以减少API Key泄露风险。
    # 新加坡和北京地域的API Key不同。
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下是北京地域base_url,如果使用新加坡地域的模型,需要将base_url替换为:https://dashscope-intl.aliyuncs.com/compatible-mode/v1
    # 注意:切换地域时,API Key也需要对应更换
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

batch = client.batches.create(
    input_file_id="file-batch-xxx",  # 上传文件返回的 id
    endpoint="/v1/chat/completions",  # Embedding文本向量模型填写"/v1/embeddings",测试模型batch-test-model填写/v1/chat/ds-test,其他模型填写/v1/chat/completions
    completion_window="24h",
    metadata={
            "ds_batch_finish_callback": "https://xxx/xxx"
          }
)
print(batch)
Este método não requer IP público e é adequado para cenários em que você integra com outros serviços do Alibaba Cloud (como Function Compute e RocketMQ).Quando uma tarefa em lote é concluída, o sistema envia um evento para o Alibaba Cloud EventBridge. Você pode configurar regras do EventBridge para escutar esse evento e encaminhá-lo para um destino especificado.
  • Origem: acs.dashscope
  • Tipo: dashscope:System:BatchTaskFinish
Documentação relacionada: Encaminhamento para o Message Queue for Apache RocketMQ.

Entrando em produção

  • Gerenciamento de arquivos
    • Chame periodicamente a API de exclusão de arquivos do OpenAI-File para excluir arquivos desnecessários e evitar atingir o limite de armazenamento de arquivos (10.000 arquivos ou 100 GB)
    • Para arquivos grandes, recomendamos armazená-los no Alibaba Cloud OSS
  • Monitoramento de tarefas
    • Prefira notificações assíncronas por Callback ou EventBridge
    • Use um intervalo de consulta > 1 minuto com uma estratégia de backoff exponencial
  • Tratamento de erros
    • Implemente um mecanismo completo de tratamento de exceções cobrindo erros de rede, erros de API e mais
    • Baixe e analise os detalhes dos erros em error_file_id
    • Para códigos de erro comuns, consulte códigos de erro para resolvê-los
  • Otimização de custos
    • Combine tarefas pequenas em um único lote
    • Defina o completion_window adequadamente para fornecer mais flexibilidade de agendamento

Utilitários

Quando seus dados brutos estão armazenados em um arquivo CSV (primeira coluna como ID, segunda coluna como conteúdo), você pode usar o script a seguir para gerar rapidamente o arquivo JSONL necessário para tarefas em lote.
Para alterar o caminho do arquivo ou outros parâmetros, modifique o código conforme necessário.
import csv
import json
def messages_builder_example(content):
    messages = [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": content}]
    return messages

with open("input_demo.csv", "r") as fin:
    with open("input_demo.jsonl", 'w', encoding='utf-8') as fout:
        csvreader = csv.reader(fin)
        for row in csvreader:
"messages": messages_builder_example(row[1])}
            # 选择Embedding文本向量模型进行调用时,url的值需填写"/v1/embeddings",其他模型填写/v1/chat/completions
            request = {"custom_id": row[0], "method": "POST", "url": "/v1/chat/completions", "body": body}
            fout.write(json.dumps(request, separators=(',', ':'), ensure_ascii=False) + "\n")
Use o script a seguir para analisar o arquivo result.jsonl em um arquivo result.csv fácil de analisar no Excel.
Para alterar o caminho do arquivo ou outros parâmetros, modifique o código conforme necessário.
import json
import csv
columns = ["custom_id",
           "model",
           "request_id",
           "status_code",
           "error_code",
           "error_message",
           "created",
           "content",
           "usage"]

def dict_get_string(dict_obj, path):
    obj = dict_obj
    try:
        for element in path:
            obj = obj[element]
        return obj
    except:
        return None

with open("result.jsonl", "r") as fin:
    with open("result.csv", 'w', encoding='utf-8') as fout:
        rows = [columns]
        for line in fin:
            request_result = json.loads(line)
            row = [dict_get_string(request_result, ["custom_id"]),
                   dict_get_string(request_result, ["response", "body", "model"]),
                   dict_get_string(request_result, ["response", "request_id"]),
                   dict_get_string(request_result, ["response", "status_code"]),
                   dict_get_string(request_result, ["error", "error_code"]),
                   dict_get_string(request_result, ["error", "error_message"]),
                   dict_get_string(request_result, ["response", "body", "created"]),
                   dict_get_string(request_result, ["response", "body", "choices", 0, "message", "content"]),
                   dict_get_string(request_result, ["response", "body", "usage"])]
            rows.append(row)
        writer = csv.writer(fout)
        writer.writerows(rows)
Corrigindo caracteres corrompidos no Excel
  • Use um editor de texto (como o Sublime) para converter a codificação do arquivo CSV para GBK e, em seguida, abra-o no Excel.
  • Ou crie um novo arquivo no Excel e especifique o formato de codificação correto (UTF-8) ao importar os dados.

Limites de taxa da API

API

Limite de taxa (nível da conta principal)

Criar tarefa

1000 vezes/minuto, até 1000 tarefas simultâneas

Consultar tarefa

1000 vezes/minuto

Consultar a lista de tarefas

100 vezes/minuto

Cancelar tarefa

1000 vezes/minuto

Detalhes de cobrança

  • Preço unitário: Para todas as solicitações bem-sucedidas, o preço unitário dos tokens de entrada e de saída é 50% do preço de inferência em tempo real do modelo correspondente. Para mais informações, consulte Modelos.
  • Escopo da cobrança:
    • Somente as solicitações executadas com sucesso são cobradas.
    • Falhas na análise de arquivos, falhas na execução de tarefas e solicitações com erro em nível de linha não geram custos.
    • Para tarefas canceladas, as solicitações concluídas com sucesso antes do cancelamento ainda são cobradas normalmente.
  • A inferência em lote é um item de cobrança separado. Ela suporta o plano de economia universal de IA, mas não suporta descontos de pagamento antecipado (plano de economia) ou cota gratuita para novos usuários, nem recursos como cache de contexto.
  • Alguns modelos (como qwen3.5-plus e qwen3.5-flash) têm o modo de raciocínio ativado por padrão, o que gera tokens de raciocínio adicionais cobrados pelo preço do token de saída e aumenta os custos. Recomendamos definir o parâmetro enable_thinking com base na complexidade da tarefa para controlar os custos. Para mais informações, consulte raciocínio profundo.

Códigos de erro

Se uma chamada falhar, consulte códigos de erro para solução de problemas.

Perguntas frequentes

  1. Como escolher entre Batch Chat e Batch File? Escolha Batch File ao processar um único arquivo grande que contém um grande número de solicitações e recuperar os resultados de forma assíncrona. Escolha Batch Chat quando precisar enviar um grande número de solicitações de conversa independentes com alta concorrência por meio de chamadas de API síncronas.
  2. Como o uso do Batch File é cobrado? Preciso adquiri-lo separadamente? O Batch é um método de chamada que usa um modelo de pagamento por uso e é cobrado com base no uso de tokens das solicitações bem-sucedidas, portanto não é necessário adquirir pacotes adicionais.
  3. Os arquivos Batch enviados são executados em ordem? Não. O sistema usa um mecanismo de agendamento dinâmico para organizar a execução das tarefas com base na carga de recursos de computação e não garante estrita aderência à ordem de envio. Quando os recursos estão escassos, a inicialização e a execução das tarefas podem ser atrasadas.
  4. Quanto tempo leva para um arquivo Batch enviado ser concluído? O tempo de execução depende da alocação de recursos do sistema e da escala da tarefa. Se uma tarefa não for concluída dentro do completion_window especificado, seu status muda para expired, e as solicitações não processadas não são mais executadas e não geram custos. Recomendações de cenário: Para cenários com requisitos rígidos de tempo, recomendamos usar chamadas em tempo real. Para cenários de processamento de dados em grande escala com alguma tolerância à latência, recomendamos usar chamadas em lote.