Limites de taxa e boas práticas
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, os exemplos seguem a API REST e o
xai-sdkoficial (client.batch.*; a API de Lotes da xAI não utiliza o 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.
Restrições que precisa de conhecer
A API de Lotes impõe limites técnicos que deve considerar na sua arquitetura. Ignorá-los leva a rejeições, cancelamento de lotes ou perda de resultados. Esta lição resume as restrições documentadas pela xAI e as boas práticas para uso em produção.
Limites de taxa
| Restrição | Valor | Âmbito |
|---|---|---|
| Criação de lotes | 2 por segundo | Por equipa |
| Número de lotes | Ilimitado | Por equipa |
| Chamadas de adição de pedidos | 1.000 por 30 segundos | Janela deslizante, partilhada por todos os lotes da equipa |
| Tamanho do pedido | 25 MB | Por pedido individual |
| Pedidos por lote | Teoricamente ilimitado | Acima de 100.000, o processamento pode ser mais lento |
Criação de lotes: o limite de 2 criações por segundo raramente é um problema, uma vez que geralmente cria um lote por operação.
Adição de pedidos: o limite aplica-se às chamadas, e cada chamada transporta uma lista de pedidos. Com blocos de 100 pedidos, isto já permite mais de 3.000 pedidos por segundo.
Tamanho do pedido: o limite de 25 MB afeta principalmente os pedidos carregados com imagens codificadas em base64; um pedido de texto raramente excede alguns quilobytes.
Por outro lado, os pedidos em lote não contam para os limites de taxa da API em tempo real: um lote grande não desacelera a sua aplicação interativa.
Limites de ficheiros JSONL
| Restrição | Valor |
|---|---|
| Pedidos por ficheiro | Máximo de 50.000 |
| Tamanho do ficheiro | Máximo de 200 MB |
| Adições após criação | Não é possível: o lote é selado |
Se o seu lote exceder estes limites, divida-o em vários ficheiros e crie um lote por ficheiro; agregará os resultados posteriormente.
Expiração de URL
As URLs assinadas para resultados de imagem e vídeo expiram após uma hora. Esta é a restrição mais crítica a gerir em produção: o seu processo de recuperação deve descarregar os média imediatamente, sem intervenção manual (a função telecharger_medias da lição 9). Para o lote, monitore também o expire_time, após o qual nenhum resultado está acessível.
Boas práticas de produção
IDs determinísticos
Derive os seus IDs de pedido (batch_request_id, ou custom_id no JSONL) a partir dos seus dados de entrada. Se precisar de reenviar um lote, os mesmos dados produzirão os mesmos IDs, o que facilita a deduplicação:
import hashlib
def identifiant_requete(document_id: str, operation: str) -> str:
"""Gera um ID de pedido determinístico."""
brut = f"{document_id}:{operation}"
return hashlib.sha256(brut.encode()).hexdigest()[:16]
Gestão de falhas parciais
Um lote totalmente processado pode ainda conter pedidos falhados. Verifique sempre cada resultado:
reussies, echouees = [], []
jeton = None
while True:
page = client.batch.list_batch_results(
batch_id=batch_id, limit=1000, pagination_token=jeton
)
reussies.extend(page.succeeded)
echouees.extend(page.failed)
if page.pagination_token is None:
break
jeton = page.pagination_token
if echouees:
print(f"{len(echouees)} pedidos falhados para reenviar num novo lote")
Acompanhamento de custos
Cada lote mantém o registo do seu custo total em ticks (dez mil milionésimos de um dólar):
batch = client.batch.get(batch_id=batch_id)
print("Custo total: %.4f $" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Através da API REST, o custo de cada pedido de texto aparece no seu resultado, no campo usage.cost_in_usd_ticks.
Registos e rastreabilidade
Registe cada operação para poder diagnosticar problemas:
import logging
logger = logging.getLogger("batch_api")
logger.info("Lote criado: %s", batch_id)
logger.info("Ficheiro carregado: %s, %d pedidos", file_id, len(documents))
logger.info("Resultados: %d bem-sucedidos, %d falhados", len(reussies), len(echouees))
Nova tentativa com recuo (backoff)
Para erros transitórios (tempo limite excedido, limite de taxa, erro de servidor), tente novamente com um atraso crescente:
import time
def appel_avec_retry(fonction, max_essais=3):
for essai in range(max_essais):
try:
return fonction()
except Exception as e:
if essai == max_essais - 1:
raise
attente = 2 ** essai
print(f"Tentativa novamente em {attente} s: {e}")
time.sleep(attente)
Lista de verificação pré-produção
Antes de implementar um pipeline da API de Lotes em produção, verifique:
- O modelo aceita processamento em lote e aparece na lista de modelos com desconto se o custo for relevante
- Os IDs dos pedidos são únicos e determinísticos
- O ficheiro JSONL é validado antes do carregamento (uma linha inválida cancela o lote)
- O descarregamento de resultados multimédia é automatizado, dentro de uma hora
- As falhas parciais são detetadas e reenviadas num novo lote
- Os resultados são recuperados antes do
expire_time - Os registos cobrem cada etapa do fluxo de trabalho
- A chave da API é lida a partir de uma variável de ambiente, nunca codificada diretamente
Pontos-chave
- Limites: 2 criações por segundo, 1.000 chamadas de adição de pedidos por 30 segundos, 25 MB por pedido
- Ficheiros JSONL: máximo de 50.000 pedidos e 200 MB, um lote por ficheiro
- URLs de imagem e vídeo expiram numa hora: descarregue imediatamente
- IDs determinísticos, verificação de cada resultado, acompanhamento de custos em ticks
- Registos, nova tentativa com recuo e um tempo limite máximo para produção
Teste os seus conhecimentos
Processamento em massa: a API de Lotes sem áreas cinzentas.
1. Quando é que a API de Lotes é a escolha certa?
Resposta: Para grandes volumes sem restrições de tempo real: classificação, enriquecimento, avaliações, geração em massa. Os pedidos em lote não contam para os limites de taxa, e os modelos de texto elegíveis beneficiam de um desconto de 20%.
2. Qual é o fluxo de trabalho de quatro etapas?
Resposta: Criar um lote nomeado, adicionar pedidos ao mesmo (através da API, ou criando o lote a partir de um ficheiro JSONL carregado), acompanhar os seus contadores e, em seguida, recuperar os resultados, à medida que chegam ou no final. O processamento inicia-se automaticamente, sem etapa de lançamento.
3. O que pode colocar num lote?
Resposta: Pedidos de Respostas (recomendado) e Conclusões de Chat (legado), com ferramentas de servidor e chamada de funções, bem como gerações e edições de imagem e vídeo, e extensões de vídeo. Apenas os tokens de texto para modelos elegíveis obtêm o desconto.
4. Como acompanha a execução?
Resposta: Através dos contadores do lote (num_pending, num_success, num_error…), do estado de cada pedido (pending, succeeded, failed, cancelled) e dos resultados paginados, que separam os sucessos das falhas. O lote está totalmente processado quando num_pending é zero.
5. Que boas práticas se aplicam aos limites?
Resposta: Adicione pedidos em blocos, divida ficheiros grandes num lote por ficheiro, descarregue os média dentro de uma hora, recupere os resultados antes do expire_time e reenvie as falhas num novo lote: conceba o lote como um pipeline robusto, não como uma submissão em massa cega.
Lotes bem formados, contadores acompanhados, falhas retomadas: a API de Lotes transforma volume em rotina, ao melhor custo.