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

Cliente Assíncrono e Desempenho

Aula 10 de 14 Atualizada a 3 de novembro de 2026 Iniciante
Nesta página
  1. Otimize o Desempenho com Assincronia
  2. O Cliente AsyncOpenAI
  3. Pedidos Paralelos com asyncio.gather
  4. Controlo do Paralelismo
  5. Pipeline Assíncrono Completo
  6. Comparação entre Síncrono e Assíncrono
  7. Tratamento de Erros
  8. Pontos-chave

Atualizado em 3 de novembro de 2026 com base na página Rate limits da xAI e na referência da API de Imagens: os limites do modelo Imagine contam como pedidos por segundo — 6 no nível de entrada, 100 no nível mais alto — e não «30 por minuto»; um semáforo limita pedidos concorrentes, não a taxa de transferência; as imagens são produzidas em JPEG por padrão; e os tempos específicos da versão antiga, que não provinham de nenhuma medição publicada, dão lugar a um cálculo. Fontes: Rate limits · Images API.

Otimize o Desempenho com Assincronia

Quando precisa de gerar ou editar muitas imagens, as chamadas sequenciais tornam-se um gargalo. O cliente assíncrono da API da xAI permite-lhe executar múltiplos pedidos em paralelo, reduzindo significativamente o tempo total de processamento.

O Cliente AsyncOpenAI

A assincronia não torna uma única geração mais rápida: um pedido de imagem demora exatamente o mesmo tempo. O que elimina é a espera desnecessária entre pedidos — enquanto a primeira imagem é calculada no servidor, o seu programa pode solicitar outras dez em vez de ficar bloqueado. É por isso que o ganho é nulo para uma imagem e dramático para cinquenta.

from openai import AsyncOpenAI
import asyncio
import os

async_client = AsyncOpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)

async def generate_image(prompt):
    """Gera uma imagem de forma assíncrona."""
    response = await async_client.images.generate(
        model="grok-imagine-image",
        prompt=prompt,
        extra_body={"resolution": "1k"},
    )
    return response.data[0].url

async def main():
    url = await generate_image("A lighthouse on a cliff, watercolor style")
    print(url)

asyncio.run(main())

Pedidos Paralelos com asyncio.gather

O asyncio.gather lança todos os pedidos e aguarda que o conjunto termine. A duração total passa a ser a do pedido mais lento, e não a soma de todos — essa é toda a diferença, e nota-se logo com três ou quatro imagens.

async def generate_batch(prompts):
    """Gera imagens para múltiplos prompts em paralelo."""
    tasks = [generate_image(prompt) for prompt in prompts]
    results = await asyncio.gather(*tasks)
    return results

async def main():
    prompts = [
        "Portrait of an engineer, corporate style",
        "Panoramic view of a futuristic city",
        "Isometric diagram of a data center",
        "Abstract blue and silver logo",
        "Illustration of a team in a meeting"
    ]

    urls = await generate_batch(prompts)
    for prompt, url in zip(prompts, urls):
        print(f"{prompt[:40]}... → {url}")

asyncio.run(main())

Com cinco prompts, em vez de esperar que cada pedido termine antes de lançar o seguinte, todas as cinco imagens são calculadas ao mesmo tempo: o tempo total aproxima-se do do pedido mais lento.

Controlo do Paralelismo

Sem um limite, o gather lança tudo de uma vez — e cinquenta pedidos concorrentes num modelo limitado a 6 pedidos por segundo no nível de entrada produzem uma avalanche de erros 429 que lhe custam mais tempo do que a execução sequencial. O semáforo não é, portanto, uma precaução opcional: é o que torna o paralelismo utilizável. Calibre-o ao limite de taxa do modelo, nunca à capacidade da sua máquina.

async def generate_with_limit(prompts, max_concurrent=5):
    """Gera imagens com um número máximo de pedidos paralelos."""
    semaphore = asyncio.Semaphore(max_concurrent)

    async def limited_generate(prompt):
        async with semaphore:
            return await generate_image(prompt)

    tasks = [limited_generate(prompt) for prompt in prompts]
    return await asyncio.gather(*tasks)

As fichas oficiais para grok-imagine-image e grok-imagine-image-2.0 indicam 6 pedidos por segundo no nível de entrada, um limite que cresce com o nível da sua equipa até 100. Nota: um semáforo limita pedidos concorrentes, não a taxa de transferência. Com max_concurrent=5, mantém-se abaixo de 6 pedidos por segundo desde que cada geração dure mais de um segundo; se as suas respostas chegarem mais rápido, espace também os envios. Verifique os limites da sua equipa na consola da xAI antes de aumentar.

Pipeline Assíncrono Completo

Este pipeline encadeia as três operações que devem funcionar em conjunto: gerar, descarregar imediatamente — os URLs expiram — e isolar falhas. Num lote grande, este terceiro ponto faz a diferença entre um incidente e uma perda total.

import aiohttp
import aiofiles

async def download_image(session, url, filepath):
    """Descarrega uma imagem de forma assíncrona."""
    async with session.get(url) as resp:
        if resp.status == 200:
            async with aiofiles.open(filepath, "wb") as f:
                await f.write(await resp.read())
            return filepath
    return None

async def pipeline(prompts, output_dir="output"):
    """Pipeline completo: geração + descarregamento."""
    os.makedirs(output_dir, exist_ok=True)

    # Passo 1: gerar todas as imagens em paralelo
    urls = await generate_with_limit(prompts, max_concurrent=5)

    # Passo 2: descarregar todas as imagens em paralelo
    async with aiohttp.ClientSession() as session:
        download_tasks = []
        for i, url in enumerate(urls):
            if url:
                # JPEG por padrão (image/jpeg), salvo se a definição de qualidade produzir PNG
                filepath = os.path.join(output_dir, f"image_{i:03d}.jpg")
                download_tasks.append(download_image(session, url, filepath))

        saved_files = await asyncio.gather(*download_tasks)

    count = sum(1 for f in saved_files if f)
    print(f"{count}/{len(prompts)} imagens geradas e guardadas")

Comparação entre Síncrono e Assíncrono

O ganho calcula-se no papel. Se uma geração demorar T segundos, vinte imagens pedidas uma após a outra demoram cerca de 20 × T. Com cinco pedidos concorrentes, avançam em ondas de cinco: cerca de 4 × T, um ganho próximo de cinco, o número de pedidos concorrentes — desde que se mantenha abaixo do limite de taxa de transferência. Meça T na sua própria conta antes de prometer um prazo: as páginas de imagens da xAI não indicam tempo de geração, e este varia com o modelo, a resolução e a carga.

Tratamento de Erros

O comportamento padrão do gather é brutal: uma exceção numa tarefa propaga o erro e perde-se os resultados das outras, incluindo as já pagas. return_exceptions=True altera isso — cada tarefa devolve o seu resultado ou a sua exceção, e decide o que fazer com as falhas sem sacrificar os sucessos.

async def safe_generate(prompt):
    """Gera uma imagem com tratamento de erros."""
    try:
        return await generate_image(prompt)
    except Exception as e:
        print(f"Erro para '{prompt[:30]}...' : {e}")
        return None

Pontos-chave

  • O cliente AsyncOpenAI permite pedidos paralelos via asyncio
  • Utilize asyncio.gather para lançar múltiplas gerações simultaneamente
  • Limite a concorrência com um semáforo para respeitar os limites de taxa
  • O ganho aproxima-se do número de pedidos concorrentes, dentro do limite de taxa de transferência autorizado (6 pedidos por segundo no nível de entrada)
  • Trate os erros individualmente para evitar perder todo o lote