cfskit 0.1.7

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

cfskit

cfskit 是一个轻量科研代码库，提供日志、TensorBoard、进程信号、严格配置、DDP Context、checkpoint 基础和 显式 Pipeline 抽象，以及一个默认支持多进程 DDP 的实验工程示例：

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

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

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

通用工程实现位于命名明确的 cfskit.config_base、cfskit.context_base、 cfskit.checkpoint_base 和 cfskit.pipeline； 模板根 context.py 通过双继承统一管理具体配置与 Runtime，configs/ 只保留 TOML 实验数据。context.py 公开五个项目全局对象，s01 在每个 rank 上初始化 一次，后续代码直接调用：

全局对象	说明
ctx	一级实验配置字段、派生路径和进程信息
accelerator	绑定当前进程的 accelerate.Accelerator
logger	基于 loguru 的全局代理，tqdm 兼容，单次初始化
tb	TensorBoard 操作代理与示例接口，非主 rank 自动 no-op
ipc	基于 SIGUSR1/SIGUSR2 的进程内单例，通过 collective 向全部 rank 传播决策

模板调用方式

from cfskit import ExperimentPipeline

if __name__ == "__main__":
    ppl = ExperimentPipeline()
    from pipeline import InitStep, PrepareDataStep, TrainStep

    ppl.add_step(InitStep())
    ppl.add_step(PrepareDataStep())
    ppl.add_step(TrainStep())
    ppl.run()

ExperimentPipeline 统一处理 Pipeline 执行、ExperimentError 的简短报错和 Context 收尾；项目入口只保留一行一个 step 的实验流程。InitStep 不区分 train/eval， work() 只调用 ctx.initialize()，由 Context 底层读取一个必填的完整 TOML。训练恢复与 评估前置条件由各自 step 按约定做基础检查，不进入通用 Runtime 状态。--help 仍无 运行副作用。DDP 是模板的 主要执行架构，推荐通过 accelerate launch --num_processes=<N> run_train.py configs/<experiment>.toml 启动；world_size=1 只是同一路径的 单进程情形，不存在另一套“单卡默认实现”。每次运行只接收一个显式全量 TOML，不做默认加载或增量 TOML 合并；TOML 仍用 section 管理完整实验， 但初始化后直接使用 ctx.batch_size、ctx.model_name 等一级字段；模板 context.py 只以注释分隔各生命周期配置区域。

临时调试可在完整 TOML 后直接覆盖已声明的一级字段，例如 --micro-batch-size 32 --epochs 3。GPU 可见范围和 DDP 进程数仍分别由 CUDA_VISIBLE_DEVICES 与 accelerate launch --num_processes=<N> 管理；覆盖后的最终值会写入 effective_config.json。正式实验仍建议保存一份对应的完整 TOML。

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

logger、tb、ipc 直接复用 cfskit 单例，不再由模板再包一层代理；accelerator 由 cfskit.context_base 提供稳定代理。Pipeline 使用普通 for 循环执行显式 step，不包含自动发现、 递归责任链、dataset registry 或隐式 DDP barrier。

cfskit.checkpoint_base 只提供可复用的 Accelerate state 检查和 DDP staging 发布； last/best/epoch 命名、指标 metadata、train/eval 选择顺序与保留策略仍由具体科研项目定义。 它不自动扫描硬崩溃遗留的隐藏 backup，也不提供复杂策略框架。

安装

python -m pip install "cfskit>=0.1.7"

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

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

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

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

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

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

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