Skip to main content

Inferência em lote

Referência de comandos da CLI do Model Studio para criar, acompanhar e baixar tarefas de inferência em lote assíncronas.

O bl batch converte CSV em Batch JSONL, cria tarefas de lote Chat ou Embedding assíncronas, acompanha o progresso, cancela tarefas e baixa arquivos de resultado e de erro. Tarefas de lote assíncronas baseadas em arquivo são separadas da requisição única síncrona bl text chat --batch.
O batch convert é executado localmente e não requer autenticação. Criar, consultar, cancelar e baixar tarefas exige uma chave de API de modelo. A disponibilidade e os limites do Batch dependem do modelo e do serviço.
Adicione --help a qualquer comando para ver os detalhes completos dos parâmetros, por exemplo bl batch create --help. Os detalhes dos comandos nesta página foram verificados com o bl 2.8.0.

Início rápido

bl batch convert --file input.csv --model qwen-plus --output-file input.jsonl
bl batch create --file input.jsonl
bl batch get --batch-id <batch-id> --follow
bl batch download --batch-id <batch-id> --csv

Gerenciamento de tarefas

bl batch convert

Cria Batch JSONL a partir de um CSV UTF-8 localmente. Não requer autenticação. Uso
bl batch convert --file <csv> --model <model> --output-file <jsonl> [flags]
ParâmetroTipoObrigatórioDescrição
--file <csv>stringSimCSV UTF-8 com cabeçalhos
--output-file <jsonl>stringSimCaminho de saída JSONL local
--model <model>stringSimModelo para cada registro
--id-column <name>stringNãoColuna de ID (padrão: custom_id)
--input-column <name>stringNãoColuna de entrada (padrão: content)
--system <text>stringNãoPrompt de sistema compartilhado (somente Chat)
--body-file <json>stringNãoParâmetros de corpo compartilhados, exceto model, messages ou input
--endpoint </v1/chat/completions|/v1/embeddings|/v1/chat/ds-test>stringNãoEndpoint do Batch, inferido do JSONL local
--forceswitchNãoSubstituir arquivos de saída existentes (atômico por arquivo)
Exemplo: Converter CSV em Chat JSONL
bl batch convert --file input.csv --model qwen-plus --output-file input.jsonl
Exemplo: Converter CSV em Embedding JSONL
bl batch convert --file input.csv --model text-embedding-v4 --endpoint /v1/embeddings --output-file vectors.jsonl
  • Apenas o mapeamento de campos de texto e Embedding é suportado. Escreva o JSONL diretamente para entradas multimodais ou de vários turnos.
  • Os IDs permanecem strings. Importe IDs CSV como texto no software de planilha para manter os zeros à esquerda.
  • O dry-run não faz requisições de negócio nem grava arquivos de negócio.

bl batch create

Faz upload ou referencia a entrada e cria uma tarefa Batch assíncrona. Requer autenticação por chave de API. Uso
bl batch create (--file <jsonl> | --input-file-id <source> --endpoint <path>) [flags]
ParâmetroTipoObrigatórioDescrição
--file <jsonl>stringNãoBatch JSONL local (exclusivo com --input-file-id)
--input-file-id <source>stringNãoID de arquivo, URL HTTPS do OSS ou oss:region:bucket/path
--completion-window <24h|7d>stringNãoJanela de conclusão: 24–336 horas (padrão: 24h)
--name <text>stringNãoNome da tarefa (máximo de 100 caracteres)
--description <text>stringNãoDescrição da tarefa (máximo de 200 caracteres)
--callback-url <url>stringNãoCallback de conclusão; atualmente documentado apenas para a região China (Pequim)
--metadata <KEY=VALUE>arrayNãoMetadados personalizados da tarefa (repetível)
--endpoint </v1/chat/completions|/v1/embeddings|/v1/chat/ds-test>stringNãoEndpoint do Batch, inferido do JSONL local
Exemplo: Pré-visualizar a criação da tarefa
bl batch create --file input.jsonl --name eval-1 --dry-run
Exemplo: Criar uma tarefa a partir de um ID de arquivo
bl batch create --input-file-id file-batch-xxx --endpoint /v1/chat/completions
Exemplo: Referenciar um caminho do OSS com janela de conclusão de 7 dias
bl batch create --input-file-id oss:ap-southeast-1:my-bucket/input.jsonl --endpoint /v1/chat/completions --completion-window 7d
Exemplo de Chat JSONL:
{"custom_id":"req-001","method":"POST","url":"/v1/chat/completions","body":{"model":"qwen-plus","messages":[{"role":"user","content":"Introduce yourself"}]}}
Exemplo de Embedding JSONL:
{"custom_id":"req-001","method":"POST","url":"/v1/embeddings","body":{"model":"text-embedding-v4","input":"Introduce yourself","encoding_format":"float"}}
  • Limites de entrada local: 50.000 requisições, 500 MiB e 6 MiB por linha. Linhas acima de 1 MiB geram um aviso.
  • O batch-test-model é limitado a 100 requisições e 1 MiB.
  • Referências remotas exigem autorização e uma URL válida; a CLI não as baixa para validação.
  • Uma criação bem-sucedida retorna um ID de tarefa sem aguardar a conclusão. Não há repetição de POST nem limpeza de arquivos enviados em caso de falha.

bl batch get

Obtém detalhes da tarefa Batch e, opcionalmente, acompanha o progresso. Requer autenticação por chave de API. Uso
bl batch get --batch-id <id> [--follow] [--interval <seconds>] [--poll-timeout <seconds>]
ParâmetroTipoObrigatórioDescrição
--batch-id <id>stringSimID da tarefa Batch
--followswitchNãoConsultar até um estado terminal (Ctrl-C interrompe apenas a consulta local)
--interval <seconds>numberNãoIntervalo de consulta, mínimo de 60 s (padrão: 65 s; somente --follow)
--poll-timeout <seconds>numberNãoOrçamento total de consulta (padrão: ilimitado; somente --follow)
Exemplo: Acompanhar uma tarefa até o fim
bl batch get --batch-id batch_xxx --follow
  • Um único get sai com código 0 após uma consulta bem-sucedida, independentemente do estado da tarefa.
  • Com --follow, o código 0 significa concluída (pode conter linhas com falha), 1 significa falha, expirada ou cancelada, 5 significa timeout do cliente e 130 significa Ctrl-C.
  • finalizing e cancelling não são estados terminais.
  • O progresso vai para stderr; o resultado final vai para stdout.
  • Apenas erros de transporte, timeouts ou HTTP 429/5xx são repetidos, no máximo três vezes.
  • A retenção no servidor é limitada; baixe os resultados prontamente.

bl batch list

Lista uma página de tarefas Batch. Requer autenticação por chave de API. Uso
bl batch list [filters] [--after <id>] [--limit <n>]
ParâmetroTipoObrigatórioDescrição
--limit <n>numberNãoTamanho da página: 1–100 (padrão: 20)
--after <id>stringNãolast_id da página anterior
--name <text>stringNãoFiltro por nome da tarefa
--input-file-id <id>arrayNãoFiltro por arquivo de entrada (repetível, máximo 20)
--status <status>arrayNãoFiltro por status da tarefa (repetível): validating, in_progress, finalizing, completed, failed, expired, cancelling, cancelled
--created-after <yyyyMMddHHmmss>stringNãoCriada após este timestamp da API
--created-before <yyyyMMddHHmmss>stringNãoCriada antes deste timestamp da API
Exemplo: Listar tarefas concluídas e com falha
bl batch list --status completed --status failed --limit 20
  • Retorna data, last_id e has_more. Passe last_id para --after na próxima página.
  • Os timestamps da API não são convertidos de fuso horário.

bl batch cancel

Solicita o cancelamento de uma tarefa Batch. Requer autenticação por chave de API. Uso
bl batch cancel --batch-id <id>
ParâmetroTipoObrigatórioDescrição
--batch-id <id>stringSimID da tarefa Batch
Exemplo: Solicitar o cancelamento da tarefa
bl batch cancel --batch-id batch_xxx
  • Um cancelamento aceito pode retornar cancelling, não cancelled. Use batch get --follow para confirmar.
  • Requisições já executadas continuam sendo cobradas; os arquivos não são excluídos.

bl batch download

Baixa os resultados originais ou arquivos de erro e, opcionalmente, exporta CSV. Requer autenticação por chave de API. Uso
bl batch download --batch-id <id> [--out-dir <path>] [--csv] [--force]
ParâmetroTipoObrigatórioDescrição
--batch-id <id>stringSimID da tarefa Batch
--out-dir <path>stringNãoDiretório de saída (padrão: ./batch-results/<batch-id>/)
--csvswitchNãoTambém gerar result.csv (projeção de exibição com perdas)
--forceswitchNãoSubstituir arquivos de saída existentes (atômico por arquivo)
Exemplo: Baixar resultados e exportar CSV
bl batch download --batch-id batch_xxx --out-dir ./out --csv
  • O JSONL é a fonte autoritativa. O CSV lê apenas choices[0].message.content, dados de Embedding, response.request_id, status_code, uso e error.code / error.message.
  • O CSV omite chamadas de ferramentas e escolhas adicionais, e trata texto semelhante a fórmulas como texto. Importe IDs como texto para manter os zeros à esquerda.
  • A ordem de entrada original não é garantida.
  • Os arquivos são publicados atomicamente por arquivo, não por diretório. Se a geração do CSV falhar, o JSONL baixado é preservado; execute novamente com --force para recuperar.

Comandos relacionados

Para uma requisição única síncrona, use bl text chat --batch. Ele não cria uma tarefa assíncrona. Consulte Chat de texto e Omni.