NNI 搜索空间(Search Space)完全指南:从 JSON 定义到 11 种采样策略与 Tuner 兼容矩阵

原创2026-09-21 12:13:301,892 阅读
文章标签:人工智能AutoML机器学习深度学习模型压缩模型量化模型优化特征工程MLOps数据可视化

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 文件方式。

搜索空间的调优实践要点

结合上述语法与源码,给出几条可直接落地的实践建议:

  1. 先核对 Tuner 兼容性:在设计搜索空间前,先对照上文支持矩阵确认所选 Tuner 覆盖你需要的所有 _type。例如选了 SMAC 就不要在空间里放 normal/qnormal/lognormal/qlognormal;GP、Metis、DNGO 的 choice 只能放数值候选。
  2. 数量级参数优先用对数分布:学习率、正则化强度等跨数量级的参数,用 loguniform(或 qloguniform)通常比 uniform 更高效。
  3. 整数有序性要求高时用 quniform 且 q=1:由于部分 Tuner 把 randint 当作无序类别,若希望所有 Tuner 尊重整数顺序,请改用 quniform。
  4. 依赖结构用嵌套 choice:参数 A 只有在参数 B 选中某个分支时才存在,就用带 _name 的嵌套子搜索空间表达,并确认 Tuner 在嵌套支持列表中(TPE / Random / Grid Search / Anneal / Evolution)。
  5. 让校验提前兜底: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"的顺序执行,可以最大程度避免配置返工。

登录后查看全文
nni