Skip to main content

Inferência em lote

Para cenários de inferência que não exigem respostas em tempo real, a inferência em lote pode processar de forma assíncrona grandes volumes de solicitações de dados por apenas 50% do custo da inferência em tempo real, com uma API compatível com OpenAI. É ideal para trabalhos em lote, como avaliação de modelos e rotulagem de dados.

Como funciona

  1. Envie a tarefa: faça o upload de um arquivo JSONL contendo várias solicitações para criar uma tarefa de inferência em lote.
  2. Processamento assíncrono: o sistema processa a tarefa em uma fila em segundo plano. Você pode consultar o progresso e o status da tarefa por meio do console ou da API.
  3. Baixe os resultados: após a conclusão da tarefa, o sistema gera um arquivo de resultados (registrando as respostas bem-sucedidas) e um arquivo de erros (registrando os detalhes das falhas, se houver).

Escopo aplicável

  • 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 256K tokens de contexto por solicitação. qwen3.5-omni-plus e qwen3.5-omni-flash não suportam saída de voz.
  • Alguns modelos suportam o modo de raciocínio. Ativá-lo gera 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 modelos 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; ele não pode ser colocado dentro de extra_body.
  • Os arquivos de resultados da inferência em lote não contêm o campo reasoning_content. Mesmo que enable_thinking=true seja definido, choices[0].message no arquivo de resultados contém apenas os campos content e role. Para obter o conteúdo do processo de raciocínio, use chamadas de API em tempo real (com ou sem streaming; basta definir enable_thinking=true). Para mais informações, consulte Raciocínio profundo.

Usar inferência em lote

Etapa 1: Preparar o arquivo de entrada

Antes de criar uma tarefa, prepare um arquivo JSONL em conformidade com as seguintes especificações:
  • Formato: JSONL codificado em UTF-8 (um objeto JSON independente por linha).
  • Limites de tamanho: Até 50.000 solicitações e 500 MB por arquivo.
    Se o volume de dados exceder esses limites, divida-o em várias tarefas e envie-as separadamente.
  • Limite por linha: Cada objeto JSON deve ter ≤ 1 MB e não deve exceder o comprimento de contexto do modelo.
  • Requisito de consistência: Todas as solicitações no mesmo arquivo devem usar o mesmo modelo.
  • Identificador exclusivo: Cada solicitação deve incluir um campo custom_id exclusivo no arquivo, usado para correspondência de resultados. O custom_id aceita até 256 caracteres; exceder esse limite faz com que a validação da tarefa falhe. Para transmitir informações de identificador mais longas, use um campo personalizado de metadata ao criar a tarefa. Para mais informações, consulte Usar metadata para retornar identificadores personalizados.
  • Endereços de arquivos de mídia: Os arquivos de mídia referenciados por campos como image_url e video_url no body de solicitações multimodais devem usar URLs publicamente acessíveis. Caminhos de arquivos locais (como file:///home/user/test.mp4) e endereços de rede interna não são suportados. Tarefas criadas com esses endereços podem ser enviadas com sucesso, mas nunca serão processadas até a conclusão. Faça primeiro o upload dos arquivos para um armazenamento publicamente acessível e, em seguida, referencie suas URLs.
Cada objeto JSON deve seguir as seguintes especificações de campo:

Campo

Tipo

Obrigatório

Descrição

custom_id

string

Sim

Identificador exclusivo da solicitação

method

string

Sim

Método HTTP; apenas POST é suportado

url

string

Sim

O endpoint da solicitação. Insira /v1/chat/completions para modelos de geração de texto e multimodais, e /v1/embeddings para modelos de embedding de texto

body

object

Sim

O corpo da solicitação, cujo formato é o mesmo da API correspondente ao url especificado (/v1/chat/completions ou /v1/embeddings)

Arquivo de exemplo

Você pode baixar o arquivo de exemplo test_model.jsonl, que contém:
{"custom_id":"1","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-max","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-max","messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":"What is 2+2?"}]}}
Ferramenta de geração de arquivos JSONL para inferência em lote A inferência em lote requer a construção de um arquivo JSONL em que cada linha é uma solicitação independente. O script Python a seguir pode ser executado diretamente para gerar um arquivo JSONL 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 na lista TASKS do script
  3. Execute python generate_batch_jsonl.py
  4. O arquivo batch_input.jsonl gerado pode ser usado diretamente em tarefas de inferência em lote (Batch)
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
O campo content dos modelos multimodais está em formato de matriz, contendo objetos de mídia e perguntas em 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 o formato da 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)} 条请求")

Configurar o modo de raciocínio na inferência em lote

Alguns modelos (como qwen3.7-plus, qwen3.7-max e as séries qwen3.6 e qwen3.5) têm o modo de raciocínio ativado por padrão, o que gera tokens de raciocínio adicionais. Para configurar o modo de raciocínio na inferência em lote, defina o parâmetro enable_thinking no body de cada linha de solicitação do arquivo JSONL, colocando-o no mesmo nível de model. O parâmetro opcional thinking_budget é usado para limitar o número máximo de tokens de raciocínio.
enable_thinking e thinking_budget devem ser colocados diretamente no nível superior de body (no mesmo nível de model). Não os coloque em extra_body — extra_body é um mecanismo usado pelo OpenAI Python SDK para passar parâmetros não padrão, que funciona apenas em chamadas de SDK para inferência em tempo real e não se aplica a arquivos JSONL de inferência em lote.
Exemplo: desativar o modo de raciocínio
{"custom_id":"request-1","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen3.5-plus","enable_thinking":false,"messages":[{"role":"user","content":"你好"}]}}
Exemplo: ativar o modo de raciocínio e limitar o orçamento de tokens de raciocínio
{"custom_id":"request-2","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen3.5-plus","enable_thinking":true,"thinking_budget":50,"messages":[{"role":"user","content":"请分析以下问题"}]}}

Etapa 2: Criar uma tarefa de inferência em lote

  1. Na página **Inferência em lote**, clique em Criar Lote.
  2. Na caixa de diálogo exibida: insira o Nome da Tarefa e a Descrição da Tarefa, defina o Tempo Máximo de Espera (de 1 a 14 dias) e faça o upload de um arquivo JSONL.
    Você pode clicar em Baixar Arquivo de Exemplo para obter um modelo.
  3. Após preencher o formulário, clique em Confirmar.

Etapa 3: Monitorar e gerenciar tarefas

  • Visualizar:
    • Na página de tarefas, visualize o progresso (número de solicitações processadas/total de solicitações) e o status de uma tarefa.
    • Pesquise por nome ou ID da tarefa, ou filtre por workspace para localizar rapidamente a tarefa desejada.
  • Gerenciar:
    • Cancelar: tarefas no estado "Em execução" podem ser canceladas na coluna Ações.

Etapa 4: Baixar os resultados

As tarefas são excluídas automaticamente 30 dias após a conclusão. Baixe os resultados prontamente.
Após a conclusão de uma tarefa, clique em Visualizar Resultados para baixar os arquivos de saída:
  • Arquivo de resultados: registra todas as solicitações bem-sucedidas e seus resultados de response.
  • Arquivo de erros (se houver): registra todas as solicitações com falha e seus detalhes de error.
Ambos os arquivos contêm o campo custom_id, usado para corresponder aos dados de entrada originais, associar resultados ou localizar erros.

Etapa 5: Visualizar estatísticas de uso (opcional)

Na página Monitoramento, filtre e visualize as estatísticas de uso da inferência em lote.
  • Visualizar a visão geral dos dados: selecione um período (até 30 dias), defina o Tipo de Inferência como Inferência em Lote, e você poderá visualizar:
    • Dados de Monitoramento: estatísticas resumidas de todos os modelos no período, como número total de chamadas e número total de falhas.
    • Modelos: dados detalhados de cada modelo, como total de chamadas, taxa de falhas e duração média das chamadas.
    Para visualizar dados de inferência de mais de 30 dias atrás, acesse a página Fatura.
  • Visualizar detalhes do modelo: Na lista Modelos, clique em Monitoramento na coluna Ações do modelo desejado para visualizar os detalhes das Estatísticas de Chamadas (como número de chamadas e volume de chamadas).
    image
  • Os dados de chamadas da inferência em lote são contabilizados com base no horário de término da tarefa. Para tarefas em execução, as informações de chamada só podem ser consultadas após a conclusão da tarefa.
  • Os dados de monitoramento têm um atraso de 1 a 2 horas.

Usar metadata para retornar identificadores personalizados

O custom_id aceita até 256 caracteres. Para retornar informações de identificador mais longas no arquivo de resultados, você pode usar os campos personalizados de metadata.

Campos de metadata

O metadata é um parâmetro opcional ao criar uma tarefa Batch e suporta os seguintes campos:
  • ds_name: Nome da tarefa. Uma vez definido, é exibido na coluna Nome da Tarefa do console.
  • ds_description: Descrição da tarefa. Uma vez definida, é exibida na coluna Descrição da Tarefa do console.
  • Campos personalizados: Além dos campos oficiais acima, o metadata também suporta campos personalizados arbitrários, e os valores dos campos personalizados não estão sujeitos ao limite de 256 caracteres. Ao consultar os detalhes da tarefa, todos os campos personalizados são retornados integralmente.

Exemplo de código

O exemplo a seguir mostra como retornar informações de identificador com mais de 256 caracteres por meio dos campos personalizados de metadata:
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

batch = client.batches.create(
    input_file_id="file-batch-xxxxxxxxxxxxxxxxxxxx",
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={
        "ds_name": "my_batch_task",
        "ds_description": "批量推理任务描述",
        "my_custom_field": "此字段的值可以超过256个字符,用于回传更长的标识信息..."
    }
)
print(batch)
Após a criação da tarefa, você pode chamar a API de consulta de detalhes da tarefa (GET /v1/batches/{batch_id}) para obter as informações completas de metadata, incluindo todos os campos personalizados e seu conteúdo integral.

Referência da API

Em ambientes de produção, use APIs compatíveis com OpenAI para criar e gerenciar tarefas Batch automaticamente. O fluxo de trabalho principal é o seguinte:
A inferência em lote suporta apenas chamadas de API no formato compatível com OpenAI. Ao usar o OpenAI Python SDK, defina base_url como https://dashscope.aliyuncs.com/compatible-mode/v1. O DashScope Python SDK (pacote dashscope) não fornece interfaces de inferência em lote, portanto as tarefas de inferência em lote não podem ser enviadas por meio de dashscope.BatchInference, dashscope.Batches ou métodos semelhantes.
Exemplo:
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
batch = client.batches.create(
    input_file_id=file_id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)
  1. Fazer upload do arquivo Chame POST /v1/files para fazer o upload do arquivo e registre o ID do arquivo retornado.
  2. Criar a tarefa Passe o ID do arquivo e chame POST /v1/batches para criar uma tarefa; em seguida, registre o batch_id retornado.
  3. Consultar o status Use o batch_id para consultar periodicamente GET /v1/batches/{batch_id}. Quando o status mudar para completed, registre o output_file_id e pare a consulta.
  4. Baixar os resultados Use o output_file_id para chamar GET /v1/files/{output_file_id}/content e baixar o arquivo de resultados.
Para as definições completas da API de Batch e exemplos de código, consulte Batch compatível com OpenAI (entrada de arquivo).

Ciclo de vida da tarefa

Status

Descrição

validating (Verificando)

O sistema está validando o formato do arquivo (especificação JSONL) e a validade do formato da API de cada linha de solicitação.

in_progress (Em execução)

O arquivo passou na validação, e o sistema começou a processar as solicitações de inferência linha por linha.

finalizing (Em execução)

Todas as solicitações foram processadas, e os resultados estão sendo gravados no arquivo de resultados e no arquivo de erros, respectivamente. Na lista de tarefas do console, esta etapa compartilha o rótulo de status Em execução com in_progress e não tem texto de exibição separado.

completed (Concluído)

O arquivo de resultados e o arquivo de erros foram gravados e estão prontos para download.

failed

A tarefa falhou durante a etapa de validating, geralmente devido a erros no nível do arquivo (como formato JSONL inválido ou arquivos grandes demais). Nesse estado, nenhuma solicitação de inferência é executada e nenhum arquivo de resultados é gerado.

expired

O tempo de execução da tarefa excedeu o tempo máximo de espera definido na criação, e ela foi encerrada pelo sistema. Ao criar uma nova tarefa, recomendamos definir um tempo de espera mais longo.

cancelled

O usuário cancela a tarefa, e as solicitações que ainda não começaram a ser processadas serão encerradas.

Detalhes de faturamento

  • Preço unitário de faturamento: Para todas as solicitações bem-sucedidas, o preço unitário dos tokens de entrada e saída é 50% do preço da inferência em tempo real do modelo correspondente. Para mais informações, consulte Modelos.
  • Escopo de faturamento:
    • Apenas as solicitações executadas com sucesso na tarefa são faturadas.
    • Falha na análise do arquivo, falha na execução da tarefa ou solicitações errôneas em nível de linha não geram cobranças.
    • Para tarefas canceladas, as solicitações concluídas com sucesso antes do cancelamento ainda são faturadas normalmente.
  • A inferência em lote é um item de faturamento independente. Ela suporta o Plano de Economia Universal de IA, mas não suporta descontos como pré-pagamento (savings plan) e cota gratuita para novos usuários, nem recursos como cache de contexto.
  • Alguns modelos (como qwen3.7-plus, qwen3.7-max e as séries qwen3.6 e qwen3.5) têm o modo de raciocínio ativado por padrão, o que gera tokens de raciocínio adicionais faturados pelo preço dos tokens de saída, aumentando os custos. Recomendamos definir o parâmetro enable_thinking de acordo com a complexidade da tarefa para controlar os custos. Para mais informações, consulte raciocínio profundo.

Perguntas frequentes

  1. Preciso fazer uma compra ou ativação adicional para usar a inferência em lote? Não. Você pode usá-la assim que o Alibaba Cloud Model Studio for ativado, e as taxas são deduzidas do saldo da sua conta no modelo de pagamento conforme o uso.
  2. Por que uma tarefa falha imediatamente após o envio (o status muda para failed)? Isso geralmente é causado por erros no nível do arquivo, e a tarefa não executou nenhuma solicitação de inferência. Solucione o problema na seguinte ordem:
    • Formato do arquivo: está no formato JSONL estrito, com um objeto JSON completo por linha?
    • Tamanho do arquivo: o tamanho do arquivo, o número de linhas, etc. excedem os limites? Para mais informações, consulte Preparar arquivos de entrada.
    • Consistência do modelo: verifique se o campo body.model de todas as solicitações no arquivo é exatamente o mesmo e se os modelos usados são suportados na região atual.
  3. Quanto tempo leva o processamento da tarefa? O tempo de processamento depende principalmente da carga do sistema no momento. Quando o sistema está ocupado, as tarefas podem precisar esperar em fila, mas os resultados, sejam de sucesso ou de falha, serão retornados dentro do tempo máximo de espera definido.

Códigos de erro

Se uma chamada falhar e retornar uma mensagem de erro, consulte Códigos de erro para solução de problemas.