Pipeline completo de ponta a ponta
Nesta página
Curso 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 as Conclusões de Chat, um endpoint legado na xAI. Fontes: API de Lotes · Referência REST · Preços de Lotes.
Reunir as peças
As lições anteriores abordaram cada passo isoladamente. Esta lição reúne-os num pipeline completo, desde a preparação dos dados até ao processamento dos resultados. No final, terá um script que pode adaptar ao seu caso de uso.
Pipeline Python completo
import json
import time
from xai_sdk import Client
client = Client() # chave lida de XAI_API_KEY
# --- Passo 1: preparar dados ---
documents = [
{"id": f"doc-{i}", "text": f"Document content {i}..."}
for i in range(100)
]
# --- Passo 2: escrever o ficheiro JSONL ---
with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
for doc in documents:
ligne = {
"custom_id": doc["id"],
"method": "POST",
"url": "/v1/responses",
"body": {
"model": "grok-4.3",
"input": [
{"role": "system", "content": "Summarize in two sentences."},
{"role": "user", "content": doc["text"]},
],
"max_output_tokens": 200,
},
}
f.write(json.dumps(ligne, ensure_ascii=False) + "\n")
# --- Passo 3: carregar o ficheiro ---
with open("batch_requests.jsonl", "rb") as f:
fichier = client.files.upload(f, filename="batch_requests.jsonl")
# --- Passo 4: criar o lote a partir do ficheiro (agora está selado) ---
batch = client.batch.create(batch_name="resumes_documents", input_file_id=fichier.id)
print(f"Batch created: {batch.batch_id}")
# --- Passo 5: aguardar o fim do processamento ---
while True:
batch = client.batch.get(batch_id=batch.batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Batch canceled by xAI: {batch.cancel_by_xai_message}")
if etat.num_requests > 0 and etat.num_pending == 0:
break
print(f"{etat.num_success + etat.num_error}/{etat.num_requests} requests processed")
time.sleep(300) # a cada 5 minutos
# --- Passo 6: recuperar resultados, página por página ---
resultats, echecs = {}, []
jeton = None
while True:
page = client.batch.list_batch_results(
batch_id=batch.batch_id, limit=100, pagination_token=jeton
)
for r in page.succeeded:
resultats[r.batch_request_id] = r.response.content
echecs.extend(page.failed)
if page.pagination_token is None:
break
jeton = page.pagination_token
with open("batch_results.json", "w", encoding="utf-8") as f:
json.dump(resultats, f, ensure_ascii=False, indent=2)
print(f"{len(resultats)} results, {len(echecs)} failures")
print("Total cost: $%.4f" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Três detalhes são importantes. A condição de paragem exige num_requests > 0 porque um lote criado a partir de um ficheiro é lido em segundo plano: logo após a criação, os seus contadores podem ainda estar todos a zero. O campo cancel_by_xai_message sinaliza o cancelamento pela xAI, por exemplo, devido a uma linha inválida. E o custo é expresso em ticks, dez mil milionésimos de um dólar.
Pipeline cURL passo a passo
Se preferir a linha de comandos, eis o equivalente em cURL (usando jq para ler as respostas):
# 1. Carregar o ficheiro JSONL
FILE_ID=$(curl -s -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl" | jq -r '.id')
echo "File: $FILE_ID"
# 2. Criar o lote a partir do ficheiro
BATCH_ID=$(curl -s -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"name\": \"resumes_documents\", \"input_file_id\": \"$FILE_ID\"}" | jq -r '.batch_id')
echo "Batch: $BATCH_ID"
# 3. Ler contadores
curl -s "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY" | jq '.state'
# 4. Recuperar a primeira página de resultados
curl -s "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY" > results-page-1.json
Obtenha as páginas subsequentes adicionando &pagination_token=… com o valor devolvido pela página anterior.
Gestão de erros em produção
Um pipeline robusto distingue três famílias de erros:
Erros de submissão: o carregamento do ficheiro ou a criação do lote falha. Re tente erros transitórios (tempo limite, limite de taxa, erro de servidor) com um atraso crescente: 1 s, 2 s, 4 s, 8 s.
Erros de processamento: alguns pedidos falham dentro do lote. Estes aparecem em page.failed com a respetiva mensagem; reenvie apenas esses, num novo lote.
Tempo limite e expiração: a janela de 24 horas é indicativa, não garantida. O que é implacável é a expiração (expire_time): após este ponto, os resultados deixam de estar acessíveis. Recupere-os à medida que chegam, em vez de todos de uma vez no final.
# Pedidos falhados: identifique-os para reenviar num novo lote
for r in echecs:
print(f"Failure: {r.batch_request_id} — {r.error_message}")
a_relancer = {r.batch_request_id for r in echecs}
Otimização de custos
As poupanças acumulam-se através de quatro alavancas. A escolha do modelo vem em primeiro lugar, sendo de longe a mais poderosa: à tarifa standard de 2 de novembro de 2026, o grok-4.3 custa 1,25 $ por milhão de tokens de entrada e 2,50 $ para saída, contra 2 $ e 6 $ para o grok-4.7 (prompts inferiores a 200.000 tokens). Para classificação ou extração curta, o modelo mais leve é frequentemente suficiente, e o desconto de lote de 20% aplica-se a ambos. O comprimento da resposta vem a seguir: max_output_tokens impede que pague por saídas desnecessariamente longas; para classificação, bastam alguns tokens. Prompts: remover dez tokens de um prompt repetido 50.000 vezes poupa 500.000 tokens de entrada. Finalmente, a cache: a xAI coloca automaticamente em cache o início idêntico dos pedidos, e o desconto de lote também se aplica aos tokens servidos a partir da cache; por isso, coloque instruções comuns no início de cada pedido, antes da parte variável.
Pontos-chave
- Um pipeline completo abrange seis passos: preparação, JSONL, carregamento, criação, monitorização, recuperação
- Um lote criado a partir de um ficheiro é lido em segundo plano: aguarde por
num_requests > 0antes de concluir que terminou - Trate as três famílias de erros: submissão, processamento, tempo limite e expiração
- Recupere e guarde os resultados à medida que chegam, antes do
expire_time - A escolha do modelo, o comprimento da saída, prompts curtos e prefixos comuns maximizam as poupanças