Ir al contenido principal
Español— Elegir un idioma
Menú

Uso de semáforos para limitar peticiones concurrentes

Lección 4 de 12 Actualizado el 30 de julio de 2026 Avanzado
En esta página
  1. El problema de la concurrencia sin control
  2. Cómo funcionan los semáforos
  3. Patrón completo con el SDK de OpenAI
  4. Elección del valor correcto del semáforo
  5. Error común: semáforo global frente a local
  6. Puntos clave

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.

5
Peticiones paralelas recomendadas
429
Error de límite de tasa HTTP
RPM
Peticiones por minuto
TPM
Tokens por minuto

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