Processamento em lote

A API de Lotes permite que você envie grupos de solicitações como um único trabalho que é processado de forma assíncrona. Isso é útil quando você precisa executar muitas solicitações e não precisa dos resultados imediatamente — por exemplo, ao rodar avaliações, gerar embeddings para um grande conjunto de dados ou classificar conteúdo em massa. As solicitações em lote são executadas dentro de uma janela de conclusão de 24 horas e possuem limites de taxa separados e mais altos do que as chamadas síncronas da API.

Endpoints suportados

Endpoint	Descrição
`/v1/chat/completions`	Solicitações de conclusão de chat
`/v1/embeddings`	Geração de embeddings
`/v1/images/generations`	Geração de imagens

Todas as solicitações em um único lote devem ter como alvo o mesmo endpoint.

Ciclo de vida

Um lote passa pelos seguintes status:

validating → in_progress → finalizing → completed
     ↓            ↓
   failed     cancelling → cancelled

Status	Descrição
`validating`	O arquivo de entrada está sendo verificado quanto a erros de formato e conteúdo.
`failed`	A validação falhou — o arquivo de entrada contém erros. Verifique `batch.errors` para detalhes.
`in_progress`	As solicitações estão sendo processadas.
`finalizing`	Todas as solicitações foram processadas e os arquivos de saída estão sendo gerados.
`completed`	O lote foi finalizado. Baixe os resultados de `output_file_id`.
`cancelling`	Um cancelamento foi solicitado. Solicitações em andamento estão sendo finalizadas.
`cancelled`	O lote foi cancelado. Resultados parciais podem estar disponíveis.
`expired`	O lote não foi concluído dentro da janela de 24 horas.

Passo 1 — Prepare o arquivo de entrada

Crie um arquivo JSONL onde cada linha é uma solicitação. Cada linha tem quatro campos:

Campo	Tipo	Descrição
`custom_id`	string	Seu identificador para esta solicitação. Usado para relacionar entrada e saída. Deve ser único dentro do arquivo.
`method`	string	`"POST"` — o único método suportado.
`url`	string	O caminho do endpoint — deve corresponder ao `endpoint` que você declara ao criar o lote.
`body`	object	O corpo da solicitação — os mesmos parâmetros que você enviaria para o endpoint síncrono.

{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "meetkai:functionary-pt", "messages": [{"role": "user", "content": "Summarize the benefits of batch processing in one sentence."}], "max_tokens": 100}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "meetkai:functionary-pt", "messages": [{"role": "user", "content": "What is the capital of France?"}], "max_tokens": 100}}
{"custom_id": "request-3", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "meetkai:functionary-pt", "messages": [{"role": "user", "content": "Explain embeddings in one paragraph."}], "max_tokens": 100}}

Um único lote pode conter até 10.000 solicitações.

Passo 2 — Faça upload do arquivo de entrada

Envie o arquivo JSONL usando a API de Arquivos com purpose: "batch".

mka1 llm files upload \
  --file ./batch_input.jsonl \
  --purpose batch \
  -H 'X-On-Behalf-Of: <end-user-id>'

Passo 3 — Crie o lote

Informe o ID do arquivo enviado, o endpoint de destino e a janela de conclusão.

mka1 llm batches create --body '{
  "input_file_id": "file_abc123",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h"
}'

Você também pode anexar metadados para seu próprio controle:

mka1 llm batches create --body '{
  "input_file_id": "file_abc123",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "metadata": {
    "description": "nightly evaluation run",
    "run_id": "eval-2026-03-31"
  }
}'

Passo 4 — Verifique o status do lote

Faça polling do lote até que ele atinja um status final.

mka1 llm batches get --batch-id batch_abc123

Aqui está um auxiliar de polling que espera o lote finalizar:

# Faça polling de um lote até atingir um status final usando --jq e um loop de shell.
BATCH_ID=batch_abc123
while :; do
  STATUS=$(mka1 llm batches get --batch-id "$BATCH_ID" --jq '.status' --output-format json)
  echo "status: $STATUS"
  case "$STATUS" in
    completed|failed|cancelled|expired) break ;;
  esac
  sleep 2
done

Passo 5 — Baixe os resultados

Quando o lote estiver completed, baixe o arquivo de saída. Ele é um arquivo JSONL onde cada linha contém o custom_id que você forneceu, a resposta e qualquer erro.

# Baixe o arquivo de saída JSONL
mka1 llm files content \
  --file-id file_xyz789 \
  --output-file ./batch_output.jsonl

# Inspecione os resultados inline com jq
mka1 llm files content --file-id file_xyz789 \
  --jq '"\(.custom_id): status=\(.response.status_code)"'

Cada linha do arquivo de saída tem esta estrutura:

{
  "id": "response_abc123",
  "custom_id": "request-1",
  "response": {
    "status_code": 200,
    "request_id": "req_abc123",
    "body": { "...": "same shape as the synchronous endpoint response" }
  },
  "error": null
}

Se uma solicitação falhar, response será null e error conterá os detalhes:

{
  "id": "response_def456",
  "custom_id": "request-2",
  "response": null,
  "error": {
    "code": "processing_error",
    "message": "The request could not be processed."
  }
}

Se houver solicitações com falha, o lote também fornece um error_file_id contendo apenas as entradas que falharam.

Cancelar um lote

Cancele um lote que ainda está em andamento. Solicitações que já foram concluídas permanecem na saída.

mka1 llm batches cancel --batch-id batch_abc123

O lote transita para cancelling enquanto as solicitações em andamento são finalizadas, depois para cancelled.

Listar lotes

Recupere todos os lotes da conta atual, do mais recente para o mais antigo. Suporta paginação.

mka1 llm batches list --limit 20

Use o parâmetro after com um ID de lote para paginar os resultados.

Exemplo: embeddings em lote

O mesmo fluxo funciona para embeddings. Altere o url em cada linha do JSONL e o endpoint ao criar o lote.

{"custom_id": "embed-1", "method": "POST", "url": "/v1/embeddings", "body": {"model": "meetkai:functionary-pt", "input": "The quick brown fox"}}
{"custom_id": "embed-2", "method": "POST", "url": "/v1/embeddings", "body": {"model": "meetkai:functionary-pt", "input": "jumps over the lazy dog"}}

# Faça upload do arquivo JSONL de embeddings
FILE_ID=$(mka1 llm files upload \
  --file ./embed_batch.jsonl \
  --purpose batch \
  --jq '.id' --output-format json | tr -d '"')

# Crie o lote para o endpoint de embeddings
mka1 llm batches create --body "{
  \"input_file_id\": \"$FILE_ID\",
  \"endpoint\": \"/v1/embeddings\",
  \"completion_window\": \"24h\"
}"

# Faça polling e baixe os resultados — veja os Passos 4 e 5

Erros de validação

Se o arquivo de entrada tiver problemas de formatação, o lote muda para failed imediatamente. Causas comuns:

JSON inválido — uma linha não é um JSON válido.
Campos ausentes — uma linha está sem custom_id, method, url ou body.
Método incorreto — method deve ser "POST".
URL não corresponde — o url de uma linha não corresponde ao endpoint declarado ao criar o lote.
custom_id duplicado — cada custom_id deve ser único dentro do arquivo.

Verifique batch.errors.data para mensagens de erro específicas e números de linha.

mka1 llm batches get --batch-id batch_abc123 \
  --jq '.errors.data[] | "Line \(.line): [\(.code)] \(.message)"'

Veja também

Gerar uma resposta para o padrão síncrono de conclusões de chat.
Arquivos e vetores para a API de Arquivos usada para enviar entradas em lote.

​Endpoints suportados

​Ciclo de vida

​Passo 1 — Prepare o arquivo de entrada

​Passo 2 — Faça upload do arquivo de entrada

​Passo 3 — Crie o lote

​Passo 4 — Verifique o status do lote

​Passo 5 — Baixe os resultados

​Cancelar um lote

​Listar lotes

​Exemplo: embeddings em lote

​Erros de validação

​Veja também