Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Fluxo de trabalho em quatro etapas

Aula 2 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. O ciclo de vida de um lote
  2. Etapa 1: Criar um lote
  3. Etapa 2: Adicionar pedidos
  4. Etapa 3: Monitorizar o progresso
  5. Etapa 4: Recuperar resultados
  6. O fluxo de trabalho na prática
  7. Gestão de erros no fluxo de trabalho
  8. Pontos-chave

Atualizado em 2 de novembro de 2026 com base na documentação da xAI: o desconto para lotes é de 20% em modelos de texto elegíveis (não 50%); os exemplos utilizam a API REST e o xai-sdk oficial (client.batch.*; a API de Lotes da xAI não segue o formato da OpenAI, pelo que o SDK da OpenAI não se aplica); e a API de Respostas tem precedência sobre a de Completamentos de Chat, um endpoint legado na xAI. Fontes: Batch API · REST reference · Batch pricing.

O ciclo de vida de um lote

Cada lote segue o mesmo ciclo: criar, adicionar pedidos, processar e recuperar resultados. Compreender este ciclo é essencial antes de avançar para a implementação, pois cada etapa possui as suas próprias restrições e melhores práticas.

Etapa 1: Criar um lote

Tudo começa com uma chamada POST /v1/batches, com um campo obrigatório: o nome do lote. A API devolve um identificador único (batch_id) que utilizará para todas as operações subsequentes.

curl -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "customer_review_analysis"}'

A resposta contém também as datas de criação e expiração do lote (create_time, expire_time) e um objeto state cujos contadores estão ainda todos a zero.

Etapa 2: Adicionar pedidos

Existem dois métodos:

Através da API: envia pedidos com POST /v1/batches/{batch_id}/requests. Cada chamada transporta uma lista de pedidos e pode continuar a adicioná-los enquanto o lote não for cancelado. Este é o caminho para lotes construídos incrementalmente.

Através de um ficheiro JSONL: prepara um ficheiro contendo todos os seus pedidos, carrega-o através da API de Ficheiros e, em seguida, cria o lote a partir desse ficheiro. O lote fica então selado: não são possíveis mais adições. Este é o caminho para grandes volumes preparados antecipadamente.

Cada pedido transporta um identificador único dentro do lote: batch_request_id na API, custom_id no ficheiro JSONL. Se o omitir na API, a xAI gera um UUID; forneça o seu próprio (um ID de base de dados, por exemplo): serve como chave de correspondência entre os seus dados e os resultados, e garante que um pedido é processado apenas uma vez.

Etapa 3: Monitorizar o progresso

O processamento inicia assim que os pedidos chegam; não existe uma etapa de “início”. Entretanto, GET /v1/batches/{batch_id} devolve o objeto state e os seus contadores: num_requests (total), num_pending (pendentes), num_success (bem-sucedidos), num_error (falhados) e num_cancelled (cancelados).

curl https://api.x.ai/v1/batches/$BATCH_ID \
  -H "Authorization: Bearer $XAI_API_KEY"

Quando num_pending desce para zero, todos os pedidos foram processados, com sucesso ou não. A sondagem periódica é suficiente: alguns segundos para um lote de teste pequeno, alguns minutos para um lote grande.

Etapa 4: Recuperar resultados

Os resultados são lidos com GET /v1/batches/{batch_id}/results, sem esperar que o lote termine: cada pedido está disponível assim que é processado. A resposta é paginada: limit define o tamanho da página (máximo 1.000) e o pagination_token devolvido é utilizado para solicitar a página seguinte; está vazio na última página.

curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
  -H "Authorization: Bearer $XAI_API_KEY"

Cada resultado transporta o batch_request_id do seu pedido: isto permite-lhe reconstruir o mapeamento entre os seus dados de entrada e as respostas do Grok.

O fluxo de trabalho na prática

Num pipeline de produção, o fluxo de trabalho traduz-se geralmente em dois processos separados:

  • Um processo de submissão que cria o lote, prepara e adiciona pedidos, e depois armazena o batch_id
  • Um processo de recuperação que verifica periodicamente os contadores e descarrega os resultados à medida que ficam disponíveis

Esta separação permite-lhe integrar a API de Lotes em arquiteturas orientadas por eventos ou em pipelines de dados existentes (tarefas cron, Apache Airflow, filas).

Gestão de erros no fluxo de trabalho

Um lote não possui um estado global de “sucesso” ou “falha”: lê-se através dos seus contadores. Um pedido falhado incrementa num_error e aparece nos resultados com a sua mensagem de erro, sem bloquear os outros. Deve, portanto, examinar cada resultado e tratar as falhas caso a caso.

Dois eventos afetam todo o lote. O primeiro é o cancelamento, por si ou pela xAI, que então o explica no campo cancel_by_xai_message. Isto acontece, em particular, quando uma linha num ficheiro JSONL é inválida. O outro é a expiração (expire_time), após a qual os resultados deixam de estar acessíveis: recupere-os prontamente.

Pontos-chave

  • O fluxo de trabalho segue a ordem: criar (com um nome), adicionar, monitorizar, recuperar
  • O identificador do pedido (batch_request_id, ou custom_id em JSONL) é a sua chave de correspondência
  • O progresso lê-se nos contadores de state; tudo está processado quando num_pending é zero
  • Os resultados são paginados (limit, pagination_token) e estão disponíveis à medida que são processados
  • Os erros são tratados pedido a pedido; o cancelamento e a expiração afetam todo o lote