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

asyncio.gather para el procesamiento por lotes

Lección 5 de 12 Actualizado el 30 de julio de 2026 Avanzado
En esta página
  1. Orquestación de solicitudes paralelas
  2. Sintaxis básica
  3. Patrón completo: lote con semáforo
  4. Gestión de errores en un lote
  5. División en sublotes (fragmentación)
  6. Seguimiento del progreso
  7. Puntos clave

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 original
  • return_exceptions=True evita que un único error falle todo el lote
  • La fragmentación permite manejar volúmenes muy grandes sin saturar la memoria
  • Combina siempre gather con un semáforo para respetar los límites de tasa
  • Añade seguimiento del progreso para procesos de larga duración