Acompanhamento, estado e cancelamento
Nesta página
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-sdkoficial (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 pedido | Significado | Ação |
|---|---|---|
pending | Em fila de espera | Aguardar |
succeeded | Processado, resultado disponível | Obter resultado |
failed | Erro durante o processamento | Ler mensagem, repetir se útil |
cancelled | Cancelado, por exemplo com o seu lote | Reenviar 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,/resultsos resultados,/requestso 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
limitepagination_token - Faça polling em intervalos de alguns minutos, com um atraso máximo, e obtenha os dados antes do
expire_time