超参数自动调优
==============

- `超参数自动调优接口`_
- `调参实验描述（profile）类`_
- `（附）简要流程设计`_

基于Anylearn后端引擎提供的强大的训练和任务管理能力，
借助开源工具 `NNI <https://nni.readthedocs.io/zh/stable/index.html>`_ ，
Anylearn SDK提供了一套便捷使用超参数自动调优的接口，
不仅支持Anylearn算法库内置标准算法，
也支持用户本地自定义的外置算法和数据集。

.. Note::
    超参数调优的相关概念参见
    `AutoML.org超参数调优 <https://www.automl.org/hpo-overview/>`_ 。

用户使用超参数自动调优的前提是对目标算法有基本的认知，
熟悉算法的所有超参数的类型、格式以及取值范围。
另外，不同超参数对算法效果的影响也不尽相同，
了解算法的哪些超参数有调优价值会使自动调优的过程更加高效。

超参数自动调优的本质是最优化过程，
其使用的优化方法大多是搜索类算法，如：随机搜索、网格搜索等等。
因此，使用超参数自动调优时需要用户定义一个超参数搜索空间，
为每一个要调优的超参数定义一套取值方式和取值范围。
Anylearn SDK中集成了 开源工具 `NNI <https://nni.readthedocs.io/zh/stable/index.html>`_ 
来统筹超参数自动调优过程，
并沿用了其超参数搜索空间的定义方式，
参见 `NNI超参数搜索空间 <https://nni.readthedocs.io/zh/stable/Tutorial/SearchSpaceSpec.html>`_ 。

调参过程中出了搜索空间之外还有其他一些配置项，
用以控制调参的时长、优化算法、本地执行环境等等。
目前接受的配置包括：

- 超参数搜索空间
- 最大调优任务数（到量终止调优）
- 最长调优总时间（到时终止调优）
- 调优算法
- 调优模式（最大化或最小化指标）
- 本地端口绑定

此外，SDK中提供了一套管理超参数自动调优实验的方法，
即 `调参实验描述（profile）类`_ 。
一个调参实验的描述包括了调参任务配置、训练配置以及算法、数据集、训练的元信息等几方面，
用户可以根据这些信息可以在多次调参实验之间进行区别和回忆。
调参实验描述中封装了一系列与实验相关的功能，
如：获取全部实验、获取某一实验、停止实验、重启实验、输出最佳模型等等，
以便对任一调参实验的生命周期进行完整的回溯和管理。

.. Note::

    版本 ``0.11.0`` 新特性：创建调参实验时，需要额外增加计算资源请求（单次训练）

超参数自动调优接口
------------------

.. autofunction:: anylearn.applications.hpo.run_hpo

调参实验描述（profile）类
-------------------------

.. autoclass:: anylearn.applications.hpo_experiment.HpoExperiment
    :members:
    :member-order: bysource
    :special-members: __init__

（附）简要流程设计
------------------

SDK实现的超参数自动调优功能的简要流程如下图所示：

.. figure:: ../_static/img/api-proc-hpo.png
    :width: 800px
    :align: center
    :height: 1075px
    :alt: Anylearn SDK HPO
    :figclass: align-center

    Anylearn SDK超参数自动调优流程图