API de Lotes e Lista de Verificação para Produção
Nesta página
A Alternativa da API de Lotes: 20% de Desconto em Tokens
Quando o processamento em tempo real não é um requisito, a API de Lotes da xAI oferece uma redução de 20% em todos os tokens para modelos de texto elegíveis (do grok-4.3 ao grok-4.7, conforme 2 de novembro de 2026, de acordo com preços da API de lotes da xAI). Em vez de enviar pedidos um a um e gerir a concorrência, submete os seus pedidos em lotes através da API ou num ficheiro JSONL, e recupera os resultados à medida que o processamento termina — normalmente no prazo de 24 horas. Os pedidos em lote não contam para os limites de taxa. O curso API de Lotes: Processamento em Massa detalha o fluxo de trabalho.
Quando Utilizar a API de Lotes
- Processamento de catálogos de produtos (milhares de descrições)
- Classificação em massa de tickets de suporte
- Geração de resumos para uma base documental
- Qualquer tarefa onde um atraso de algumas horas seja aceitável
Quando Manter o Assíncrono Clássico
- Chatbot interativo (resposta em tempo real)
- Pipeline onde cada passo depende do anterior
- Monitorização e alertas em tempo real
- Qualquer caso em que o atraso da API de Lotes seja inaceitável
Comparação de Abordagens
| Critério | Assíncrono + Semáforo | API de Lotes |
|---|---|---|
| Custo | Tarifa padrão | -20% em tokens para modelos elegíveis |
| Latência | Segundos a minutos | Minutos a horas |
| Controlo | Tempo real, erros imediatos | Resultados à medida que o processamento termina, erros por pedido |
| Complexidade | Semáforo, backoff, gather | Lote de pedidos ou ficheiro JSONL, rastreio de contadores |
| Limites de taxa | Sujeito a RPM/TPM | Gerido pela xAI |
Lista de Verificação para Produção
Antes de implementar o seu sistema de pedidos assíncronos em produção, verifique todos os pontos desta lista:
Configuração
- O tempo limite (timeout) está definido para 3600 segundos para modelos de raciocínio
- O semáforo está dimensionado com base nos seus limites de taxa reais (não em estimativas)
- O backoff exponencial está implementado com jitter para erros 429
- As chaves de API são carregadas a partir de variáveis de ambiente, nunca codificadas diretamente no código
- O cabeçalho
x-grok-conv-idé utilizado para conversas multi-turno
Gestão de Erros
return_exceptions=Trueé utilizado emasyncio.gatherpara isolar erros- Erros 429, de tempo limite e de ligação desencadeiam uma nova tentativa
- Erros de pedido inválido (
BadRequestError) não desencadeiam uma nova tentativa - Pedidos falhados são identificados e podem ser repetidos
- Os registos (logs) incluem o tipo de erro, o número da tentativa e o atraso da nova tentativa
Monitorização
- O número de tokens consumidos é rastreado via
response.usage - A taxa de acertos da cache é medida para validar o uso de
x-grok-conv-id - Os custos são estimados em tempo real com
cost_in_usd_ticks - Os limites de taxa restantes são monitorizados para ajustar o semáforo dinamicamente
Desempenho
- O fracionamento (chunking) é utilizado para lotes superiores a 100 pedidos
- Os resultados intermédios são guardados entre sub-lotes
- O progresso é exibido para tarefas de longa duração
- O semáforo é ajustado com base no modelo utilizado (raciocínio = menor)
Segurança
- As chaves de API não são expostas em registos ou mensagens de erro
- Respostas contendo dados sensíveis são processadas na memória, não escritas no disco
- O armazenamento remoto (
store_messages) está desativado para dados confidenciais use_encrypted_contentestá ativado quando é necessária confidencialidade no raciocínio
Arquitetura Recomendada
import os
import asyncio
import uuid
from asyncio import Semaphore
from openai import AsyncOpenAI, RateLimitError, APITimeoutError
import httpx
class GrokAsyncProcessor:
def __init__(self, max_concurrent: int = 5):
self.client = AsyncOpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1",
timeout=httpx.Timeout(3600.0)
)
self.sem = Semaphore(max_concurrent)
self.conv_id = str(uuid.uuid4())
async def request(self, prompt: str, max_retries: int = 5) -> str:
async with self.sem:
for attempt in range(max_retries):
try:
response = await self.client.chat.completions.create(
model="grok-4.5",
messages=[{"role": "user", "content": prompt}],
extra_headers={"x-grok-conv-id": self.conv_id}
)
return response.choices[0].message.content
except RateLimitError:
if attempt == max_retries - 1:
raise
await asyncio.sleep(2 ** attempt)
except APITimeoutError:
if attempt == max_retries - 1:
raise
await asyncio.sleep(2 ** attempt)
async def batch(self, prompts: list[str]) -> list[str | Exception]:
tasks = [self.request(p) for p in prompts]
return await asyncio.gather(*tasks, return_exceptions=True)
Esta classe encapsula todos os padrões abordados neste curso: cliente assíncrono, semáforo, backoff, cache e gestão de erros. Fornece um ponto de partida sólido para os seus projetos de produção.
Pontos-chave
- A API de Lotes oferece 20% de desconto em modelos elegíveis, mas impõe um atraso de processamento
- Escolha entre assíncrono em tempo real e lotes com base nas suas restrições de latência
- A lista de verificação para produção abrange configuração, erros, monitorização, desempenho e segurança
- A classe
GrokAsyncProcessorencapsula todos os padrões do curso numa única abstração - Teste sempre a sua configuração com um pequeno lote antes de lançar o processamento em massa
Teste os Seus Conhecimentos
Assíncrono, limites, cache: padrões de produção em cinco perguntas.
1. Quando é que o assíncrono prevalece sobre o síncrono?
Resposta: Sempre que lidar com múltiplos pedidos independentes: o AsyncClient (ou AsyncOpenAI) sobrepõe as esperas de rede — o throughput multiplica-se sem multiplicar as threads.
2. Como processar um lote sem atingir os limites?
Resposta: asyncio.gather para paralelismo, um semáforo para limitar pedidos concorrentes e backoff exponencial em HTTP 429 — respeitando os limites RPM/TPM da consola.
3. Como gerir o contexto multi-turno à escala?
Resposta: Através do armazenamento de respostas no lado do servidor e reutilização do raciocínio encriptado — o estado vive no lado da API, o seu código apenas rastreia identificadores.
4. O que precisa de saber sobre cache e tempos limite?
Resposta: A cache de conversação (x-grok-conv-id) acelera threads seguidas, e os pedidos de raciocínio exigem tempos limite adaptados — duas definições que transformam a produção.
5. O que contém a lista de verificação de produção do curso?
Resposta: Assíncrono dominado, limites respeitados (semáforo + backoff), lotes para volume frio, tempos limite e novas tentativas configurados, custos rastreados — robustez como uma lista de verificação.
Concorrência limitada, falhas planeadas, estado no lado do servidor: os padrões assíncronos transformam os seus scripts em serviços — a lista de verificação final garante a sua estabilidade.