Traitement asynchrone et concurrent des compétences

Lorsqu'une compétence doit attendre simultanément plusieurs opérations chronophages (comme des requêtes réseau, des E/S de fichiers), la programmation asynchrone peut réduire considérablement le temps d'attente total.

Cet article présente les scénarios d'application et les modèles de codage de Python asyncio dans les scripts de compétences.


Synchrone vs asynchrone : quand utiliser l'asynchrone

ScénarioApproche recommandéeRaison
Traitement d'un seul fichier, un seul appel APISynchroneLes avantages de l'asynchrone ne sont pas évidents ; le code est plus simple
Envoyer plusieurs requêtes HTTP simultanémentAsynchroneAttente concurrente, temps total ≈ temps de la plus longue requête unique
Lire plusieurs fichiers simultanémentAsynchrone ou pool de threadsLes tâches peuvent être commutées pendant l'attente d'E/S
Calcul intensif en CPU (par ex., traitement d'images)Multiprocessingasyncio ne contourne pas le GIL

L'asynchrone n'est pas équivalent au parallélisme. L'asyncio de Python est une boucle d'événements monothread, adaptée aux tâches intensives en E/S (attente réseau, disque). Les tâches intensives en CPU devraient utiliserProcessPoolExecutor。


Envoyer plusieurs requêtes HTTP de manière asynchrone

Supposons qu'une Skill doive appeler 3 points de terminaison d'API simultanément. En mode synchrone, le temps total est la somme des trois requêtes ; en mode asynchrone, le temps total est approximativement égal à celui de la plus lente.

Exemple

# Chemin du fichier : scripts/async_requests.py
# Appeler plusieurs API de manière asynchrone et concurrente, puis agréger les résultats

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:
    """Envoyer une seule requête POST de manière asynchrone"""
    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:
    """
Envoyer toutes les requêtes simultanément et attendre que toutes soient terminées

Paramètres :
requests : list, chaque élément est un tuple (endpoint, payload)
    """

    async with aiohttp.ClientSession() as session:
        tasks = [
            fetch_one(session, endpoint, payload)
            for endpoint, payload in requests
        ]
        # gather exécute toutes les tâches simultanément ; return_exceptions=True empêche qu'un échec affecte les autres
        return await asyncio.gather(*tasks, return_exceptions=True)

def main():
    # Définir la liste des requêtes à appeler simultanément
    requests = [
        ("/summarize", {"text": "Example est une plateforme d'apprentissage technologique", "lang": "zh"}),
        ("/keywords",  {"text": "EXAMPLE propose divers tutoriels de programmation", "top_n": 5}),
        ("/sentiment", {"text": "Les tutoriels sur cette plateforme sont de haute qualité"}),
    ]

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

    print(f"{len(results)} requêtes terminées simultanément, temps total {elapsed:.2f} secondes")
    print(json.dumps(results, ensure_ascii=False, indent=2))

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

Lire plusieurs fichiers de manière asynchrone

Pour les scénarios où plusieurs fichiers doivent être lus simultanément,aiofilesfournit une version asynchrone des E/S de fichiers.

Exemple

# Chemin du fichier : 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:
    """Lire un seul fichier de manière asynchrone"""
    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:
    """Lire tous les fichiers simultanément"""
    tasks = [read_file(fp) for fp in file_paths]
    return await asyncio.gather(*tasks)

if __name__ == "__main__":
    import glob, json
    # Lire tous les fichiers .txt dans le répertoire de téléversement
    files = glob.glob("/mnt/user-data/uploads/*.txt")
    if not files:
        print("Aucun fichier .txt trouvé")
    else:
        results = asyncio.run(read_all_files(files))
        print(json.dumps(results, ensure_ascii=False, indent=2))

Contrôle des délais d'attente et annulation des tâches

Dans les tâches asynchrones, le contrôle des délais d'attente est particulièrement important.asyncio.wait_forVous pouvez définir un temps d'attente maximal pour une tâche unique.

Exemple

# Chemin du fichier : scripts/async_timeout.py
import asyncio

async def slow_task(name: str, delay: float) -> str:
    """Simuler une tâche chronophage"""
    await asyncio.sleep(delay)
    return f"{name} terminé"

async def run_with_timeout():
    tasks = {
        "Tâche rapide": slow_task("Tâche rapide", 0.5),
        "Tâche lente": slow_task("Tâche lente", 5.0),
    }
    results = {}
    for name, coro in tasks.items():
        try:
            # Attendre au plus 2 secondes pour chaque tâche
            result = await asyncio.wait_for(coro, timeout=2.0)
            results[name] = {"status": "ok", "result": result}
        except asyncio.TimeoutError:
            results[name] = {"status": "timeout", "message": "Non terminé dans les 2 secondes"}
    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 秒未完成"}
}

Expliquer comment invoquer des scripts asynchrones dans SKILL.md

## 并发 API 调用

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

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

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