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

Acompanhamento, estado e cancelamento

Aula 11 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Gerir o ciclo de vida do lote
  2. Dois níveis de estado
  3. Verificar contadores
  4. Listar os seus lotes
  5. Obter resultados
  6. Verificar metadados do pedido
  7. Cancelar um lote
  8. Estratégia de polling
  9. 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 seguem a API REST e o xai-sdk oficial (client.batch.*; a API de Lotes da xAI não corresponde ao formato da OpenAI, pelo que o SDK da OpenAI não se aplica), e a API de Respostas tem precedência sobre a de Conclusões de Chat, um endpoint legado na xAI. Fontes: API de Lotes · Referência REST · Preços de Lotes.

Gerir o ciclo de vida do lote

Assim que submeter os seus pedidos, precisa de acompanhar o progresso do processamento, ler os estados e saber quando e como cancelar um lote. Esta lição cobre todas as operações de gestão disponíveis.

Dois níveis de estado

A xAI acompanha o progresso em dois níveis. O lote em si não possui um estado global como “concluído” ou “falhado”: contém contadores no seu objeto state. Cada pedido, no entanto, tem o seu próprio estado:

Estado do pedidoSignificadoAção
pendingEm fila de esperaAguardar
succeededProcessado, resultado disponívelObter resultado
failedErro durante o processamentoLer mensagem, repetir se útil
cancelledCancelado, por exemplo com o seu loteReenviar se necessário

O lote está totalmente processado quando o seu contador num_pending desce para zero. Também pode ser cancelado ou expirar: após o expire_time, os seus resultados deixam de estar acessíveis.

Verificar contadores

A chamada GET /v1/batches/{batch_id} devolve o lote e os seus contadores:

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

A resposta inclui:

{
  "batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
  "name": "analyse_avis_clients",
  "state": {
    "num_requests": 500,
    "num_pending": 155,
    "num_success": 342,
    "num_error": 3,
    "num_cancelled": 0
  }
}

Estes contadores monitorizam o progresso em tempo real, sem esperar que o processamento termine. Com o SDK, leia-os em client.batch.get(batch_id=...).state.

Listar os seus lotes

Para encontrar um lote ou verificar o histórico:

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

A lista é paginada através de limit e pagination_token. Os lotes permanecem lá até expirarem. Com o SDK, client.batch.list(limit=20) devolve uma lista batches onde cada elemento carrega o seu name, batch_id e state. A consola da xAI oferece a mesma visão, de forma visual.

Obter resultados

Pode obter resultados a qualquer momento, mesmo durante o processamento:

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

Cada resultado carrega o batch_request_id do seu pedido. Os pedidos falhados aparecem aqui com a sua mensagem; com o SDK, as propriedades succeeded e failed de cada página separam-nos.

Verificar metadados do pedido

Para acompanhar o estado de cada pedido:

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

Cada entrada fornece o identificador do pedido, o seu endpoint, modelo, estado, e datas de criação e término. Esta é a ferramenta de diagnóstico quando um contador estagna, ou para verificar o que foi adicionado com sucesso.

Cancelar um lote

Se precisar de parar o processamento em curso:

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

O cancelamento é definitivo: os pedidos pendentes não serão processados e já não pode adicionar pedidos ao lote. Os pedidos já processados, no entanto, permanecem disponíveis nos resultados. Cancele se:

  • Detetou um erro nos seus pedidos após o envio
  • O lote já não é necessário (mudança de prioridade)
  • Deseja reenviar um lote corrigido

Com o SDK: client.batch.cancel(batch_id=...), que devolve o lote e os seus contadores no momento do cancelamento.

Estratégia de polling

Em produção, aguarde a conclusão com polling espaçado e um atraso máximo:

import time


def attendre_batch(client, batch_id, intervalle=300, delai_max=2 * 86400):
    """Wait until all requests in the batch are processed."""
    debut = time.monotonic()
    while time.monotonic() - debut < delai_max:
        batch = client.batch.get(batch_id=batch_id)
        etat = batch.state
        if batch.cancel_by_xai_message:
            raise RuntimeError(f"Canceled by xAI: {batch.cancel_by_xai_message}")
        if etat.num_requests > 0 and etat.num_pending == 0:
            return batch
        print(f"{etat.num_success} succeeded, {etat.num_error} failed, "
              f"{etat.num_pending} pending out of {etat.num_requests}")
        time.sleep(intervalle)
    raise TimeoutError(f"Batch not finished after {delai_max} s")

Um intervalo de alguns minutos adequa-se a lotes grandes; a documentação da xAI faz polling a cada poucos segundos nos seus exemplos, que cobrem lotes pequenos. E como os resultados estão disponíveis à medida que chegam, nada impede que os obtenha durante a espera.

Pontos-chave

  • Leia o lote através dos seus contadores (num_pending, num_success, num_error…); cada pedido tem o seu estado: pending, succeeded, failed, cancelled
  • GET /v1/batches/{id} fornece o progresso, /results os resultados, /requests o detalhe do pedido
  • O cancelamento (POST /v1/batches/{id}:cancel) é irreversível, mas mantém os resultados já produzidos
  • Listas e resultados são paginados com limit e pagination_token
  • Faça polling em intervalos de alguns minutos, com um atraso máximo, e obtenha os dados antes do expire_time