Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.mka1.com/llms.txt

Use this file to discover all available pages before exploring further.

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

EndpointDescrição
/v1/chat/completionsSolicitações de conclusão de chat
/v1/embeddingsGeração de embeddings
/v1/images/generationsGeraçã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
StatusDescrição
validatingO arquivo de entrada está sendo verificado quanto a erros de formato e conteúdo.
failedA validação falhou — o arquivo de entrada contém erros. Verifique batch.errors para detalhes.
in_progressAs solicitações estão sendo processadas.
finalizingTodas as solicitações foram processadas e os arquivos de saída estão sendo gerados.
completedO lote foi finalizado. Baixe os resultados de output_file_id.
cancellingUm cancelamento foi solicitado. Solicitações em andamento estão sendo finalizadas.
cancelledO lote foi cancelado. Resultados parciais podem estar disponíveis.
expiredO 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:
CampoTipoDescrição
custom_idstringSeu identificador para esta solicitação. Usado para relacionar entrada e saída. Deve ser único dentro do arquivo.
methodstring"POST" — o único método suportado.
urlstringO caminho do endpoint — deve corresponder ao endpoint que você declara ao criar o lote.
bodyobjectO 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