async_log

def async_log(
    func: Callable,
    *args: Any,
    step: Optional[int] = None,
    mode: AsyncLogType = "threading",
    **kwargs: Any,
) -> Future

参数	描述
func	(Callable) 一个返回 dict 的函数，返回值会被自动通过 swanlab.log() 记录。
*args	传递给 func 的位置参数。
step	(Optional[int]) 可选步数。如果为 None，将在任务完成时（而非提交时）自动递增。如果步序很重要，请传入显式值。
mode	(AsyncLogType) 执行模式。可选值为 asyncio、threading（默认）、spawn、fork。详见下方说明。
**kwargs	传递给 func 的关键字参数。

介绍

swanlab.async_log 异步执行一个函数并自动记录其返回值。适用于需要在训练循环中记录需要耗时计算或 I/O 的指标，而不会阻塞主流程的场景。

该调用会立即返回一个 Future。swanlab.finish() 会等待所有未完成的 async_log 任务完成后才刷新数据，因此不会丢失任何数据。

执行模式

threading（默认）

在后台线程中运行 func。无 pickle 限制 — func 可以访问 swanlab.config 并返回 Image、Audio 等媒体对象。受 GIL 限制。

import swanlab
import time

swanlab.init(project="my-project")

def fetch_score():
    time.sleep(2)
    return {"score": 0.95}

future = swanlab.async_log(fetch_score, step=1)
# 训练继续，不会被阻塞...

swanlab.finish()

asyncio

在运行的 asyncio 事件循环上调度 func。func 必须是一个协程（async def）。如果没有事件循环在运行，将抛出 RuntimeError。

import asyncio
import swanlab

swanlab.init(project="my-project")

async def slow_compute():
    await asyncio.sleep(2)
    return {"score": 0.95}

future = swanlab.async_log(slow_compute, step=1, mode="asyncio")

swanlab.finish()

spawn

在新的子进程中运行 func（使用 multiprocessing 的 spawn 上下文）。绕过 GIL，适合 CPU 密集型任务。func、其参数和返回值必须可被 pickle 序列化（不支持 Image、torch.Tensor 等）。

import swanlab

swanlab.init(project="my-project")

def compute_loss():
    return {"loss": 0.123, "acc": 0.95}

future = swanlab.async_log(compute_loss, step=2, mode="spawn")

swanlab.finish()

使用 torch.Tensor 时需要先转换：

import torch
import swanlab

swanlab.init(project="my-project")

def compute():
    t = torch.randn(10)
    return {"value": t.item(), "arr": t.detach().cpu().numpy()}

future = swanlab.async_log(compute, step=3, mode="spawn")

swanlab.finish()

fork（保留）

此模式暂未支持。将在 swanlab-core 发布后启用，届时子进程可直接调用 swanlab.log()。

注意事项

1. func 的返回值必须是 dict，且兼容 swanlab.log() 的数据格式。
2. finish() 会阻塞直到所有未完成的 async_log 任务完成，确保数据不会丢失。
3. asyncio 模式下需要有活跃的事件循环，否则会抛出 RuntimeError。
4. spawn 模式下，传入和返回 func 的所有数据必须可被 pickle 序列化。子进程无法访问活跃的 Run 实例。