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

Limites de taxa e boas práticas

Aula 12 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Restrições que precisa de conhecer
  2. Limites de taxa
  3. Limites de ficheiros JSONL
  4. Expiração de URL
  5. Boas práticas de produção
  6. Lista de verificação pré-produção
  7. Pontos-chave
  8. Teste os seus conhecimentos

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-sdk oficial (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çãoValorÂmbito
Criação de lotes2 por segundoPor equipa
Número de lotesIlimitadoPor equipa
Chamadas de adição de pedidos1.000 por 30 segundosJanela deslizante, partilhada por todos os lotes da equipa
Tamanho do pedido25 MBPor pedido individual
Pedidos por loteTeoricamente ilimitadoAcima 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çãoValor
Pedidos por ficheiroMáximo de 50.000
Tamanho do ficheiroMáximo de 200 MB
Adições após criaçãoNã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.