NNI NAS API 参考指南:从搜索空间构建到策略编排的完整实践
NNI NAS API 参考指南:从搜索空间构建到策略编排的完整实践
导读
本文以 docs/source/reference/nas.rst 为骨架,系统梳理 NNI(Neural Network Intelligence)神经架构搜索(NAS)模块的完整 API 体系。你将掌握如何用 LayerChoice、InputChoice、Repeat、Cell 等原语搭建可搜索模型空间,如何使用 FunctionalEvaluator、PyTorch 内置评估器评估模型,如何通过多试次(multi-trial)与一次性(one-shot)策略驱动搜索,以及如何编排 NasExperiment、使用 Profiler、接入 NAS Benchmarks 与执行引擎。所有论述均以当前仓库的源码实现(nni/nas 目录)为佐证,可对照源码继续深入。
一、NAS API 全景总览
docs/source/reference/nas.rst 将 NNI NAS 的公开 API 划分为十一个板块,对应到仓库中的实现模块如下:
| API 分类 | RST 章节 | 源码位置 |
|---|---|---|
| Model space(模型空间原语) | Model space | nni/nas/nn/pytorch |
| Model Space Hub(预置空间库) | Model Space Hub | nni/nas/hub/pytorch |
| Evaluator(评估器) | Evaluator | nni/nas/evaluator |
| Multi-trial strategy(多试次策略) | Multi-trial strategy | nni/nas/strategy |
| One-shot strategies(一次性策略) | One-shot strategies | nni/nas/oneshot/pytorch/strategy |
| Experiment(实验编排) | Experiment | nni/nas/experiment |
| Profiler(硬件性能剖析) | Profiler | nni/nas/profiler |
| Model format(模型空间格式) | Model format | nni/nas/space |
| Execution engine(执行引擎) | Execution engine | nni/nas/execution |
| NAS Benchmarks(基准数据集) | NAS Benchmarks | nni/nas/benchmark |
| 序列化工具 | Miscellaneous Utilities | nni/nas/utils/serializer.py |
理解这条主线之后,下面的内容将按"搜索空间 → 评估器 → 搜索策略 → 实验编排 → 性能剖析 → 基准与执行"的顺序展开。
二、Model Space:构建可搜索的模型空间
Model space 是 NAS 的"画布"。NNI 提供一组继承自 MutableModule 的 PyTorch 模块原语,让开发者用接近普通 PyTorch 的方式写出带"不确定性"的模型。
2.1 LayerChoice:从候选算子中选择一个
nni.nas.nn.pytorch.LayerChoice 从一组候选模块(PyTorch Module)中选出一个,应用到输入上并返回结果。它允许将多个候选算子放入一个模块,每次搜索时只激活其中一种。
核心参数(见 choice.py):
candidates:list或OrderedDict。传 list 时按位置索引命名(0、1、2…),传 OrderedDict 时以键名命名,例如:self.op_choice = nn.LayerChoice(OrderedDict([ ("conv3x3", nn.Conv2d(3, 16, 128)), ("conv5x5", nn.Conv2d(5, 16, 128)), ("conv7x7", nn.Conv2d(7, 16, 128)) ]))weights:list[float],随机采样时的先验分布权重。label:该 layer choice 的标识符;同一 label 的多个选择在语义上共享同一个采样结果。
典型用法:
self.layer = nn.LayerChoice([
ops.PoolBN('max', channels, 3, stride, 1),
ops.SepConv(channels, channels, 3, stride, 1),
nn.Identity()
])
# 在 forward 中
out = self.layer(x)
从源码可以看到 LayerChoice 还支持容器式操作:len(layer_choice) 获取候选个数、layer_choice<a href="https://link.gitcode.com/i/c4bcdc66c8d13ddddf482c2e11f1b493" target="_blank">"conv5x5"] 或 layer_choice[1] 访问候选模块、del 删除候选。注意当前版本不支持新增候选([choice.py)。其 freeze(sample) 方法会依据采样字典把 LayerChoice 还原成被选中的那个具体模块(recursive_freeze 递归处理)。
2.2 InputChoice:从多个输入中选择连接
nni.nas.nn.pytorch.InputChoice 用于连接搜索(connection search):从 n_candidates 个输入张量中选出 n_chosen 个,并按 reduction 合并为单个输出(choice.py):
n_candidates:候选输入个数(必填)。n_chosen:推荐选出的个数;为None时由 mutator 决定。reduction:'mean'|'concat'|'sum'|'none',默认'sum'。'none'直接返回张量列表;'concat'在维度 1 上拼接。weights:随机采样先验。label:标识符。
示例:
self.input_switch = nn.InputChoice(n_chosen=1)
# forward 中从三个张量里选一个
out = self.input_switch([tensor1, tensor2, tensor3])
当采样确定后,InputChoice 会被冻结为 ChosenInputs(见 choice.py),其中保存 chosen(被选中的索引列表)与 reduction,真正执行张量归约逻辑。
2.3 Repeat:可变深度地重复模块块
nni.nas.nn.pytorch.Repeat 将一个 block 重复可变次数,用于搜索网络的深度(repeat.py):
blocks:模块、模块列表或接收索引返回模块的工厂函数。传入单个模块时会被深拷贝复制max_depth份;传入函数时按索引实例化,从而可以让每层拥有独立 label(独立决策)。depth:整数(固定次数)、(min, max)元组(在该闭区间内搜索)或正整数候选的 choice。2.8 版本起min允许为 0,但图执行引擎不支持 0 深度。
# Block() 被深拷贝并固定重复 3 次
self.blocks = nn.Repeat(Block(), 3)
# 在 [1, 3] 之间搜索重复次数
self.blocks = nn.Repeat(Block(), (1, 3))
# 与 LayerChoice 组合:3 层共享同一选择(同 label)
self.blocks = nn.Repeat(nn.LayerChoice([...]), (1, 3))
# 让 3 层的 LayerChoice 各自独立
self.blocks = nn.Repeat(lambda index: nn.LayerChoice([...], label=f'layer{index}'), (1, 3))
# depth 使用 ValueChoice 支持任意深度候选
self.blocks = nn.Repeat(Block(), nn.ValueChoice([1, 3, 5]))
从源码看,Repeat 内部把 depth 规范化为 Categorical 或整数,并维护 min_depth / max_depth;freeze() 时只保留前 depth 个 block 组成 nn.Sequential。
2.4 Cell:NAS 文献中的经典单元结构
nni.nas.nn.pytorch.Cell 是 NAS 文献(NASNet、DARTS、NDS 等)中广泛使用的 Cell 结构:一个 Cell 由多个"节点"组成,每个节点是多个算子的求和;每个算子从 op_candidates 中独立选出,并从前序节点或 Cell 的输入(predecessors)中选一个作为输入;Cell 的输出默认是所有节点的拼接(cell.py)。
关键参数:
op_candidates:模块列表、字典,或接收(node_index, op_index, input_index)的工厂函数。工厂函数示例:cell = nn.Cell([ lambda node_index, op_index, input_index: nn.Conv2d(32, 32, 3, stride=2 if input_index < 1 else 1), ], 4, 1, 2)num_nodes:Cell 内节点数。num_ops_per_node:每个节点内算子数(节点输出为算子求和),默认 1。num_predecessors:Cell 输入个数,forward 需接收等长张量列表,默认 1。merge_op:'all'或'loose_end'。'all'拼接全部节点;'loose_end'只拼接从未被其他节点用作输入的节点(详见 NDS 论文),默认'all'。preprocessor/postprocessor:对 Cell 输入/输出的自定义变换回调,默认分别为"原样透传"与"直接返回当前 Cell 输出"。concat_dim:节点拼接维度,默认 1。
基本用法与 output_node_indices:
cell = nn.Cell([nn.Conv2d(32, 32, 3, padding=1), nn.MaxPool2d(3, padding=1)], 4, 1, 2)
cell([input1, input2]) # forward:长度须等于 num_predecessors
cell(only_input) # 单个输入可省略列表括号
cell_out_channels = len(cell.output_node_indices) * 32
Preprocessor 用于对齐不同形状的前驱输入:
class Preprocessor:
def __init__(self):
self.conv1 = nn.Conv2d(16, 32, 1)
self.conv2 = nn.Conv2d(64, 32, 1)
def forward(self, x):
return [self.conv1(x[0]), self.conv2(x[1])]
cell = nn.Cell([nn.Conv2d(32, 32, 3), nn.MaxPool2d(3)], 4, 1, 2, preprocessor=Preprocessor())
源码细节:Cell 内部为每个节点构建一个 LayerChoice(算子选择,label 为 op_{i}_{k})与一个 InputChoice(输入选择,label 为 input_{i}_{k}),forward 时逐节点执行"选输入 → 过算子 → 求和",最后按 output_node_indices 拼接并交给 postprocessor。使用工厂函数时,Cell.freeze() 会基于采样重新实例化整个 Cell(cell.py)。
注意:官方文档明确
Cell不适用于GraphModelSpace图模型空间,请仅在 Python(PyTorch)模型空间中直接使用。
2.5 ModelSpace 与 ParametrizedModule:模型空间的基类体系
nni.nas.nn.pytorch.ModelSpace:基于 PyTorch 的模型搜索空间基类。官方明确它不是真实的可运行模型,其 forward 仅用于对空间内的任意模型做 dry run 与空间追踪;导出权重请走 one-shot 策略把模型空间变成 supernet,直接state_dict并不可靠(base.py)。它还提供load_searched_model(name, pretrained=...)用于加载预搜索模型(需子类实现)。nni.nas.nn.pytorch.MutableModule:带不确定性的 PyTorch 模块基类,核心能力包括freeze(sample)(把模块冻结为确定架构)、add_mutable()(注册游离的可变变量,常与ensure_frozen搭配)、named_mutable_descendants()(遍历子树中所有 MutableModule)。nni.nas.nn.pytorch.ParametrizedModule:支持把可变量作为__init__参数的模块。它在初始化时自动冻结传入的 mutable 参数,例如:
注意可变参数必须直接作为class MyModule(ParametrizedModule): def __init__(self, x): super().__init__() self.t = x # 将会是确定值,如 3 MyModule(nni.choice('choice1', [1, 2, 3]))__init__的位置/关键字参数,不能藏在 list/dict 里;可变参数在嵌套实例化中不被跟踪。对第三方模块做 parametrized 改造的推荐姿势是class ParametrizedConv2d(ParametrizedModule, nn.Conv2d, wraps=nn.Conv2d)。torch.nn中常用模块的 parametrized 版本已内置在nni.nas.nn.pytorch,均以Mutable前缀命名,如MutableConv2d(base.py)。
label 与 label_prefix:NAS 要求模型空间中的 mutable 必须手动指定 label,除非模型空间提供了 label_prefix。例如 class MyModelSpace(ModelSpace, label_prefix='backbone') 后,nni.choice('depth', <a href="https://link.gitcode.com/i/61c488bddfadf94df7185827dae9f638" target="_blank">2, 3, 4]) 的 label 会自动成为 backbone/depth([base.py)。
三、Model Space Hub:开箱即用的预置搜索空间
参考文档的 "Model Space Hub" 章节列出了 nni.nas.hub.pytorch 下的预置空间,均可作为模型空间直接使用或组合:
- NAS-Bench 相关:
NasBench101、NasBench201—— 与官方基准数据集对齐的空间。 - NASNet 家族:
NASNet、nasnet.NDS、nasnet.NDSStage、nasnet.NDSStagePathSampling、nasnet.NDSStageDifferentiable—— 其中NDS*系列提供 NDS(Network Design Spaces)论文风格的 Cell 级/Stage 级搜索单元,且区分路径采样与可微分两种搜索模式。 - 经典搜索空间:
ENAS、AmoebaNet、PNAS、DARTS、ProxylessNAS(含proxylessnas.InvertedResidual模块)、MobileNetV3Space、ShuffleNetSpace、AutoFormer。 - Module Components:
nni.nas.hub.pytorch.modules提供可复用的组件模块。
这些空间的实现位于 nni/nas/hub/pytorch,配套示例见 examples/nas/legacy(如 darts、oneshot、nasbench101、nasbench201 等目录)。完整可运行教程可参考 docs/source/tutorials/hello_nas.rst 与 examples/tutorials/hello_nas.py。
四、Evaluator:如何给模型打分
Evaluator 负责"评估一个模型并返回分数"。NNI 提供从最自由的函数式到开箱即用的 PyTorch 评估器。
4.1 FunctionalEvaluator:最通用的函数式评估器
nni.nas.evaluator.FunctionalEvaluator 直接接收一个函数,是最具自由度、但也与部分算法不兼容的评估方式(functional.py):
evaluator = FunctionalEvaluator(my_function, lr=0.1, epochs=10)
构造时传入 function 与其它关键字参数;运行时调用 function(model, **kwargs) 返回分数。它自带 trace 能力,无需额外 nni.trace 装饰。
4.2 Evaluator 与 MutableEvaluator:可搜索超参的评估器
Evaluator:评估器基类,用户只需实现evaluate(model)。官方文档建议:评估器内部可以使用标准 NNI trial API 与搜索策略通信——nni.get_current_parameter()获取当前模型、nni.report_intermediate_result()上报中间结果、nni.report_final_result()上报最终结果;不要调用nni.get_next_parameter(),因为 NAS 框架已处理参数获取逻辑,误用可能引发异常行为(evaluator.py)。MutableEvaluator:评估器自身的参数也可以被搜索(如学习率)。要求:① 继承MutableEvaluator;② 用nni.trace包装构造(若存在嵌套的可变实例化,所有层级都需包装)。freeze(sample)会冻结所有可变参数并返回FrozenEvaluator(为了省内存,默认不立即实例化,首次evaluate时才递归实例化)。
@nni.trace
class MyOwnEvaluator(MutableEvaluator):
def __init__(self, lr, data): ...
evaluator = MyOwnEvaluator(
lr=nni.choice('lr', [0.1, 0.01]), # 可搜索的学习率
data=nni.trace(get_data)(shuffle=nni.choice('shuffle', [False, True]))
)
4.3 PyTorch 内置评估器
nni.nas.evaluator.pytorch 提供:
Classification/ClassificationModule:面向分类模型,假定模型 forward 接收一批数据并返回 logits。Regression/RegressionModule:面向回归任务。Trainer、DataLoader:训练循环与数据加载的配置容器。Lightning/LightningModule:基于 PyTorch Lightning 的训练封装,适合复用 Lightning 生态的训练器与回调。
使用这些评估器需要安装 PyTorch 及(如用 Lightning)相应依赖,可参考 dependencies/recommended.txt。实际组合示例见 examples/compression/evaluator/torch_evaluator.py 与 examples/compression/evaluator/lightning_evaluator.py。
五、Multi-trial Strategy:多试次搜索策略
多试次策略通过反复"采样 → 提交模型 → 训练评估 → 收集指标"来探索空间。参考文档列出五类策略(nni/nas/strategy):
GridSearch:对搜索空间做网格穷举。Random:随机采样。RegularizedEvolution:正则化进化算法。PolicyBasedRL:基于策略梯度的强化学习搜索(实现在 rl.py 与 _rl_impl.py)。TPE:基于 Tree-structured Parzen Estimator 的贝叶斯优化(见 hpo.py)。
5.1 Strategy 基类:状态机与引擎协作
所有策略继承 nni.nas.strategy.base.Strategy(base.py)。策略是有状态的,生命周期状态包括 EMPTY → INITIALIZED → RUNNING → SUCCEEDED / INTERRUPTED / FAILED。运行一个策略的方式是:
strategy = MyStrategy()
strategy(model_space, engine) # 依次调用 initialize() 与 run()
子类通常只需重写 _initialize、_run,以及用于断点续跑的 state_dict / load_state_dict。策略通过 engine 提交模型、监听指标、做预算/并发控制;wait_for_resource() 在 worker 空闲且预算可用时才继续提交。list_models(sort=True, limit=...) 可取出历史搜索中按指标降序排列的最优模型。
5.2 Middleware 与工具函数
nni.nas.strategy.middleware:策略中间件,可以包装真实的执行引擎(接口一致),用于在策略与引擎之间插入横切逻辑(如缓存、过滤)。nni.nas.strategy.utils:策略相关的工具函数。
六、One-shot Strategies:一次性(可微分)搜索
与多试次策略不同,one-shot 策略把模型空间变异为 supernet,训练与搜索同时进行,典型代表是可微分 DARTS 类算法。参考文档列出的策略包括:
RandomOneShot:随机采样子网训练。ENAS:权值共享 + 强化学习控制器。DARTS:以架构参数 α 做双层优化的可微分搜索。GumbelDARTS:用 Gumbel-Softmax 松弛离散选择。Proxyless:面向延迟约束的渐进式剪枝式可微分搜索。
相关实现位于 nni/nas/oneshot/pytorch/strategy(基类 OneShotStrategy 也在其中)。文档还列出以下支撑模块:
base_lightning:one-shot 训练基类(基于 Lightning)。supermodule.differentiable:可微分超网模块(路径加权求和,服务于 DARTS / GumbelDARTS)。supermodule.sampling:路径采样超网模块(服务于 RandomOneShot / ENAS)。supermodule.proxyless:Proxyless 风格二值化路径采样。supermodule.operation:超网中使用的算子封装。profiler:one-shot 中的剖析工具。
提示:官方文档强调,只有通过 one-shot 策略得到的 supernet 才能可靠导出权重(参考第二节 ModelSpace 的说明)。可运行的 one-shot 示例见 examples/nas/legacy/oneshot,教程见 docs/source/tutorials/darts.rst。
七、Experiment:编排一次 NAS 实验
nni.nas.experiment.NasExperiment:NAS 实验的顶层入口,负责把模型空间、评估器、策略、执行引擎组装起来并驱动运行。nni.nas.experiment.config.NasExperimentConfig:实验配置类。
使用上,一般流程为:构造模型空间 → 选择评估器与策略 → 通过 NasExperimentConfig 配置并发数、预算等 → 启动 NasExperiment 并运行。NNI 也支持通过命令行工具 nnictl(nni/tools/nnictl)管理实验生命周期。实验内部还会用到消息分发(nni/runtime/msg_dispatcher.py)与训练服务等运行时组件,可参考 docs/source/experiment 下的文档了解完整机制。
八、Profiler:剖析硬件性能指标
nni.nas.profiler 用于在不真正运行模型的情况下估计硬件性能指标,在硬件感知 NAS 中非常关键:
Profiler:剖析器基类。ExpressionProfiler:基于符号表达式(symbolic expression)的剖析,可从模型空间推导 FLOPs 等指标的解析式。- FLOPs(
nni.nas.profiler.pytorch.flops):计算浮点运算量。 - nn-Meter(
nni.nas.profiler.pytorch.nn_meter):基于实测数据集的推理延迟预测器(需相应依赖支持)。
用法上,通常先构建模型空间,再对该空间执行剖析,得到空间内所有候选架构的指标表达式,进而把 FLOPs / 延迟作为搜索目标或约束。相关讲解见 docs/source/nas/hardware_aware_nas.rst。
九、Model Format 与 Execution Engine
9.1 Model Format:空间的形式化表示
nni.nas.space 定义了模型空间的抽象表示,包括 Python 模型空间与 GraphModelSpace(图模型空间) 两种格式:
ExecutableModelSpace:可执行模型空间,是采样后可以真正运行的对象。GraphModelSpace:以计算图形式表示搜索空间,适合对接图执行引擎与 CGO 跨图优化;如前所述,Cell不适用于该格式,且图引擎对Repeat的 0 深度、工厂式op_candidates支持有限。- 常用上下文 API:
model_context(在给定采样下实例化模型)、current_model(获取当前上下文中的采样)。
9.2 Execution Engine:模型执行的编排者
nni.nas.execution 定义了执行引擎抽象:策略通过 engine.submit_models() 提交模型、通过 engine.budget_available() / engine.idle_worker_available() 感知资源与预算、通过 engine.list_models() 获取历史模型与指标。基类 Strategy 的所有协作逻辑都建立在该接口之上(base.py)。
Cross-graph optimization(CGO):nni.nas.execution.cgo 提供跨图优化能力——当多个模型共享大量相同子图时,CGO 通过图等价分析合并计算,避免重复训练,显著提升搜索吞吐。
十、NAS Benchmarks:接入公开基准
nni.nas.benchmark 提供对公开 NAS 基准数据集的查询接口,文档覆盖三类:
NAS-Bench-101(nni.nas.benchmark.nasbench101):CIFAR-10 上的 cell 级基准。NAS-Bench-201(nni.nas.benchmark.nasbench201):含 4 个数据集、统一 cell 拓扑的基准。NDS(nni.nas.benchmark.nds):基于 NASNet/DARTS 等大空间的基准。
基准的下载与查询脚本见 examples/nas/benchmarks(nasbench101.sh、nasbench201.sh、nds.sh、nlp.sh 及各 .requirements.txt)。把基准当作数据集使用的教程见 docs/source/tutorials/nasbench_as_dataset.rst。
十一、Miscellaneous Utilities:序列化与其它工具
nni.nas.utils.serializer 提供 NAS 对象(模型空间、评估器、策略等)的序列化与反序列化能力,支撑多进程/分布式场景下的对象重建。nni.nas.nn.pytorch 中的 ParametrizedModule 与 ModelSpace 均实现了 trace 接口(记录 __init__ 参数,trace_copy() 重建 shell),正是该序列化体系的基础(nni/common/serializer.py)。
十二、实践小结与阅读指引
综合参考文档与源码,NNI NAS 的典型落地路径是:
- 定义空间:用
LayerChoice/InputChoice/Repeat/Cell或 Hub 预置空间(NasBench201、DARTS等)构造ModelSpace,注意为 mutable 指定 label 或提供label_prefix; - 选择评估器:简单场景用
FunctionalEvaluator,分类/回归用Classification/Regression,复杂训练用Lightning;若评估器自身含超参,继承MutableEvaluator并nni.trace; - 选定策略:需要精确指标用多试次策略(
GridSearch、Random、RegularizedEvolution、PolicyBasedRL、TPE),追求训练效率用 one-shot 策略(RandomOneShot、ENAS、DARTS、GumbelDARTS、Proxyless); - 优化目标:通过
Profiler(FLOPs、nn-Meter 延迟)为搜索注入硬件指标; - 编排运行:以
NasExperiment组装以上全部,配合执行引擎与可选的 CGO 跨图优化;需要快速验证搜索质量时,把NAS-Bench-101/201/NDS当作离线数据集。
进一步阅读当前仓库的对应材料:NAS 总览文档、搜索空间构造指南、可执行引擎、探索策略、评估器 与 基准。源码入口统一在 nni/nas 目录,测试用例见 test/algo/nas 与 test/ut/nas,可作为理解各 API 行为边界的权威参考。