PILOT开发者指南:如何三步在工具箱中添加一个新的类增量学习算法?
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 里的训练逻辑,其余评估、日志、遗忘度统计全部由框架代劳。
上图是工具箱已复现算法在 CIFAR-100(初始 10 类、每阶段 +10 类)上的精度曲线,新算法加入后将直接出现在这一体系中横向对比。
二、第一步:在 models/ 下实现你的 Learner 类
所有算法都遵循同一约定:models/<你的名字>.py 中定义一个名为 Learner 的类,继承自 models/base.py 中的 BaseLearner,并实现两个核心方法:
incremental_train(self, data_manager):每个增量阶段的训练入口。典型骨架(可参考 models/finetune.py 和 models/l2p.py):
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:样例相关,无样例方法填 0seed:默认 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)
你的方法曲线应与图中文本标注风格一致地落在对应精度区间——明显偏离同类方法时,优先排查分类头扩展(update_fc)、参数冻结范围和损失裁剪(增量阶段只对"新类区间"计算交叉熵)这三处。
六、常见坑与提交建议
get_task_size与索引范围:训练集只取np.arange(self._known_classes, self._total_classes),测试集取np.arange(0, self._total_classes),两者搞混是新手最常踩的坑。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),自定义骨干时请一并加好校验。- 多卡训练:沿用基类写法,在训练前后处理
nn.DataParallel的包装与解包(参考 models/l2p.py)。 - 样例 vs 无样例:无样例方法把
memory_size、memory_per_class置 0,并让基类跳过 NME 评估(无_class_means时eval_task自动只输出 CNN 精度)。 - 提交代码前:仓库对 PR 有明确政策,优先合入在论文中引用了 PILOT 工具箱的工作,请先阅读 resources/PR_policy.md。
总结
向 PILOT 添加新算法的本质就是"一次继承、一处注册、一份配置":
| 步骤 | 改动位置 | 工作量 |
|---|---|---|
① 实现 Learner |
models/ 新文件 | 核心工作量 |
| ② 注册工厂分支 | utils/factory.py | 2 行代码 |
| ③ 配置与运行 | exps/ 新 JSON + python main.py --config=... |
复用模板 |
得益于 BaseLearner 对数据切分、评估、日志和样例记忆的抽象,新算法只需专注增量训练逻辑本身,即可立即进入工具箱的公平对比体系,为类增量学习研究节省大量重复的基建工作。

