NNI NAS API 参考指南:从搜索空间构建到策略编排的完整实践

原创2026-09-22 20:30:171,647 阅读
文章标签:人工智能AutoML机器学习深度学习模型压缩模型量化模型优化特征工程MLOps数据可视化

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 的典型落地路径是:

  1. 定义空间:用 LayerChoice / InputChoice / Repeat / Cell 或 Hub 预置空间(NasBench201、DARTS 等)构造 ModelSpace,注意为 mutable 指定 label 或提供 label_prefix;
  2. 选择评估器:简单场景用 FunctionalEvaluator,分类/回归用 Classification / Regression,复杂训练用 Lightning;若评估器自身含超参,继承 MutableEvaluator 并 nni.trace;
  3. 选定策略:需要精确指标用多试次策略(GridSearch、Random、RegularizedEvolution、PolicyBasedRL、TPE),追求训练效率用 one-shot 策略(RandomOneShot、ENAS、DARTS、GumbelDARTS、Proxyless);
  4. 优化目标:通过 Profiler(FLOPs、nn-Meter 延迟)为搜索注入硬件指标;
  5. 编排运行:以 NasExperiment 组装以上全部,配合执行引擎与可选的 CGO 跨图优化;需要快速验证搜索质量时,把 NAS-Bench-101/201/NDS 当作离线数据集。

进一步阅读当前仓库的对应材料:NAS 总览文档、搜索空间构造指南、可执行引擎、探索策略、评估器 与 基准。源码入口统一在 nni/nas 目录,测试用例见 test/algo/nas 与 test/ut/nas,可作为理解各 API 行为边界的权威参考。

登录后查看全文
nni