Uso de semáforos para limitar peticiones concurrentes
En esta página
El problema de la concurrencia sin control
Lanzar todas tus peticiones en paralelo sin límites es un error común. Si tienes 200 preguntas que procesar y las lanzas todas simultáneamente, alcanzarás los límites de tasa de la API, recibirás errores HTTP 429 y, posiblemente, tu clave de API quede bloqueada temporalmente.
Un semáforo es la solución estándar para controlar el número de peticiones concurrentes. Se trata de un contador que permite que un número máximo de corrutinas se ejecuten en paralelo.
Cómo funcionan los semáforos
asyncio.Semaphore actúa como un bloqueo por contador. Cuando una corrutina entra en el bloque async with semaphore, el contador disminuye. Cuando sale, el contador aumenta. Si el contador llega a cero, las corrutinas siguientes esperan hasta que se libere un hueco.
import asyncio
from asyncio import Semaphore
semaphore = Semaphore(5) # máximo 5 peticiones simultáneas
async def process_request(request: str):
async with semaphore:
# Esta sección está limitada a 5 ejecuciones paralelas
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
max_tokens=100
)
chat.append(user(request))
return await chat.sample()
En este ejemplo, aunque lances 100 corrutinas con asyncio.gather, solo 5 se ejecutarán simultáneamente. Las otras 95 esperarán su turno.
Patrón completo con el SDK de OpenAI
Aquí tienes el mismo patrón usando AsyncOpenAI, que suele preferirse por su compatibilidad:
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)
El parámetro max_concurrent es configurable. Ajústalo en función de tus límites de tasa (lección 7).
Elección del valor correcto del semáforo
Calcula el valor óptimo a partir de tus límites de tasa, pero no directamente: debes tener en cuenta la duración de la petición. Si tu plan permite 60 RPM y cada petición tarda unos 10 segundos, un semáforo de 5 produce como máximo 5 peticiones simultáneas, es decir, unas 30 peticiones por minuto, quedando cómodamente por debajo del límite. Aplica este razonamiento (límite RPM × duración media ÷ 60) a tu propio caso. Esto explica por qué los modelos de razonamiento requieren un semáforo más bajo: sus peticiones tardan más, por lo que, con la misma concurrencia, el rendimiento por minuto cae y aumenta el riesgo de saturación momentánea. En caso de duda, el enfoque empírico es el más seguro: empieza con un valor bajo, entre 3 y 5, observa la tasa de errores 429 y aumenta gradualmente hasta encontrar el equilibrio entre rendimiento y estabilidad.
Cálculo aproximado
Peticiones por minuto = semáforo * (60 / duración_media_segundos)
Ejemplo: semáforo=5, duración=10s → 5 * (60/10) = 30 RPM
Ejemplo: semáforo=10, duración=5s → 10 * (60/5) = 120 RPM
Error común: semáforo global frente a local
# MAL: nuevo semáforo en cada llamada
async def bad_request(request: str):
sem = Semaphore(5) # cada llamada crea su propio semáforo
async with sem:
return await client.chat.completions.create(...)
# BIEN: semáforo compartido entre todas las llamadas
sem = Semaphore(5)
async def good_request(request: str):
async with sem:
return await client.chat.completions.create(...)
El semáforo debe ser compartido por todas las corrutinas. Si lo creas localmente dentro de cada función, cada corrutina tendrá su propio semáforo y el límite no funcionará.
Puntos clave
- Un semáforo limita el número de peticiones simultáneas a la API para respetar los límites de tasa
- Usa
async with semaphorepara proteger las llamadas a la API - Empieza con un valor de 3 a 5 y ajústalo según tus límites RPM
- El semáforo debe ser compartido (global o pasado como parámetro), nunca creado localmente
- La fórmula
RPM = semáforo * (60 / duración_media)ayuda a dimensionar el valor