NNI 在 Windows 上的安装与验证：从 pip/源码安装到跑通第一个 HPO 实验

NNI 在 Windows 上的安装与验证：从 pip/源码安装到跑通第一个 HPO 实验

【免费下载链接】nniAn open source AutoML toolkit for automate machine learning lifecycle, including feature engineering, neural architecture search, model compression and hyper-parameter tuning.项目地址: https://gitcode.com/gh_mirrors/nn/nni

NNI（Neural Network Intelligence）是微软开源的 AutoML 工具包，覆盖特征工程、超参调优、神经网络架构搜索与模型压缩等机器学习全生命周期。本文以仓库中的 InstallationWin_zh.rst 为骨架，完整讲解 NNI 在 Windows 平台上的安装前置条件、pip/源码两种安装方式、通过 MNIST 示例验证安装的完整流程，并结合仓库源码与配置深入剖析实验启动的关键细节与常见故障排查。读完本文，你将能够在自己的 Windows 机器上从零安装 NNI，跑通并理解第一个超参调优实验，并具备独立排查 Windows 特有安装问题的能力。

安装前的环境准备

NNI 在 Windows 上的运行依赖若干基础软件，建议在正式安装前逐一确认。原文档将先决条件分为三部分，每一部分都有明确的用途：

在 Windows 上，推荐使用 Anaconda 或 Miniconda 管理多个 Python 环境，这样既便于隔离依赖，也能规避 Windows 上常见的二进制库（DLL）问题。

如果是全新安装的 Python 环境，还需要先安装 Microsoft C++ Build Tools，并通过 pip 预先安装两个编译工具链组件：

pip install cython wheel

从当前仓库的依赖文件可以印证这两个包的必要性：dependencies/develop.txt 中将cython列为开发依赖，而 dependencies/required.txt 中列出的scikit-learn、scipy、numpy、pandas等核心运行时依赖在部分旧版 Python 环境中需要本地编译，缺少 C++ 编译器会导致安装失败（典型报错见下文「simplejson 错误」一节）。

安装 NNI：两种方式

方式一：从 pip 包安装（推荐）

大多数情况下，直接从 pip 安装与升级 NNI 是最方便、快捷的方式：

python -m pip install --upgrade nni

该命令会从 PyPI 拉取最新稳定版 NNI 及其运行时依赖，无需本地编译。NNI 的核心运行时依赖（见 dependencies/required.txt）包括scikit-learn、numpy、scipy、pandas、pyyaml、psutil、prettytable、typeguard、websockets等，覆盖了调度、通信、配置解析与结果展示等能力。

方式二：从源代码安装

如果对某个或最新版本的代码感兴趣，可以通过源代码安装。原文档基于v2.6分支演示，克隆仓库后切换到目标发布标签即可（当前仓库为 nni 的开源镜像，可执行git tag查看镜像中可用的发布标签）：

git clone https://gitcode.com/gh_mirrors/nn/nni.git cd nni python -m pip install -U -r dependencies/setup.txt python -m pip install -r dependencies/develop.txt python setup.py develop

从仓库依赖文件可以进一步理解这三条命令各做了什么：

• dependencies/setup.txt：pip < 23、setuptools < 63、wheel < 0.38，用于约束较老环境下的构建工具链版本，保证setup.py可正常执行；
• dependencies/develop.txt：开发依赖，包含cython、pytest、pytest-cov、coverage、flake8、pylint、sphinx等，主要用于运行测试、代码检查与构建文档；
• python setup.py develop：以开发模式安装，源码改动即时生效，便于调试与贡献代码。

如果要为 NNI 贡献代码，可参考仓库中 贡献指南 与 从源码构建。

验证安装：运行 MNIST 示例

安装完成后，建议立即运行一个真实实验来验证 NNI 是否工作正常。原文档以经典的 MNIST 超参调优示例作为验收标准。

第一步：克隆示例代码

git clone https://gitcode.com/gh_mirrors/nn/nni.git

第二步：理解 Windows 专用实验配置

进入示例目录后，使用 Windows 专用配置启动实验：

nnictl create --config nni\examples\trials\mnist-pytorch\config_windows.yml

仓库中 config_windows.yml 的内容非常简洁，却完整覆盖了 NNI 实验配置的五个核心维度：

searchSpaceFile: search_space.json trialCommand: python mnist.py trialGpuNumber: 0 trialConcurrency: 1 tuner: name: TPE classArgs: optimize_mode: maximize trainingService: platform: local

各字段含义如下：

对照搜索空间文件 search_space.json，可以看到 TPE 调优器会探索的四个超参：batch_size（16/32/64/128 四选一）、hidden_size（128/256/512/1024 四选一）、lr（0.0001～0.1 四选一）以及momentum（0～1 连续均匀分布）：

{ "batch_size": {"_type":"choice", "_value": [16, 32, 64, 128]}, "hidden_size":{"_type":"choice","_value":[128, 256, 512, 1024]}, "lr":{"_type":"choice","_value":[0.0001, 0.001, 0.01, 0.1]}, "momentum":{"_type":"uniform","_value":[0, 1]} }

Trial 脚本 mnist.py 则展示了 NNI SDK 在 Trial 侧的标准用法，这也是理解整条数据流的关键：

• nni.get_next_parameter()从调优器获取一组超参；
• nni.utils.merge_parameter将调优器参数与脚本默认参数合并；
• 每个 epoch 结束后通过nni.report_intermediate_result(test_acc)上报中间结果；
• 训练结束后通过nni.report_final_result(test_acc)上报最终指标，供调优器用于下一轮搜索。

注意：原文档特别提醒，如果熟悉其它框架，可选择examples\trials目录下的其它示例（如 TensorFlow/Keras 版本）。若更换示例，务必检查该示例 YAML 文件中 Trial 命令是否仍为python3，Windows 默认安装的 Python 可执行文件是python.exe，没有python3.exe，因此所有 Trial 命令中的python3都必须改为python。仓库中 config_windows.yml 已按此约定编写。

第三步：解读启动日志

在命令行中等待输出INFO: Successfully started experiment!，该消息表明实验已成功启动：

INFO: Starting restful server... INFO: Successfully started Restful server! INFO: Setting local config... INFO: Successfully set local config! INFO: Starting experiment... INFO: Successfully started experiment! ----------------------------------------------------------------------- The experiment id is egchD4qy The Web UI urls are: http://223.255.255.1:8080 http://127.0.0.1:8080 -----------------------------------------------------------------------

日志的关键信息包括：RESTful 服务（即 Web 界面后端）成功启动、本地配置写入成功、Experiment 正式启动，以及最重要的Experiment ID（如egchD4qy）与Web UI 地址（默认端口 8080，浏览器打开http://127.0.0.1:8080即可访问）。

第四步：用 nnictl 管理实验

nnictl是 NNI 的命令行管理工具，实验启动后可以用以下命令持续监控与操作：

commands description 1. nnictl experiment show show the information of experiments 2. nnictl trial ls list all of trial jobs 3. nnictl top monitor the status of running experiments 4. nnictl log stderr show stderr log content 5. nnictl log stdout show stdout log content 6. nnictl stop stop an experiment 7. nnictl trial kill kill a trial job by id 8. nnictl --help get help information about nnictl

其中nnictl experiment show查看实验概览、nnictl trial ls列出所有 Trial、nnictl top实时监控实验状态、nnictl log stdout/stderr查看 Trial 输出与错误日志、nnictl stop停止实验。完整的命令参考见 nnictl 参考文档。

第五步：通过 Web UI 查看实验详情

在浏览器中打开Web UI url，可看到实验的详细信息以及所有 Trial 任务的运行状态。主页面展示实验整体进度、中间指标曲线与 Trial 列表：

点击任意 Trial 可查看其参数、日志与详细训练过程：

Web 界面的完整功能（指标曲线、超参对比、日志查看等）可参考 Web 界面使用指南。

系统需求

以下是 NNI 在 Windows 上的最低配置，推荐使用 Windows 10 1809 版本。由于程序变更，NNI 的最低配置会有所调整：

补充说明：上述最低配置为原文档基于早期版本给出的基准。从当前仓库 dependencies/required.txt 的依赖声明可以推断，较新版本的 NNI 对 Python 版本的要求已有所提升（例如numpy、scipy在 Python 3.8 以上版本使用无约束的较新版本），建议实际使用时采用较新的 Python 3.8+ 与 Windows 10 较新版本，以获得完整的功能与依赖兼容性。

Windows 常见问题排查

安装 NNI 时出现 simplejson 错误

如果安装过程中出现如下报错，说明缺少 C 编译器，导致simplejson._speedups扩展无法编译：

building 'simplejson._speedups' extension error: [WinError 3] The system cannot find the path specified

确保已安装C++ 14.0 编译器（Microsoft C++ Build Tools）后重试即可。

命令行或 PowerShell 中 Trial 因缺少 DLL 而失败

ImportError: DLL load failed

此错误通常因为缺少LIBIFCOREMD.DLL和LIBMMD.DLL文件，且 SciPy 安装失败所致。使用Anaconda 或 Miniconda + 64 位 Python可以解决——conda 会为 SciPy 等科学计算库提供预编译的二进制包，避免 DLL 缺失问题。

Web 界面上的 Trial 错误

先检查 Trial 日志文件了解详情，如果存在 stderr 文件，也要查看其内容。两种常见情况：

• 忘记将 Experiment 配置的 Trial 命令中的python3改为python——Windows 没有python3.exe可执行文件，Trial 无法启动；
• 忘记安装 Experiment 的依赖（如 TensorFlow、Keras 等）——MNIST-PyTorch 示例的依赖在 requirements.txt（torch与torchvision）中声明，运行前需在对应 Python 环境安装。

无法在 Windows 上使用 BOHB

确保安装了 C++ 14.0 编译器，然后通过 extras 方式安装 BOHB 依赖：

pip install nni[BOHB]

Windows 上不支持的 Tuner

当前版本的 NNI 在 Windows 上不支持 SMAC调优器，原因是其底层对 Linux 环境的依赖（详见 SMAC3 项目的 issue #483）。如需使用 SMAC，请将 Experiment 部署到 Linux 环境。

用 Windows 作为远程节点

如果需要将 Windows 机器作为远程训练节点（Remote Machine 模式），参考 远程模式文档 了解所需的配置（如 SSH/WinRM 连接、Python 环境路径等）与限制。

安装时出现 Segmentation Fault (core dumped)

此类崩溃一般与本地编译的科学计算依赖有关，建议优先切换到 Anaconda/Miniconda 的 64 位 Python 环境后重装，并确保所有依赖（numpy、scipy等）均来自官方渠道而非手工编译。

更多阅读

围绕 NNI 的 Windows 安装与使用，可以继续阅读以下仓库文档：

• NNI 实验概览
• nnictl 命令行工具参考
• Web 界面使用指南
• 搜索空间定义
• 实验配置参考
• 如何在本机运行 Experiment（支持多 GPU 卡）
• 如何在多机上运行 Experiment（远程模式）
• 如何在 OpenPAI 上运行 Experiment
• 如何通过 Kubeflow 在 Kubernetes 上运行 Experiment
• 如何通过 FrameworkController 在 Kubernetes 上运行 Experiment

【免费下载链接】nniAn open source AutoML toolkit for automate machine learning lifecycle, including feature engineering, neural architecture search, model compression and hyper-parameter tuning.项目地址: https://gitcode.com/gh_mirrors/nn/nni