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

Pipeline completo de ponta a ponta

Aula 7 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Reunir as peças
  2. Pipeline Python completo
  3. Pipeline cURL passo a passo
  4. Gestão de erros em produção
  5. Otimização de custos
  6. Pontos-chave

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-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 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 > 0 antes 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