cfskit 0.1.3

Common research utilities for our NUIST-GenAI-Lab and CCGM tasks

cfskit

cfskit 是一个轻量科研代码库，提供日志、TensorBoard 写入、进程信号控制，以及一个可运行的实验工程示例：

• nlab-template: 使用连续编号 pipeline 表达数据准备、训练和评估的 CIFAR-10 工程。

模板用于复现、二次开发或新实验起步；运行逻辑、配置、checkpoint 和验证证据都保留在普通代码与文档中。

本仓库推荐使用 OpenSpec 管理非平凡变更。根目录 openspec/ 用于讨论和设计 cfskit 工具模块迭代、模板规范化与维护变更；各模板工程内部的 openspec/ 只服务对应 demo 项目的本地科研变更示范。

工具实例	来源	说明
accelerator	accelerate.Accelerator	由项目 Runtime 显式创建并持有
logger	cfskit.log_util	基于 loguru 的全局代理，tqdm 兼容，单次初始化
tb	cfskit.tb_util	基于 TensorBoard 的全局代理，多进程自动适配
ipc	cfskit.ipc_util	基于 SIGUSR1/SIGUSR2 的进程内单例，支持优雅控制训练流程

基础 API

from accelerate import Accelerator
from cfskit import ipc, logger, setup_logger, setup_tensorboard, tb

accelerator = Accelerator()
setup_logger("output/demo/logs", name="nlab")
setup_tensorboard("output/demo/runs", name="nlab", accelerator=accelerator)
ipc.register_signal_handler()

accelerator.wait_for_everyone()
logger.info("experiment started")
tb.scalar("Loss/train", 0.1, step=1)
if ipc.get_s1():
    ipc.switch_s1(0)

推荐统一使用 accelerator.xxx、logger.xxx、tb.xxx、ipc.xxx。旧的 register_signal_handler()、get_s1()、switch_s1() 等 IPC 函数仍保留为兼容 wrapper， 但新代码不再使用散函数调用。

安装

python -m pip install "cfskit>=0.1.3"

如果需要使用 setup_tensorboard()，请安装 torch extra：

python -m pip install "cfskit[torch]>=0.1.3"

如果还需要 tb.image_grid() 等 torchvision 能力：

python -m pip install "cfskit[torch,tb-vision]>=0.1.3"

仓库内直接运行 examples/nlab-template/ 时，使用 editable 安装以确保调用当前源码：

cd examples/nlab-template
python -m pip install -e "../..[torch,tb-vision]"

nlab-template 当前要求 cfskit>=0.1.3。复制为独立工程后应安装已发布版本，不再依赖仓库相对路径。