Skills: Procesamiento Asíncrono y Concurrente

Cuando un Skill necesita esperar simultáneamente múltiples operaciones que consumen tiempo (como solicitudes de red, E/S de archivos), la programación asíncrona puede reducir significativamente el tiempo total de espera.

Este artículo presenta los escenarios de aplicación y la sintaxis de Python asyncio en los scripts de Skill.


Síncrono vs Asíncrono: Cuándo usar asíncrono

EscenarioMétodo recomendadoRazón
Procesamiento de un solo archivo, llamada única a APISíncronoEl beneficio de lo asíncrono no es evidente, el código es más simple
Enviar múltiples solicitudes HTTP al mismo tiempoAsíncronoEspera concurrente, tiempo total ≈ tiempo individual más largo
Leer múltiples archivos al mismo tiempoAsíncrono o grupo de hilosSe pueden cambiar de tareas durante la espera de E/S
Cálculo intensivo de CPU (como procesamiento de imágenes)Multiprocesoasyncio no evita el GIL

Asíncrono no es igual a paralelo. El asyncio de Python es un bucle de eventos de un solo hilo, adecuado para tareas intensivas en E/S (espera de red, disco). Las tareas intensivas en CPU deberían usarProcessPoolExecutor。


Envío asíncrono de múltiples solicitudes HTTP

Supongamos que un Skill necesita llamar a 3 interfaces de API al mismo tiempo. El tiempo total del método síncrono es la suma de las tres solicitudes, mientras que el tiempo total del método asíncrono es aproximadamente igual al más lento.

Ejemplo

# Ruta de archivo: scripts/async_requests.py
# Llamada asíncrona concurrente a múltiples APIs, recopilando resultados

import asyncio
import aiohttp      # pip install aiohttp --break-system-packages
import json
import sys
import time

API_KEY  = "your_api_key"
BASE_URL = "https://api.example.com/v1"

async def fetch_one(session: aiohttp.ClientSession,
                    endpoint: str, payload: dict) -> dict:
    """Envía asíncronamente una única solicitud POST"""
    url     = BASE_URL + endpoint
    headers = {"Authorization": f"Bearer {API_KEY}"}
    try:
        async with session.post(url, json=payload,
                                headers=headers, timeout=aiohttp.ClientTimeout(total=30)) as resp:
            resp.raise_for_status()
            return {"endpoint": endpoint, "status": "ok", "data": await resp.json()}
    except Exception as e:
        return {"endpoint": endpoint, "status": "error", "message": str(e)}

async def fetch_all(requests: list) -> list:
    """
Enviar todas las solicitudes de forma concurrente y esperar a que todas se completen

Parámetros:
requests: lista, cada elemento es una tupla (endpoint, payload)
    """

    async with aiohttp.ClientSession() as session:
        tasks = [
            fetch_one(session, endpoint, payload)
            for endpoint, payload in requests
        ]
        # gather ejecuta todas las tareas de forma concurrente; return_exceptions=True evita que un fallo afecte a las demás
        return await asyncio.gather(*tasks, return_exceptions=True)

def main():
    # Definir la lista de solicitudes que se llamarán de forma concurrente
    requests = [
        ("/summarize", {"text": "ejemplo es una plataforma de aprendizaje técnico", "lang": "zh"}),
        ("/keywords",  {"text": "EJEMPLO ofrece varios tutoriales de programación", "top_n": 5}),
        ("/sentiment", {"text": "Los tutoriales de esta plataforma son de alta calidad"}),
    ]

    t0      = time.perf_counter()
    results = asyncio.run(fetch_all(requests))
    elapsed = time.perf_counter() - t0

    print(f"Se completaron {len(results)} solicitudes de forma concurrente, tiempo total {elapsed:.2f} segundos")
    print(json.dumps(results, ensure_ascii=False, indent=2))

if __name__ == "__main__":
    main()
并发完成 3 个请求,总耗时 1.23 秒
(同步串行约需 3.5 秒,并发节省约 65% 时间)

Lectura asíncrona de múltiples archivos

Para escenarios donde se necesitan leer múltiples archivos al mismo tiempo,aiofilesse proporciona la versión asíncrona de E/S de archivos.

Ejemplo

# Ruta de archivo: scripts/async_file_reader.py
import asyncio
import aiofiles   # pip install aiofiles --break-system-packages
import os

async def read_file(file_path: str) -> dict:
    """Lee asíncronamente un solo archivo"""
    try:
        async with aiofiles.open(file_path, encoding="utf-8") as f:
            content = await f.read()
        return {
            "file":    os.path.basename(file_path),
            "chars":   len(content),
            "lines":   content.count("\n"),
            "status":  "ok"
        }
    except Exception as e:
        return {"file": file_path, "status": "error", "message": str(e)}

async def read_all_files(file_paths: list) -> list:
    """Lee todos los archivos de forma concurrente"""
    tasks = [read_file(fp) for fp in file_paths]
    return await asyncio.gather(*tasks)

if __name__ == "__main__":
    import glob, json
    # Leer todos los archivos .txt en el directorio de carga
    files = glob.glob("/mnt/user-data/uploads/*.txt")
    if not files:
        print("No se encontraron archivos .txt")
    else:
        results = asyncio.run(read_all_files(files))
        print(json.dumps(results, ensure_ascii=False, indent=2))

Control de tiempo de espera y cancelación de tareas

En las tareas asíncronas, el control de tiempo de espera es especialmente importante.asyncio.wait_forSe puede establecer un tiempo máximo de espera para una tarea individual.

Ejemplo

# Ruta de archivo: scripts/async_timeout.py
import asyncio

async def slow_task(name: str, delay: float) -> str:
    """Simula una tarea que consume tiempo"""
    await asyncio.sleep(delay)
    return f"{name} completado"

async def run_with_timeout():
    tasks = {
        "Tarea rápida": slow_task("Tarea rápida", 0.5),
        "Tarea lenta": slow_task("Tarea lenta", 5.0),
    }
    results = {}
    for name, coro in tasks.items():
        try:
            # Cada tarea espera como máximo 2 segundos
            result = await asyncio.wait_for(coro, timeout=2.0)
            results[name] = {"status": "ok", "result": result}
        except asyncio.TimeoutError:
            results[name] = {"status": "timeout", "message": "No se completó en más de 2 segundos"}
    return results

if __name__ == "__main__":
    import json
    output = asyncio.run(run_with_timeout())
    print(json.dumps(output, ensure_ascii=False, indent=2))
{
  "快速任务": {"status": "ok",      "result": "快速任务 完成"},
  "慢速任务": {"status": "timeout", "message": "超过 2 秒未完成"}
}

Explicar en SKILL.md cómo invocar scripts asíncronos

## 并发 API 调用

当用户提供多个文本需要同时分析时,运行异步脚本以提升速度:

```bash
python scripts/async_requests.py
```

该脚本会并发发出所有请求,总耗时约等于最慢的单次请求,
而非所有请求的时间之和。
Otras extensiones