PILOT开发者指南:如何三步在工具箱中添加一个新的类增量学习算法?

原创2026-11-16 09:22:121,363 阅读

PILOT开发者指南:如何三步在工具箱中添加一个新的类增量学习算法?

PILOT(LAMDA-PILOT)是一个基于预训练模型的类增量学习(Class-Incremental Learning)工具箱,已在统一框架内复现了 L2P、DualPrompt、CODA-Prompt、SimpleCIL、FOSTER、MEMO 等 20 余种 SOTA 算法。本指南面向想要向工具箱贡献新算法的开发者:只需三步——实现 Learner 类 → 注册工厂函数 → 配置 JSON 并运行,就能把你的新算法纳入 PILOT 的增量学习基准体系,与所有已有方法在相同设置下对比。

一、先看懂 PILOT 增量学习工具箱的架构

在动手之前,先花 2 分钟理清数据流,后面三步都是顺着这条链路做的:

模块 文件 职责
入口 main.py 解析 --config 指定的 JSON,合并参数后调用训练
训练循环 trainer.py 按任务(task)逐轮调用 incremental_train → eval_task → after_task
模型工厂 utils/factory.py 根据 model_name 字符串分发到对应算法模块
基类 models/base.py BaseLearner 提供内存管理、评估、NME 等公共能力
网络封装 utils/inc_net.py IncrementalNet、PromptVitNet、SimpleVitNet 等增量网络
数据管理 utils/data_manager.py 按 init_cls/increment 切分任务,提供 get_dataset
骨干网络 backbone/ ViT 的 prompt/adapter/VPT 等变体实现
实验配置 exps/ 每个算法一对 xxx.json 与 xxx_inr.json 超参数

整个训练主循环非常薄:trainer.py 中对每个任务依次执行 model.incremental_train(data_manager)、model.eval_task() 和 model.after_task(),并自动记录每阶段的 top1/top5 精度曲线。你的算法要做的,就是填好 incremental_train 里的训练逻辑,其余评估、日志、遗忘度统计全部由框架代劳。

PILOT预训练模型类增量学习工具箱在CIFAR-100上的各算法精度曲线对比

上图是工具箱已复现算法在 CIFAR-100(初始 10 类、每阶段 +10 类)上的精度曲线,新算法加入后将直接出现在这一体系中横向对比。

二、第一步:在 models/ 下实现你的 Learner 类

所有算法都遵循同一约定:models/<你的名字>.py 中定义一个名为 Learner 的类,继承自 models/base.py 中的 BaseLearner,并实现两个核心方法:

def incremental_train(self, data_manager):
    self._cur_task += 1
    # 1. 更新分类头:旧类 + 新增类
    self._total_classes = self._known_classes + data_manager.get_task_size(self._cur_task)
    self._network.update_fc(self._total_classes)

    # 2. 取本阶段"新类"的训练集、"全部已知类"的测试集
    train_dataset = data_manager.get_dataset(
        np.arange(self._known_classes, self._total_classes),
        source="train", mode="train")
    test_dataset = data_manager.get_dataset(
        np.arange(0, self._total_classes), source="test", mode="test")
    self.train_loader = DataLoader(train_dataset, batch_size=self.args["batch_size"], shuffle=True)
    self.test_loader = DataLoader(test_dataset, batch_size=self.args["batch_size"], shuffle=False)

    # 3. 你的训练逻辑(冻结骨干 / 优化器 / epoch 循环 / 损失函数……)
    self._train(self.train_loader, self.test_loader)
  • after_task(self):阶段结束后的收尾,最常见的是把 self._known_classes = self._total_classes。

几个关键状态变量由基类维护,理解它们即可正确实现增量逻辑:

变量 含义
self._cur_task 当前是第几轮增量阶段
self._known_classes 上一阶段结束时的类数
self._total_classes 本阶段结束时的类数
self._data_memory / self._targets_memory 样例(exemplar)缓存,基类已提供构建逻辑

网络从哪里来? 推荐优先复用 utils/inc_net.py 现成的增量网络封装,如 IncrementalNet(自动扩展分类头,见 IncrementalNet)、SimpleVitNet、PromptVitNet;如果算法需要改造 ViT 结构(prompt pool、adapter 等),则在 backbone/ 下新增模块,并在 utils/inc_net.py 的 get_backbone 中按 backbone_type 后缀分支返回——注意该函数会对 model_name 与 backbone_type 的一致性做校验,不匹配会抛出 NotImplementedError。

💡 如果你的算法需要样例回放(如 iCaRL、MEMO),基类的 build_rehearsar_memory 已实现按类均匀采样;无样例方法(如 L2P、DualPrompt)则直接保持 memory_size: 0 即可。

三、第二步:在工厂函数中注册新算法

PILOT 通过 utils/factory.py 的 get_model 做字符串 → 类的分发。只需在链中加一个分支:

elif name == "your_method":
    from models.your_method import Learner

就这一处改动。注册后,配置文件中 model_name 填 your_method 即可被 trainer.py 中的 factory.get_model(args["model_name"], args) 找到并实例化。若忘记注册,程序会走到 assert 0 直接报错——这是最常见的"新算法跑不起来"原因。

四、第三步:新建 JSON 配置并一键运行

每个算法在 exps/ 下都有一份(或一对,ImageNet-R 以 _inr 结尾)JSON 配置。最快的方式是复制一份现成模板,例如无样例方法抄 exps/l2p.json,全参数微调抄 exps/finetune.json,然后改名保存为 exps/your_method.json,重点修改全局字段:

{
    "dataset": "cifar224",
    "init_cls": 10,
    "increment": 10,
    "model_name": "your_method",
    "backbone_type": "pretrained_vit_b16_224",
    "device": ["0"],
    "seed": [1993],
    "batch_size": 256,
    "init_lr": 0.01
}

核心参数速查:

  • model_name:必须与 factory 中注册的字符串、以及 models/ 下文件名一致
  • init_cls / increment:初始类数与每阶段新增类数,决定任务切分(见 DataManager)
  • backbone_type:预训练骨干,如 pretrained_vit_b16_224、vit_base_patch16_224_l2p(需在 get_backbone 中有对应分支)
  • memory_size / fixed_memory / memory_per_class:样例相关,无样例方法填 0
  • seed:默认 1993(沿用 iCaRL 基准设定),支持列表跑多随机种子

然后运行:

python main.py --config=./exps/your_method.json

训练日志会自动写入 logs/<model_name>/<dataset>/<init_cls>/<increment>/ 目录,每个任务打印 CNN top1 分组精度、平均精度(Average Accuracy);开启 print_forget 后还会输出精度矩阵与遗忘度(Forgetting)。

五、验证你的工作:加入基准曲线

算法跑通后,对照官方复现结果检查数值是否合理。工具箱在两个标准设定上给出完整曲线:

  • CIFAR-100(cifar224,初始 10 类、每阶段 10 类,见 exps/l2p.json)
  • ImageNet-R(imagenetr,初始 20 类、每阶段 20 类,见 exps/l2p_inr.json)

PILOT工具箱在ImageNet-R上类增量学习算法平均精度曲线对比

你的方法曲线应与图中文本标注风格一致地落在对应精度区间——明显偏离同类方法时,优先排查分类头扩展(update_fc)、参数冻结范围和损失裁剪(增量阶段只对"新类区间"计算交叉熵)这三处。

六、常见坑与提交建议

  1. get_task_size 与索引范围:训练集只取 np.arange(self._known_classes, self._total_classes),测试集取 np.arange(0, self._total_classes),两者搞混是新手最常踩的坑。
  2. backbone_type 一致性:get_backbone 中每个后缀分支都会校验 args<a href="https://link.gitcode.com/i/796908f087053b3269d20562b12f8400" target="_blank">"model_name"],如 _l2p 分支要求 model_name == "l2p"(见 [utils/inc_net.py),自定义骨干时请一并加好校验。
  3. 多卡训练:沿用基类写法,在训练前后处理 nn.DataParallel 的包装与解包(参考 models/l2p.py)。
  4. 样例 vs 无样例:无样例方法把 memory_size、memory_per_class 置 0,并让基类跳过 NME 评估(无 _class_means 时 eval_task 自动只输出 CNN 精度)。
  5. 提交代码前:仓库对 PR 有明确政策,优先合入在论文中引用了 PILOT 工具箱的工作,请先阅读 resources/PR_policy.md。

总结

向 PILOT 添加新算法的本质就是"一次继承、一处注册、一份配置":

步骤 改动位置 工作量
① 实现 Learner models/ 新文件 核心工作量
② 注册工厂分支 utils/factory.py 2 行代码
③ 配置与运行 exps/ 新 JSON + python main.py --config=... 复用模板

得益于 BaseLearner 对数据切分、评估、日志和样例记忆的抽象,新算法只需专注增量训练逻辑本身,即可立即进入工具箱的公平对比体系,为类增量学习研究节省大量重复的基建工作。

登录后查看全文
LAMDA-PILOT