Skills: Asynchrone und nebenläufige Verarbeitung

Wenn ein Skill gleichzeitig auf mehrere zeitaufwändige Operationen warten muss (wie Netzwerkanfragen, Datei-I/O), kann asynchrone Programmierung die gesamte Wartezeit erheblich reduzieren.

Dieser Artikel stellt die Anwendungsszenarien und Codierungsmuster von Python asyncio in Skill-Skripten vor.


Synchron vs. Asynchron: Wann asynchron verwendet werden sollte

SzenarioEmpfohlener AnsatzGrund
Verarbeitung einer einzelnen Datei, einzelner API-AufrufSynchronAsynchrone Vorteile sind nicht offensichtlich; Code ist einfacher
Mehrere HTTP-Anfragen gleichzeitig sendenAsynchronGleichzeitiges Warten, Gesamtzeit ≈ längste einzelne Anfragezeit
Mehrere Dateien gleichzeitig lesenAsynchron oder Thread-PoolAufgaben können während des Wartens auf I/O umgeschaltet werden
CPU-intensive Berechnung (z. B. Bildverarbeitung)Multiprocessingasyncio umgeht den GIL nicht

Asynchron ist nicht gleich parallel. Pythons asyncio ist eine Single-Threaded-Ereignisschleife, geeignet für I/O-intensive Aufgaben (Warten auf Netzwerk, Festplatte). CPU-intensive Aufgaben sollten verwendenProcessPoolExecutor。


Mehrere HTTP-Anfragen asynchron senden

Angenommen, ein Skill muss 3 API-Endpunkte gleichzeitig aufrufen. Im synchronen Modus ist die Gesamtzeit die Summe der drei Anfragen; im asynchronen Modus entspricht die Gesamtzeit ungefähr der langsamsten.

Beispiel

# Dateipfad: scripts/async_requests.py
# Mehrere APIs asynchron und nebenläufig aufrufen und die Ergebnisse zusammenführen

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:
    """Eine einzelne POST-Anfrage asynchron senden"""
    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:
    """
Alle Anfragen gleichzeitig senden und warten, bis alle abgeschlossen sind

Parameter:
requests: list, jedes Element ist ein (endpoint, payload)-Tupel
    """

    async with aiohttp.ClientSession() as session:
        tasks = [
            fetch_one(session, endpoint, payload)
            for endpoint, payload in requests
        ]
        # gather führt alle Aufgaben gleichzeitig aus; return_exceptions=True verhindert, dass ein Fehler andere beeinflusst
        return await asyncio.gather(*tasks, return_exceptions=True)

def main():
    # Definiere die Liste der Requests, die gleichzeitig aufgerufen werden sollen
    requests = [
        ("/summarize", {"text": "Example ist eine Technologie-Lernplattform", "lang": "zh"}),
        ("/keywords",  {"text": "EXAMPLE bietet verschiedene Programmier-Tutorials", "top_n": 5}),
        ("/sentiment", {"text": "Die Tutorials auf dieser Plattform sind von hoher Qualität"}),
    ]

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

    print(f"{len(results)} Anfragen gleichzeitig abgeschlossen, Gesamtzeit {elapsed:.2f} Sekunden")
    print(json.dumps(results, ensure_ascii=False, indent=2))

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

Mehrere Dateien asynchron lesen

Für Szenarien, in denen mehrere Dateien gleichzeitig gelesen werden müssen,aiofilesbietet eine asynchrone Version der Datei-E/A.

Beispiel

# Dateipfad: 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:
    """Liest eine einzelne Datei asynchron ein"""
    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:
    """Alle Dateien gleichzeitig lesen"""
    tasks = [read_file(fp) for fp in file_paths]
    return await asyncio.gather(*tasks)

if __name__ == "__main__":
    import glob, json
    # Alle .txt-Dateien im Upload-Verzeichnis lesen
    files = glob.glob("/mnt/user-data/uploads/*.txt")
    if not files:
        print("Keine .txt-Dateien gefunden")
    else:
        results = asyncio.run(read_all_files(files))
        print(json.dumps(results, ensure_ascii=False, indent=2))

Timeout-Steuerung und Task-Abbruch

Bei asynchronen Tasks ist die Timeout-Steuerung besonders wichtig.asyncio.wait_forSie können eine maximale Wartezeit für eine einzelne Aufgabe festlegen.

Beispiel

# Dateipfad: scripts/async_timeout.py
import asyncio

async def slow_task(name: str, delay: float) -> str:
    """Simuliere eine zeitaufwändige Aufgabe"""
    await asyncio.sleep(delay)
    return f"{name} abgeschlossen"

async def run_with_timeout():
    tasks = {
        "Schnelle Aufgabe": slow_task("Schnelle Aufgabe", 0.5),
        "Langsame Aufgabe": slow_task("Langsame Aufgabe", 5.0),
    }
    results = {}
    for name, coro in tasks.items():
        try:
            # Warte höchstens 2 Sekunden auf jede Aufgabe
            result = await asyncio.wait_for(coro, timeout=2.0)
            results[name] = {"status": "ok", "result": result}
        except asyncio.TimeoutError:
            results[name] = {"status": "timeout", "message": "Nicht innerhalb von 2 Sekunden abgeschlossen"}
    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 秒未完成"}
}

Erklären, wie asynchrone Skripte in SKILL.md aufgerufen werden

## 并发 API 调用

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

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

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