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.
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: Obtenha e configure sua API Key em variáveis de ambiente
- Instalar o SDK (opcional): Para chamar a API com o SDK, instale o SDK da OpenAI
-
Endpoints
- China (Pequim):
https://dashscope.aliyuncs.com/compatible-mode/v1 - Singapura:
https://dashscope-intl.aliyuncs.com/compatible-mode/v1
- China (Pequim):
Escopo
- Singapore
- China (Beijing)
-
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
- Compreensão de imagem e vídeo: qwen3.8-max, qwen3.7-plus
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.
- 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:
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.
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:client.files.list(purpose="batch").Código de exemplo
Código de exemplo
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."}:
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
As strings Base64 dos exemplos foram omitidas; use o código Python abaixo para gerar a codificação completa.
Passar uma string codificada em Base64 (usando uma imagem como exemplo)
Passar uma string codificada em Base64 (usando uma imagem como exemplo)
- Converta o arquivo local para codificação Base64:
-
Construa o formato Data URL:
data:[MIME_type];base64,{base64_image};MIME_typedeve ser substituído pelo tipo de mídia real, garantindo que corresponda ao valor deMIME Type(por exemplo,image/jpeg,image/png);base64_imageé a string Base64 gerada na etapa anterior.
Uso
- Salve o código a seguir como
generate_batch_jsonl.py - Modifique o conteúdo das solicitações da lista
TASKSno script - Execute
python generate_batch_jsonl.py - O arquivo
batch_input.jsonlgerado pode ser usado diretamente para tarefas de inferência em lote
Script de geração de JSONL para modelos de geração de texto
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:
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:
1. Modifique o arquivo de entrada
-
Você pode modificar diretamente o arquivo
test_model.jsonlusado 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/completionsModelos 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
modeleurlestejam corretos.
2. Modifique o código do Início rápido
- Altere o caminho do arquivo de entrada para o nome do seu arquivo
- 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, contendocustom_ideresponse.
- 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.
1. Upload de arquivos
1. Upload de arquivos
file_id.Ao fazer o upload de um arquivo,purposedeve serbatch.
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:client.files.list(purpose="batch").- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
Exemplo de requisição
Exemplo de resposta
2. Criar uma tarefa em lote
2. Criar 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 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 |
endpoint | String | Body | Sim | O caminho de acesso, que deve corresponder ao campo URL no arquivo de entrada.
|
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: 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: Limite: até 200 caracteres. Se este campo for definido repetidamente, o último valor passado prevalece. |
Exemplo de resposta
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 |
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. |
3. Consultar e gerenciar tarefas em lote
3. Consultar e gerenciar tarefas em lote
Consultar o status de uma tarefa específica
Consultar o status de uma tarefa específica
- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
Exemplo de requisição
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:Campo | Tipo | Descrição |
|---|---|---|
id | String | ID da tarefa em lote. |
status | String | Status da tarefa. Os valores possíveis incluem:
|
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. |
Consultar a lista de tarefas
Consultar a lista de tarefas
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
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 |
create_before | String | Query | Não | Filtra tarefas criadas antes deste ponto no tempo, no formato |
Exemplo de resposta
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. |
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 o cancelamento bem-sucedido da tarefa, os detalhes da tarefa em lote são retornados. A seguir, um exemplo de resposta no estado cancelling:Após cancelar a tarefa, o status muda primeiro paracancelling, aguardando a conclusão das solicitações em andamento; eventualmente muda paracancelled. Os resultados das solicitações concluídas ainda são salvos no arquivo de saída.
4. Baixar o arquivo de resultados do lote
4. Baixar o arquivo de resultados do lote
file_id que começa com file-batch_output pode ser baixado.- OpenAI Python SDK
- OpenAI Node.js SDK
- Java(HTTP)
- curl(HTTP)
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
Exemplo de resposta
Exemplo de resposta
Resultado de uma única resposta: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 ( |
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 é |
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.
- 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
Método 1: Callback
Método 1: Callback
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)
Método 2: Fila de mensagens do EventBridge
Método 2: Fila de mensagens do EventBridge
- Origem:
acs.dashscope - Tipo:
dashscope:System:BatchTaskFinish
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_windowadequadamente para fornecer mais flexibilidade de agendamento
Utilitários
CSV para JSONL
CSV para JSONL
Para alterar o caminho do arquivo ou outros parâmetros, modifique o código conforme necessário.
Resultados JSONL para CSV
Resultados JSONL para CSV
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.
- 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
- 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.
- 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.
- 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.
- 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.