asyncio.gather para el procesamiento por lotes
En esta página
Orquestación de solicitudes paralelas
asyncio.gather es la función principal para ejecutar múltiples corrutinas en paralelo y recopilar todos los resultados. Combinada con un semáforo, te permite procesar lotes de solicitudes de forma eficiente respetando los límites de la API.
Sintaxis 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 acepta un número variable de corrutinas (de ahí el uso de *tasks para desempaquetar la lista) y devuelve una lista de resultados en el mismo orden en que se enviaron las tareas. Este es un punto importante: aunque la pregunta 3 termine antes que la pregunta 1, responses[0] contendrá siempre el resultado de la pregunta 1.
Patrón completo: lote con semáforo
Este es el patrón que usarás con mayor frecuencia en producción:
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 patrón encapsula el semáforo dentro de la función de lote. Solo necesitas llamar a process_batch(prompts) y recuperar la lista de respuestas.
Gestión de errores en un lote
Por defecto, si una sola corrutina lanza una excepción, asyncio.gather cancela todo y propaga el error. El parámetro return_exceptions=True modifica este comportamiento:
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
# Uso
results = await safe_batch(mes_prompts)
for i, result in enumerate(results):
if isinstance(result, Exception):
print(f"Error en el prompt {i}: {result}")
else:
print(f"Resultado {i}: {result[:100]}...")
Con return_exceptions=True, los errores se capturan como valores dentro de la lista de resultados. De este modo, puedes identificar y reintentar las solicitudes fallidas.
División en sublotes (fragmentación)
Para volúmenes muy grandes, es preferible dividir el trabajo en sublotes en lugar de lanzar miles de tareas simultáneamente:
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"Procesando lote {i//chunk_size + 1} ({len(chunk)} prompts)")
results = await process_batch(chunk, max_concurrent)
all_results.extend(results)
return all_results
La fragmentación ofrece varias ventajas: puedes mostrar el progreso, guardar resultados intermedios y limitar el uso de memoria. Si falla un sublote, no pierdes los resultados de los sublotes anteriores.
Seguimiento del progreso
Para lotes grandes, resulta útil un indicador de progreso:
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} completados", end="", flush=True)
return response.choices[0].message.content
tasks = [single_request(p) for p in prompts]
results = await asyncio.gather(*tasks)
print() # nueva línea tras el progreso
return results
Puntos clave
asyncio.gather(*tasks)ejecuta corrutinas en paralelo y devuelve los resultados en el orden originalreturn_exceptions=Trueevita que un único error falle todo el lote- La fragmentación permite manejar volúmenes muy grandes sin saturar la memoria
- Combina siempre
gathercon un semáforo para respetar los límites de tasa - Añade seguimiento del progreso para procesos de larga duración