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âmetro | Tipo | Obrigatório | Descrição |
|---|
--file <csv> | string | Sim | CSV UTF-8 com cabeçalhos |
--output-file <jsonl> | string | Sim | Caminho de saída JSONL local |
--model <model> | string | Sim | Modelo para cada registro |
--id-column <name> | string | Não | Coluna de ID (padrão: custom_id) |
--input-column <name> | string | Não | Coluna de entrada (padrão: content) |
--system <text> | string | Não | Prompt de sistema compartilhado (somente Chat) |
--body-file <json> | string | Não | Parâmetros de corpo compartilhados, exceto model, messages ou input |
--endpoint </v1/chat/completions|/v1/embeddings|/v1/chat/ds-test> | string | Não | Endpoint do Batch, inferido do JSONL local |
--force | switch | Não | Substituir 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âmetro | Tipo | Obrigatório | Descrição |
|---|
--file <jsonl> | string | Não | Batch JSONL local (exclusivo com --input-file-id) |
--input-file-id <source> | string | Não | ID de arquivo, URL HTTPS do OSS ou oss:region:bucket/path |
--completion-window <24h|7d> | string | Não | Janela de conclusão: 24–336 horas (padrão: 24h) |
--name <text> | string | Não | Nome da tarefa (máximo de 100 caracteres) |
--description <text> | string | Não | Descrição da tarefa (máximo de 200 caracteres) |
--callback-url <url> | string | Não | Callback de conclusão; atualmente documentado apenas para a região China (Pequim) |
--metadata <KEY=VALUE> | array | Não | Metadados personalizados da tarefa (repetível) |
--endpoint </v1/chat/completions|/v1/embeddings|/v1/chat/ds-test> | string | Não | Endpoint 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âmetro | Tipo | Obrigatório | Descrição |
|---|
--batch-id <id> | string | Sim | ID da tarefa Batch |
--follow | switch | Não | Consultar até um estado terminal (Ctrl-C interrompe apenas a consulta local) |
--interval <seconds> | number | Não | Intervalo de consulta, mínimo de 60 s (padrão: 65 s; somente --follow) |
--poll-timeout <seconds> | number | Não | Orç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âmetro | Tipo | Obrigatório | Descrição |
|---|
--limit <n> | number | Não | Tamanho da página: 1–100 (padrão: 20) |
--after <id> | string | Não | last_id da página anterior |
--name <text> | string | Não | Filtro por nome da tarefa |
--input-file-id <id> | array | Não | Filtro por arquivo de entrada (repetível, máximo 20) |
--status <status> | array | Não | Filtro por status da tarefa (repetível): validating, in_progress, finalizing, completed, failed, expired, cancelling, cancelled |
--created-after <yyyyMMddHHmmss> | string | Não | Criada após este timestamp da API |
--created-before <yyyyMMddHHmmss> | string | Não | Criada 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âmetro | Tipo | Obrigatório | Descrição |
|---|
--batch-id <id> | string | Sim | ID 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âmetro | Tipo | Obrigatório | Descrição |
|---|
--batch-id <id> | string | Sim | ID da tarefa Batch |
--out-dir <path> | string | Não | Diretório de saída (padrão: ./batch-results/<batch-id>/) |
--csv | switch | Não | Também gerar result.csv (projeção de exibição com perdas) |
--force | switch | Não | Substituir 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.