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

Utilizar Semáforos para Limitar Pedidos Concorrentes

Aula 4 de 12 Atualizada a 30 de julho de 2026 Avancado
Nesta página
  1. O problema da concorrência descontrolada
  2. Como funcionam os semáforos
  3. Padrão completo com o SDK da OpenAI
  4. Escolher o valor correto do semáforo
  5. Erro comum: semáforo global vs. local
  6. Pontos-chave

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.

5
Pedidos paralelos recomendados
429
Erro de limite de taxa HTTP
RPM
Pedidos por minuto
TPM
Tokens por minuto

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 semaphore para 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