NNI 搜索空间(Search Space)完全指南:从 JSON 定义到 11 种采样策略与 Tuner 兼容矩阵
NNI 搜索空间(Search Space)完全指南:从 JSON 定义到 11 种采样策略与 Tuner 兼容矩阵
导读
在 NNI(Neural Network Intelligence)这一开源 AutoML 工具包中,搜索空间(Search Space)是超参数调优(HPO)的起点:Tuner 依据搜索空间来采样超参数,而用户则需要为每个变量声明名称、采样策略类型(_type)及其参数(_value)。本文以官方文档 docs/source/hpo/search_space.rst 为骨架,系统讲解搜索空间的 JSON 定义语法、全部 11 种采样策略的语义与边界、嵌套搜索空间的声明方式、内置 Tuner 的支持矩阵,并结合 nni/common/hpo_utils/validation.py 与 nni/common/hpo_utils/formatting.py 等源码,从校验规则与内部表示两个层面揭示底层原理。读完本文,你将能独立为任意 NNI 实验设计正确、可复现且与所选 Tuner 兼容的搜索空间。
搜索空间是什么
在 NNI 中,超参数调优实验的全部候选参数范围由搜索空间定义。Tuner(调参器)按照搜索空间的约束,为每个 Trial 生成一组超参数组合;Trial 代码通过 nni.get_next_parameter() 获取这组参数并运行训练。搜索空间通常以 JSON 文件(或 YAML / Python dict)的形式提供给实验配置,并通过 search_space 或 search_space_file 字段注入到 ExperimentConfig 中(见 nni/experiment/config/experiment_config.py)。
搜索空间是一个 JSON 对象:每个键是超参数变量的名称,每个值是一个包含 _type 与 _value 两个字段的对象。_type 指明采样策略,_value 是其参数列表。一个典型的定义如下:
{
"dropout_rate": {"_type": "uniform", "_value": [0.1, 0.5]},
"conv_size": {"_type": "choice", "_value": [2, 3, 5, 7]},
"hidden_size": {"_type": "choice", "_value": [124, 512, 1024]},
"batch_size": {"_type": "choice", "_value": [50, 250, 500]},
"learning_rate": {"_type": "uniform", "_value": [0.0001, 0.1]}
}
以第一行为例:dropout_rate 被定义为一个先验服从均匀分布(uniform)的变量,取值区间为 [0.1, 0.5]。
注意:搜索空间内可用的采样策略取决于你选用的 Tuner。下文会列出每个内置 Tuner 支持的类型。对于自定义 Tuner,你不必遵循本约定,可以自由定义任意类型(此时 NNI 的官方校验将不再适用)。
搜索空间的类型与采样语义
以下列出全部 11 种采样策略及其参数含义。这些类型与 nni/common/hpo_utils/validation.py 中定义的 common_search_space_types 完全一致,内置 Tuner 的搜索空间校验正是以这份清单为基准。
choice(离散选择)
{"_type": "choice", "_value": options}
- 变量的取值是
options列表中的某一个元素。options应为数字列表或字符串列表。使用任意对象(如子列表、数字与字符串的混合、null 值)在大多数情况下也能工作,但可能触发未定义行为。 options也可以是一个嵌套的子搜索空间:该子搜索空间仅在对应元素被选中时才生效,其中的变量可视为条件变量。仓库提供了完整的嵌套搜索空间定义示例,见 examples/trials/mnist-nested-search-space/search_space.json。如果 options 中的某个元素是 dict,即表示一个子搜索空间;对于内置 Tuner,你必须在这个 dict 中加入_name键,用于标识哪个元素被选中。对应的采样结果示例如 examples/trials/mnist-nested-search-space/sample.json。下表给出了支持嵌套搜索空间的 Tuner 列表。
randint(随机整数)
{"_type": "randint", "_value": [lower, upper]}
- 在
lower(包含)与upper(不包含)之间随机选择一个整数。 - 注意:不同 Tuner 对
randint的解释可能不同。部分 Tuner(如 TPE、GridSearch)把区间内的整数当作无序类别处理,而另一些(如 SMAC)则尊重其顺序关系。如果你希望所有 Tuner 都按有序整数处理,请改用quniform并令q=1。
uniform(均匀分布)
{"_type": "uniform", "_value": [low, high]}
- 变量在
low与high之间均匀采样。 - 在优化时,该变量被约束为双侧有界区间。
quniform(量化均匀分布)
{"_type": "quniform", "_value": [low, high, q]}
- 取值由
clip(round(uniform(low, high) / q) * q, low, high)决定,其中 clip 操作将生成值约束在上下界内。例如_value为[0, 10, 2.5]时,可能取值为[0, 2.5, 5.0, 7.5, 10.0];_value为[2, 10, 5]时,可能取值为[2, 5, 10]。 - 适用于目标函数对取值仍有一定"平滑性"、但取值需离散且上下有界的情形。如果想从区间
[low, high]中均匀取整数,把_value写成[low, high, 1]即可。
loguniform(对数均匀分布)
{"_type": "loguniform", "_value": [low, high]}
- 变量按
exp(uniform(log(low), log(high)))从[low, high]中采样,即返回值的对数服从均匀分布。 - 在优化时,该变量被约束为正数。
qloguniform(量化对数均匀分布)
{"_type": "qloguniform", "_value": [low, high, q]}
- 取值由
clip(round(loguniform(low, high) / q) * q, low, high)决定,clip 用于把值约束在上下界内。 - 适用于目标函数随取值增大而愈发平滑、但上下需有界的离散变量(典型如学习率、正则化系数的数量级搜索)。
normal(正态分布)
{"_type": "normal", "_value": [mu, sigma]}
- 变量为服从均值
mu、标准差sigma的正态分布实数值。在优化时,这是一个无约束变量。
qnormal(量化正态分布)
{"_type": "qnormal", "_value": [mu, sigma, q]}
- 取值由
round(normal(mu, sigma) / q) * q决定。 - 适用于取值大概率落在
mu附近、但本质上无界的离散变量。
lognormal(对数正态分布)
{"_type": "lognormal", "_value": [mu, sigma]}
- 变量按
exp(normal(mu, sigma))采样,即返回值的对数服从正态分布。在优化时,该变量被约束为正数。
qlognormal(量化对数正态分布)
{"_type": "qlognormal", "_value": [mu, sigma, q]}
- 取值由
round(exp(normal(mu, sigma)) / q) * q决定。 - 适用于目标函数随变量取值增大而愈发平滑、且仅单侧有界的离散变量。
类型校验规则:源码视角
搜索空间并不是随意写的,validate_search_space 会做严格的格式与范围检查(见 nni/common/hpo_utils/validation.py)。理解这些规则可以避免最常见的配置错误:
- 结构要求:搜索空间必须是 dict;每个变量的 spec 必须是 dict,且必须同时包含
_type与_value;_type必须位于support_types白名单内;_value必须是 list。 - 参数个数:所有
q*类型必须恰好 3 个参数,其余类型必须恰好 2 个参数。 - 数值类型:
randint的两个参数必须是 int;其余类型(normal 族除外)的参数必须是 float/int。 - 范围约束:非 normal 类型要求
high > low;含log的类型要求low > 0(对数分布的下界必须为正);normal 类型要求sigma > 0。 - choice 约束:默认情况下 choice 只能包含数字或字符串;若第一个元素是 dict 且含
_name,则被识别为嵌套搜索空间(见 validation.py)。
校验失败时函数会抛出 ValueError 并给出具体变量名与原因;若 raise_exception=False,则只记录错误日志并返回 False。此外,validate_search_space 的第 2 个参数 support_types 允许 Tuner 声明自己支持的类型子集——这正是下文"各 Tuner 支持矩阵"的实现基础。
各 Tuner 支持的搜索空间类型
内置 Tuner 对搜索空间类型的支持并不一致。下表完整列出 NNI 文档中给出的兼容矩阵(✓ 表示支持):
| Tuner | choice | choice(嵌套) | randint | uniform | quniform | loguniform | qloguniform | normal | qnormal | lognormal | qlognormal |
|---|---|---|---|---|---|---|---|---|---|---|---|
| TPE | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Random | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Grid Search | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Anneal | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Evolution | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| SMAC | ✓ | — | ✓ | ✓ | ✓ | ✓ | — | — | — | — | — |
| Batch | ✓ | — | — | — | — | — | — | — | — | — | — |
| Hyperband | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Metis | ✓ | — | ✓ | ✓ | ✓ | — | — | — | — | — | — |
| BOHB | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| GP | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | — | — | — | — |
| PBT | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| DNGO | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | — | — | — | — |
从源码看,支持面的差异源于各 Tuner 对参数内部表示的处理方式不同。以 Random 为例,其 suggest_parameter 依据 ParameterSpec 的 categorical、normal_distributed 等标记分别调用整数采样、正态采样与均匀采样(见 nni/algorithms/hpo/random_tuner.py),因此可以覆盖全部类型;而 GP、Metis、DNGO 等基于高斯过程回归(GPR)的 Tuner,天然需要数值距离度量,无法处理非数值候选,故对 normal 族(以及嵌套 choice)的支持受限。
已知限制
- 仅支持数值:GP Tuner、Metis Tuner 与 DNGO Tuner 的搜索空间只支持数值(其他 Tuner 的
choice可以包含非数值,如字符串)。原因在于 GP 与 Metis 都使用高斯过程回归(GPR)——GPR 基于核函数与样本点之间的"距离"做预测,而非数值之间难以计算真正的距离。 - 嵌套搜索空间:只有 TPE / Random / Grid Search / Anneal / Evolution 这 5 个 Tuner 支持嵌套搜索空间。
嵌套搜索空间:条件变量的声明与使用
嵌套搜索空间是 NNI 表达"条件参数"的官方手段:当 choice 的某个候选项本身是一个 dict 时,dict 内部可以继续包含其他搜索空间变量,这些变量仅在对应候选被选中时才会被采样。以仓库自带的 MNIST 示例 examples/trials/mnist-nested-search-space/search_space.json 为例,每一层 layer0 ~ layer3 都可以从 Empty、Conv、Max_pool、Avg_pool 中选择一个操作:
{
"layer0": {
"_type": "choice",
"_value": [
{"_name": "Empty"},
{"_name": "Conv", "kernel_size": {"_type": "choice", "_value": [1, 2, 3, 5]}},
{"_name": "Max_pool", "pooling_size": {"_type": "choice", "_value": [2, 3, 5]}},
{"_name": "Avg_pool", "pooling_size": {"_type": "choice", "_value": [2, 3, 5]}}
]
}
}
关键约束:每个嵌套候选项 dict 都必须包含 _name 字段,用于在采样结果中标识被选中的分支。对应的采样结果如 examples/trials/mnist-nested-search-space/sample.json 所示——layer1 被选为 Conv 时,kernel_size 同时被采样为 2;layer2 被选为 Empty 时,其下不再出现任何条件变量:
{
"layer0": {"_name": "Avg_pool", "pooling_size": 3},
"layer1": {"_name": "Conv", "kernel_size": 2},
"layer2": {"_name": "Empty"},
"layer3": {"_name": "Conv", "kernel_size": 5}
}
从源码看,嵌套结构在内部被扁平化为带路径 key 的 ParameterSpec 列表:format_search_space 遇到嵌套 choice 时,会为每个候选项生成 (父变量名, 变量名, 下标) 形式的 key,并递归展开其子空间(见 nni/common/hpo_utils/formatting.py)。ParameterSpec.is_activated_in 则通过判断父 choice 的选中下标来决定当前参数是否参与采样(见 formatting.py),这正是"条件变量"机制的底层实现。deformat_parameters 负责把扁平的内部表示还原为带 _name 的嵌套结构(见 formatting.py)。
搜索空间在实验配置中的接入方式
定义好搜索空间后,需要把它接入实验。在 ExperimentConfig 中,search_space 与 search_space_file 两个字段二选一(必须且只能设置一个,否则会抛出 ValueError,见 nni/experiment/config/experiment_config.py):
from nni.experiment import Experiment
experiment = Experiment('local')
# 方式一:直接传入 dict
experiment.config.search_space = {
'dropout_rate': {'_type': 'uniform', '_value': [0.1, 0.5]},
'learning_rate': {'_type': 'loguniform', '_value': [0.0001, 0.1]},
}
# 方式二:从 JSON/YAML 文件加载
experiment.config.search_space_file = 'search_space.json'
experiment.config.tuner.name = 'TPE'
experiment.config.trial_command = 'python mnist.py'
experiment.config.max_trial_number = 20
experiment.run(8080)
search_space_file 支持 JSON 与 YAML 格式,由 _load_search_space_file 读取并解析(见 experiment_config.py)。如果使用 YAML,可以直接用 .yml 文件组织搜索空间,与 config.yml 中 authorName、trialConcurrency 等字段并列。仓库中的多数示例(如 examples/trials/mnist-pytorch 系列)都采用 search_space.json 文件方式。
搜索空间的调优实践要点
结合上述语法与源码,给出几条可直接落地的实践建议:
- 先核对 Tuner 兼容性:在设计搜索空间前,先对照上文支持矩阵确认所选 Tuner 覆盖你需要的所有
_type。例如选了 SMAC 就不要在空间里放normal/qnormal/lognormal/qlognormal;GP、Metis、DNGO 的choice只能放数值候选。 - 数量级参数优先用对数分布:学习率、正则化强度等跨数量级的参数,用
loguniform(或qloguniform)通常比uniform更高效。 - 整数有序性要求高时用
quniform且q=1:由于部分 Tuner 把randint当作无序类别,若希望所有 Tuner 尊重整数顺序,请改用quniform。 - 依赖结构用嵌套 choice:参数 A 只有在参数 B 选中某个分支时才存在,就用带
_name的嵌套子搜索空间表达,并确认 Tuner 在嵌套支持列表中(TPE / Random / Grid Search / Anneal / Evolution)。 - 让校验提前兜底:NNI 在校验不通过时会给出包含变量名与原因的
ValueError。如果看到search space "xxx" must have high > low或must have low > 0之类的报错,请优先检查区间顺序、对数分布下界与q*类型的参数个数。
总结
搜索空间是 NNI HPO 实验的定义层,直接决定了 Tuner 的采样能力与最终调优效果。本文完整覆盖了 11 种采样策略的语义、参数边界与校验规则,给出了官方兼容矩阵与已知限制,并结合 nni/common/hpo_utils/validation.py、nni/common/hpo_utils/formatting.py 以及嵌套搜索空间示例 examples/trials/mnist-nested-search-space/search_space.json 说明了底层校验与展开机制。在动手写搜索空间之前,建议按"选 Tuner → 对照矩阵选类型 → 写 JSON → 接入 ExperimentConfig"的顺序执行,可以最大程度避免配置返工。