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

API de Lotes e Lista de Verificação para Produção

Aula 12 de 12 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. A Alternativa da API de Lotes: 20% de Desconto em Tokens
  2. Comparação de Abordagens
  3. Lista de Verificação para Produção
  4. Arquitetura Recomendada
  5. Pontos-chave
  6. Teste os Seus Conhecimentos

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 em asyncio.gather para 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_content está 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 GrokAsyncProcessor encapsula 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.