asyncio.gather para Processamento em Lote
Nesta página
Orquestração de Pedidos Paralelos
asyncio.gather é a função central para executar múltiplas corrotinas em paralelo e recolher todos os resultados. Quando combinada com um semáforo, permite processar lotes de pedidos de forma eficiente, respeitando os limites da API.
Sintaxe Básica
import asyncio
requests = ["Question 1", "Question 2", "Question 3"]
tasks = [process_request(r) for r in requests]
responses = await asyncio.gather(*tasks)
asyncio.gather aceita um número variável de corrotinas (daí o uso de *tasks para desempacotar a lista) e devolve uma lista de resultados pela mesma ordem em que as tarefas foram submetidas. Este é um ponto importante: mesmo que a pergunta 3 termine antes da pergunta 1, responses[0] conterá sempre o resultado da pergunta 1.
Padrão Completo: Lote com Semáforo
Eis o padrão que utilizará com maior frequência em produção:
import os
from asyncio import Semaphore
from openai import AsyncOpenAI
import httpx
client = AsyncOpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1",
timeout=httpx.Timeout(3600.0)
)
async def process_batch(prompts: list[str], max_concurrent: int = 5) -> list[str]:
sem = Semaphore(max_concurrent)
async def single_request(prompt: str) -> str:
async with sem:
response = await client.chat.completions.create(
model="grok-4.5",
messages=[{"role": "user", "content": prompt}]
)
return response.choices[0].message.content
tasks = [single_request(p) for p in prompts]
return await asyncio.gather(*tasks)
Este padrão encapsula o semáforo dentro da função de lote. Basta chamar process_batch(prompts) e obter a lista de respostas.
Gestão de Erros num Lote
Por predefinição, se uma única corrotina levantar uma exceção, asyncio.gather cancela tudo e propaga o erro. O parâmetro return_exceptions=True altera este comportamento:
async def safe_batch(prompts: list[str]) -> list[str | Exception]:
sem = Semaphore(5)
async def single_request(prompt: str) -> str:
async with sem:
response = await client.chat.completions.create(
model="grok-4.5",
messages=[{"role": "user", "content": prompt}]
)
return response.choices[0].message.content
tasks = [single_request(p) for p in prompts]
results = await asyncio.gather(*tasks, return_exceptions=True)
return results
# Utilização
results = await safe_batch(mes_prompts)
for i, result in enumerate(results):
if isinstance(result, Exception):
print(f"Error on prompt {i}: {result}")
else:
print(f"Result {i}: {result[:100]}...")
Com return_exceptions=True, os erros são capturados como valores na lista de resultados. Pode, assim, identificar e repetir os pedidos falhados.
Divisão em Sub-lotes (Chunking)
Para volumes muito elevados, é preferível dividir em sub-lotes em vez de lançar milhares de tarefas simultaneamente:
async def chunked_batch(
prompts: list[str],
chunk_size: int = 50,
max_concurrent: int = 5
) -> list[str]:
all_results = []
for i in range(0, len(prompts), chunk_size):
chunk = prompts[i:i + chunk_size]
print(f"Processing batch {i//chunk_size + 1} ({len(chunk)} prompts)")
results = await process_batch(chunk, max_concurrent)
all_results.extend(results)
return all_results
O «chunking» oferece várias vantagens: permite apresentar o progresso, guardar resultados intermédios e limitar o uso de memória. Se um sub-lote falhar, não perde os resultados dos sub-lotes anteriores.
Acompanhamento do Progresso
Para lotes de grandes dimensões, um indicador de progresso é útil:
import asyncio
from asyncio import Semaphore
async def batch_with_progress(prompts: list[str], max_concurrent: int = 5) -> list[str]:
sem = Semaphore(max_concurrent)
completed = 0
total = len(prompts)
async def single_request(prompt: str) -> str:
nonlocal completed
async with sem:
response = await client.chat.completions.create(
model="grok-4.5",
messages=[{"role": "user", "content": prompt}]
)
completed += 1
print(f"\r{completed}/{total} completed", end="", flush=True)
return response.choices[0].message.content
tasks = [single_request(p) for p in prompts]
results = await asyncio.gather(*tasks)
print() # nova linha após o progresso
return results
Pontos-chave
asyncio.gather(*tasks)executa corrotinas em paralelo e devolve os resultados pela ordem originalreturn_exceptions=Trueimpede que um único erro falhe todo o lote- O «chunking» permite lidar com volumes muito elevados sem saturar a memória
- Combine sempre
gathercom um semáforo para respeitar os limites de taxa - Adicione acompanhamento de progresso para processos de longa duração