Utilizar Semáforos para Limitar Pedidos Concorrentes
Nesta página
O problema da concorrência descontrolada
Disparar todos os seus pedidos em paralelo sem limites é um erro comum. Se tiver 200 perguntas para processar e as lançar todas simultaneamente, irá atingir os limites de taxa da API, receber erros HTTP 429 e, potencialmente, ter a sua chave de API bloqueada temporariamente.
Um semáforo é a solução padrão para controlar o número de pedidos concorrentes. Funciona como um contador que permite executar um número máximo de corrotinas em paralelo.
Como funcionam os semáforos
O asyncio.Semaphore atua como um bloqueio de contador. Quando uma corrotina entra no bloco async with semaphore, o contador diminui. Quando sai, o contador aumenta. Se o contador atingir zero, as corrotinas subsequentes aguardam até que se liberte uma vaga.
import asyncio
from asyncio import Semaphore
semaphore = Semaphore(5) # máximo de 5 pedidos simultâneos
async def process_request(request: str):
async with semaphore:
# Esta secção está limitada a 5 execuções paralelas
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
max_tokens=100
)
chat.append(user(request))
return await chat.sample()
Neste exemplo, mesmo que lance 100 corrotinas com asyncio.gather, apenas 5 serão executadas simultaneamente. As outras 95 aguardarão a sua vez.
Padrão completo com o SDK da OpenAI
Eis o mesmo padrão utilizando AsyncOpenAI, que é frequentemente preferido por questões de compatibilidade:
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 send_request(sem: Semaphore, request: str) -> dict:
async with sem:
return await client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[{"role": "user", "content": request}]
)
async def process_all(requests: list[str], max_concurrent: int = 5):
sem = Semaphore(max_concurrent)
tasks = [send_request(sem, r) for r in requests]
return await asyncio.gather(*tasks)
O parâmetro max_concurrent é configurável. Defina-o com base nos seus limites de taxa (lição 7).
Escolher o valor correto do semáforo
Calcule o valor ótimo a partir dos seus limites de taxa, mas não diretamente: deve fatorizar a duração do pedido. Se o seu plano permitir 60 RPM e cada pedido demorar cerca de 10 segundos, um semáforo de 5 produzirá no máximo 5 pedidos simultâneos, ou seja, cerca de 30 pedidos por minuto — confortavelmente abaixo do limite. Aplique este raciocínio (limite RPM × duração média ÷ 60) ao seu caso específico. Isto explica por que os modelos de raciocínio exigem um semáforo mais baixo: os seus pedidos demoram mais tempo, pelo que, com igual concorrência, o throughput por minuto diminui e o risco de saturação momentânea aumenta. Na dúvida, a abordagem empírica é a mais segura: comece baixo, entre 3 e 5, observe a taxa de erro 429 e aumente gradualmente até encontrar o equilíbrio entre throughput e estabilidade.
Cálculo aproximado
Pedidos por minuto = semáforo * (60 / duração_média_segundos)
Exemplo: semáforo=5, duração=10s → 5 * (60/10) = 30 RPM
Exemplo: semáforo=10, duração=5s → 10 * (60/5) = 120 RPM
Erro comum: semáforo global vs. local
# MAU: novo semáforo em cada chamada
async def bad_request(request: str):
sem = Semaphore(5) # cada chamada cria o seu próprio semáforo
async with sem:
return await client.chat.completions.create(...)
# BOM: semáforo partilhado entre todas as chamadas
sem = Semaphore(5)
async def good_request(request: str):
async with sem:
return await client.chat.completions.create(...)
O semáforo deve ser partilhado entre todas as corrotinas. Se o criar localmente dentro de cada função, cada corrotina terá o seu próprio semáforo e o limite não funcionará.
Pontos-chave
- Um semáforo limita o número de pedidos de API simultâneos para respeitar os limites de taxa
- Utilize
async with semaphorepara proteger as chamadas à API - Comece com um valor entre 3 e 5 e ajuste com base nos seus limites de RPM
- O semáforo deve ser partilhado (global ou passado como parâmetro), nunca criado localmente
- A fórmula
RPM = semáforo * (60 / duração_média)ajuda a dimensionar o valor