O Alibaba Cloud Model Studio oferece uma API de Arquivo em Lote compatível com a OpenAI. Envie solicitações em massa por meio de arquivos. O sistema as processa de forma assíncrona e retorna os resultados quando todas as solicitações são concluídas ou quando o tempo máximo de espera é atingido. Os custos correspondem a apenas 50% das chamadas em tempo real. Essa abordagem é ideal para análise de dados, avaliação de modelos e outras cargas de trabalho em grande escala nas quais a latência não é crítica.
Fluxo de trabalho
Pré-requisitos
É possível chamar a API de Arquivo em Lote por meio do SDK da OpenAI (Python, Node.js) ou da API HTTP.
- Obter uma API Key: Get and configure your Model Studio API Key as an environment variable
- Instalar o SDK (opcional): Instale o OpenAI SDK caso pretenda utilizá-lo.
-
Endpoints de serviço
- China (Beijing):
https://dashscope.aliyuncs.com/compatible-mode/v1 - Singapore:
https://dashscope-intl.aliyuncs.com/compatible-mode/v1
- China (Beijing):
Escopo
- China (Beijing)
- Singapore
-
Modelos de geração de texto
- Qwen-Max: qwen3.8-max, qwen3.7-max, qwen3-max
- Qwen-Plus: qwen3.7-plus, qwen3.6-plus, qwen3.5-plus, qwen-plus, qwen-plus-latest
- Qwen-Flash: qwen3.8-flash, qwen3.7-flash, qwen3.6-flash, qwen3.5-flash, qwen-flash
- Recommended models: qwen-long, qwen-long-latest
- Modelos de terceiros: deepseek-r1, deepseek-v3.2, deepseek-v3
-
Modelos multimodais
- Image and video understanding: 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-vl-plus, qwen3-vl-flash
- Text extraction: qwen-vl-ocr, qwen-vl-ocr-latest
- Omni-modal: qwen3.5-omni-plus, qwen3.5-omni-flash
- Modelos de embedding de texto: text-embedding-v1, text-embedding-v2, text-embedding-v3, text-embedding-v4
- Singapore
- China (Beijing)
Primeiros passos
Antes de processar tarefas formais, faça testes com o batch-test-model. Esse modelo de teste ignora a inferência e retorna uma resposta de sucesso fixa, permitindo que você verifique sua cadeia de chamadas de API e o formato dos dados.
- Seu arquivo de teste deve atender aos requisitos descritos em Input file requirements. Tamanho máximo: 1 MB. Limite de linhas: 100.
- Limite de concorrência: Até 2 tarefas paralelas.
- Custo: O modelo de teste não gera taxas de inferência de modelo.
Etapa 1: Preparar o arquivo de entrada
Prepare um arquivo chamado test_model.jsonl com o seguinte conteúdo:
Etapa 2: Executar o código
Selecione o trecho de código correspondente à sua linguagem de programação. Salve-o no mesmo diretório do seu arquivo de entrada e execute-o. O código gerencia todo o fluxo de trabalho: upload, criação da tarefa, consulta de status e download dos resultados.
Para personalizar o caminho do arquivo ou outros parâmetros, modifique o código conforme necessário.
file-batch-xxx) pode ser reutilizado. Se o conteúdo de entrada permanecer o mesmo, pule o novo upload e crie diretamente uma tarefa com o ID existente:client.files.list(purpose="batch") para consultar os IDs de arquivos Batch enviados anteriormente.Código de exemplo
Código de exemplo
Etapa 3: Verificar os resultados do teste
Após a conclusão bem-sucedida da tarefa, o arquivo de resultado result.jsonl contém a resposta fixa {"content":"This is a test result."}:
Executar uma tarefa formal
Requisitos do arquivo de entrada
- Formato: JSONL codificado em UTF-8 (um objeto JSON independente por linha).
- Limites de tamanho: Máximo de 50.000 solicitações por arquivo, com limite de 500 MB.
- Limite por linha: Cada objeto JSON não deve exceder 6 MB e precisa caber na janela de contexto do modelo.
- 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 incluir um campo custom_id exclusivo dentro do arquivo. Esse campo serve para correlacionar solicitações aos respectivos resultados.
1. Modifique o arquivo de entrada
-
No arquivo
test_model.jsonl, defina o parâmetromodelcomo o modelo desejado e configure o campourl:Tipo de modelo
url
Modelos de geração de texto/multimodais
/v1/chat/completionsModelos de embedding de texto
/v1/embeddings -
Como alternativa, utilize a "JSONL batch generation tool" acima para gerar um novo arquivo destinado a tarefas formais. Verifique se os campos
modeleurlestão corretos.
2. Modifique o código de introdução
- Altere o caminho do arquivo de entrada para o nome do seu arquivo.
- Configure o parâmetro endpoint para corresponder ao campo url no seu arquivo de entrada.
3. Execute o código e aguarde os resultados
Quando a tarefa for concluída, os resultados das requisições bem-sucedidas serão salvos no arquivo local result.jsonl. Caso alguma requisição falhe, os detalhes do erro serão gravados no arquivo error.jsonl.
- Resultados bem-sucedidos (
output_file_id): Cada linha corresponde a uma requisição bem-sucedida e inclui ocustom_ide aresponse.
- Detalhes de falha (
error_file_id): Contém informações sobre requisições com falha, incluindo números de linha e motivos do erro. Consulte Error codes para solução de problemas.
Procedimento detalhado
O fluxo de trabalho da Batch API consiste em quatro etapas: upload de arquivo, criação de tarefa, consulta de status da tarefa e download dos resultados.
1. Upload de arquivo
1. Upload de arquivo
file_id.Ao fazer o upload de um arquivo, o parâmetropurposedeve serbatch.
file-batch-xxx) pode ser reutilizado. Se o conteúdo de entrada permanecer o mesmo, não é necessário fazer o upload novamente; crie diretamente uma tarefa com o ID existente:client.files.list(purpose="batch") para consultar os IDs de arquivos Batch enviados anteriormente.- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
Exemplo de requisição
Exemplo de resposta
2. Crie uma tarefa em lote
2. Crie uma tarefa em lote
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
Exemplo de requisição
Parâmetros de entrada
Campo | Tipo | Método | Obrigatório | Descrição |
|---|---|---|---|---|
input_file_id | String | Body | Sim | O ID do arquivo de entrada. Use o ID do arquivo retornado pela API Prepare and upload file, como |
endpoint | String | Body | Sim | O caminho de acesso da API. Deve corresponder ao campo url no arquivo de entrada.
|
completion_window | String | Body | Sim | Tempo máximo de espera. Intervalo: 24h-336h, apenas números inteiros. Unidades: "h" ou "d" (ex.: "24h" ou "14d"). |
metadata | Map | Body | Não | Metadados estendidos para a tarefa, especificados como pares chave-valor. |
metadata.ds_name | String | Body | Não | Nome da tarefa. Exemplo: Comprimento máximo: 100 caracteres. Se especificado várias vezes, o último valor terá efeito. |
metadata.ds_description | String | Body | Não | Descrição da tarefa. Exemplo: Comprimento máximo: 200 caracteres. Se especificado várias vezes, o último valor terá efeito. |
Instruções
- Leia o inglês para entender O QUE precisa ser comunicado
- Escreva o português brasileiro DO ZERO — esqueça a estrutura da frase em inglês
- Preserve toda a formatação markdown, blocos de código, links e imagens exatamente como estão
-
Placeholders xref (
{XREF_N}) — copie literalmente, NÃO traduza ou modifique - Aplique todas as regras específicas de idioma rigorosamente
- Aplique as regras de stopwords com tolerância zero
- Use o modo imperativo em passos numerados e listas de procedimentos
- Garanta a consistência terminológica — mesmo termo = mesma tradução em todo o documento
- Varie os inícios de frases em listas/tabelas — nenhum início repetido mais de 3 vezes
-
Retorne APENAS o documento markdown em português brasileiro, sem explicações
Exemplo de resposta
Parâmetros da resposta
Campo | Tipo | Descrição |
|---|---|---|
id | String | ID da tarefa em lote. |
object | String | Valor fixo: |
endpoint | String | Caminho de acesso à API. |
errors | Map | Informações de erro. |
input_file_id | String | ID do arquivo de entrada. |
completion_window | String | Tempo máximo de espera. Intervalo: 24h a 336h, apenas números inteiros. Unidades: "h" ou "d" (por exemplo, "24h" ou "14d"). |
status | String | Status da tarefa: validating, failed, in_progress, finalizing, completed, expired, cancelling, cancelled. |
output_file_id | String | ID do arquivo com os resultados das requisições bem-sucedidas. |
error_file_id | String | ID do arquivo com os resultados das requisições que falharam. |
created_at | Integer | Timestamp Unix (segundos) de criação da tarefa. |
in_progress_at | Integer | Timestamp Unix (segundos) de início do processamento da tarefa. |
expires_at | Integer | Timestamp Unix (segundos) em que a tarefa começa a expirar. |
finalizing_at | Integer | Timestamp Unix (segundos) da última execução da tarefa. |
completed_at | Integer | Timestamp Unix (segundos) de conclusão da tarefa. |
failed_at | Integer | Timestamp Unix (segundos) da falha na tarefa. |
expired_at | Integer | Timestamp Unix (segundos) de expiração da tarefa. |
cancelling_at | Integer | Timestamp Unix (segundos) em que a tarefa entrou no estado de cancelamento. |
cancelled_at | Integer | Timestamp Unix (segundos) do cancelamento da tarefa. |
request_counts | Map | Contagem de requisições por estado. |
metadata | Map | Metadados adicionais como pares chave-valor. |
metadata.ds_name | String | Nome da tarefa. |
metadata.ds_description | String | Descrição da tarefa. |
3. Consultar e gerenciar tarefas em lote
3. Consultar e gerenciar tarefas em lote
Consultar status de uma tarefa específica
Consultar status de uma tarefa específica
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
Exemplo de requisição
Exemplo de resposta
Uma consulta bem-sucedida retorna informações detalhadas sobre a tarefa em lote. A seguir, veja um exemplo de resposta para uma tarefa com status concluído:Campo | Tipo | Descrição |
|---|---|---|
id | String | ID da tarefa em lote. |
status | String | Status da tarefa. Valores possíveis:
|
output_file_id | String | ID do arquivo de saída contendo os resultados bem-sucedidos. Gerado após a conclusão da tarefa. |
error_file_id | String | ID do arquivo de erros contendo detalhes das requisições que falharam. Gerado após a conclusão da tarefa se houver falhas. |
request_counts | Object | Estatísticas de contagem de requisições, incluindo totais, concluídas e com falha. |
Consultar lista de tarefas
Consultar lista de tarefas
batches.list() para recuperar a lista de tarefas em lote. Use paginação para obter a lista completa de tarefas.- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
Exemplo de requisição
Parâmetros de entrada
Campo | Tipo | Método | Obrigatório | Descrição |
|---|---|---|---|---|
after | String | Query | Não | Cursor para paginação. Defina este valor como o último ID de tarefa da página anterior. |
limit | Integer | Query | Não | Número de tarefas por página. Intervalo: [1, 100]. Padrão: 20. |
ds_name | String | Query | Não | Correspondência aproximada pelo nome da tarefa. |
input_file_ids | String | Query | Não | Filtre pelos IDs dos arquivos. Especifique vários IDs separados por vírgulas (até 20). |
status | String | Query | Não | Filtre pelo status da tarefa. Especifique vários status separados por vírgulas. |
create_after | String | Query | Não | Filtre tarefas criadas após este horário. Formato: |
create_before | String | Query | Não | Filtre tarefas criadas antes deste horário. Formato: |
Exemplo de resposta
Parâmetros de resposta
Campo | Tipo | Descrição |
|---|---|---|
object | String | Tipo do objeto. Valor fixo: list. |
data | Array | Array de objetos de tarefa em lote. Consulte os parâmetros de resposta para criação de uma tarefa em lote. |
first_id | String | ID da primeira tarefa em lote na página atual. |
last_id | String | ID da última tarefa em lote na página atual. |
has_more | Boolean | Indica se há páginas adicionais disponíveis. |
Cancelar tarefa em lote
Cancelar tarefa em lote
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
Exemplo de requisição
Exemplo de resposta
Após cancelar uma tarefa com sucesso, a API retorna informações detalhadas sobre a tarefa em lote. A seguir, veja um exemplo de resposta para uma tarefa com status cancelling:Após o cancelamento de uma tarefa, o status muda primeiro paracancellingenquanto o sistema aguarda a conclusão das requisições em execução. Posteriormente, o status passa paracancelled. Os resultados das requisições concluídas continuam salvos no arquivo de saída.
4. Baixar arquivo de resultados do Batch
4. Baixar arquivo de resultados do Batch
file_id comece com file-batch_output.- OpenAI Python SDK
- OpenAI Node.js SDK
- Java (HTTP)
- curl (HTTP)
content para recuperar o conteúdo do arquivo de resultados da tarefa em lote e o método write_to_file para salvá-lo localmente.Exemplo de requisição
Exemplo de resposta
Exemplo de resposta
Exemplo de resposta única:Parâmetros de resposta
Campo | Tipo | Descrição |
|---|---|---|
id | String | O ID da requisição. |
custom_id | String | O identificador de requisição definido pelo usuário. |
response | Object | O resultado da requisição. |
status_code | Integer | Código de status HTTP. 200 indica sucesso. |
request_id | String | ID exclusivo gerado pelo servidor para esta requisição. |
completion_tokens | Integer | Número de tokens na resposta gerada pelo modelo. |
prompt_tokens | Integer | Número de tokens no conteúdo de entrada ( |
total_tokens | Integer | Número total de tokens utilizados por esta requisição. |
model | String | Nome do modelo utilizado nesta requisição. |
error | Object | O objeto de erro. Retorna |
error.code | String | Informações sobre a linha e o motivo do erro. Consulte Error codes para solução de problemas. |
error.message | String | Mensagem de erro. |
Recursos avançados
Configurar notificações de conclusão
Para tarefas de longa duração, utilize notificações assíncronas em vez de polling para reduzir o consumo de recursos.
- Callback: Especifique uma URL publicamente acessível ao criar a tarefa.
- Fila de mensagens do EventBridge: Integração profunda com o ecossistema Alibaba Cloud. Não requer IP público.
Método 1: Callback
Método 1: Callback
metadata. Após a conclusão da tarefa, o sistema envia uma requisição POST contendo o status da tarefa para a URL especificada:- OpenAI Python SDK
- curl (HTTP)
Método 2: Fila de mensagens do EventBridge
Método 2: Fila de mensagens do EventBridge
- Origem do evento (Source):
acs.dashscope - Tipo de evento (Type):
dashscope:System:BatchTaskFinish
Entrada em produção
-
Gerenciamento de arquivos
- Exclua periodicamente os arquivos desnecessários por meio do OpenAI File delete API para evitar o atingimento dos limites de armazenamento (10.000 arquivos ou 100 GB).
- Armazene arquivos grandes no OSS em vez de fazer upload direto.
-
Monitoramento de tarefas
- Utilize notificações assíncronas via Callback ou EventBridge.
- Caso seja necessário usar polling, defina o intervalo como superior a 1 minuto e adote uma estratégia de backoff exponencial.
-
Tratamento de erros
- Implemente o tratamento para erros de rede, erros de API e outras exceções.
- Baixe e analise os detalhes dos erros a partir de
error_file_id. - Para códigos de erro comuns, consulte Error codes.
-
Otimização de custos
- Consolide tarefas pequenas em um único lote.
- Defina
completion_windowadequadamente para garantir maior flexibilidade de agendamento.
Ferramentas utilitárias
CSV to JSONL
CSV to JSONL
Para personalizar o caminho do arquivo ou outros parâmetros, modifique o código conforme necessário.
JSONL results to CSV
JSONL results to CSV
result.jsonl em result.csv para análise no Excel.Para personalizar o caminho do arquivo ou outros parâmetros, modifique o código conforme necessário.
- Utilize um editor de texto (como o Sublime Text) para converter a codificação do arquivo CSV para GBK e, em seguida, abra-o no Excel.
- Como alternativa, crie um novo arquivo Excel e especifique a codificação UTF-8 ao importar os dados.
Limites de taxa
API | Limite de taxa (por conta Alibaba Cloud) |
|---|---|
Criar tarefa | 1.000 chamadas/minuto; até 1.000 tarefas simultâneas |
Consultar tarefa | 1.000 chamadas/minuto |
Consultar lista de tarefas | 100 chamadas/minuto |
Cancelar tarefa | 1.000 chamadas/minuto |
Faturamento
- Preço unitário: Os tokens de entrada e saída de todas as solicitações bem-sucedidas são cobrados a 50% do preço de inferência em tempo real do modelo correspondente. Para mais informações, consulte Model list.
-
Escopo de faturamento:
- Apenas as solicitações executadas com sucesso dentro de uma tarefa são faturadas.
- Solicitações que falham devido a erros de análise de arquivo, falhas na execução da tarefa ou erros no nível da linha não geram cobrança.
- Em 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 separado. Ela oferece suporte a AI general-purpose savings plan, mas não a descontos, como subscription (outros planos de economia) ou free quotas for new users. Também não há suporte para recursos como context cache.
- Alguns modelos, como qwen3.5-plus e qwen3.5-flash, têm o modo de raciocínio ativado por padrão. Esse modo gera tokens adicionais de raciocínio, que são cobrados pelo preço de token de saída e aumentam os custos. Para controlar as despesas, defina o parâmetro
enable_thinkingcom base na complexidade da tarefa. Para mais informações, consulte Deep thinking.
Códigos de erro
Se uma solicitação falhar e retornar uma mensagem de erro, consulte Error codes para obter uma solução.
Perguntas frequentes
- Como escolher entre Batch Chat e Batch File? Opte pelo Batch File quando precisar processar assincronicamente um arquivo grande contendo muitas solicitações. Prefira o Batch Chat quando sua lógica de negócios exigir o envio síncrono de diversas solicitações de conversa independentes com alta concorrência.
- Como funciona o faturamento da Batch File API? É preciso adquirir um pacote separado? O Batch utiliza o modelo de pagamento conforme o uso, baseado nos tokens consumidos pelas solicitações bem-sucedidas. Não é necessário nenhum pacote de recursos separado.
- Os arquivos de lote enviados são executados em ordem? Não. O sistema emprega agendamento dinâmico com base na carga computacional e não garante a ordem de execução. As tarefas podem sofrer atrasos quando os recursos estiverem limitados.
- Quanto tempo leva para concluir um arquivo de lote enviado? O tempo de execução depende dos recursos do sistema e da escala da tarefa. Caso a tarefa não seja concluída dentro do completion_window, ela expira. Solicitações não processadas em tarefas expiradas não são executadas nem geram cobrança. Recomendações de cenário: Utilize chamadas em tempo real para cenários que exigem inferência estrita de modelo em tempo real. Recorra a chamadas em lote para cenários de processamento de dados em larga escala que toleram atrasos.