.. _task_management:

===============
任务管理
===============
.. currentmodule:: qlib


简介
============

`工作流 <../component/introduction.html>`_ 部分介绍了如何以松耦合的方式运行研究流程。但使用 ``qrun`` 时只能执行一个 ``任务``。
为了自动生成和执行不同任务，``任务管理`` 提供了完整流程，包括 `任务生成`_、`任务存储`_、`任务训练`_ 和 `任务收集`_。
通过该模块，用户可以在不同周期、使用不同损失函数甚至不同模型自动运行其 ``任务``。任务生成、模型训练以及数据合并收集的流程如下图所示。

.. image:: ../_static/img/Task-Gen-Recorder-Collector.svg
    :align: center

该完整流程可用于 `在线服务 <../component/online.html>`_。

完整流程示例参见 `此处 <https://github.com/microsoft/qlib/tree/main/examples/model_rolling/task_manager_rolling.py>`__。

任务生成
===============
一个 ``task`` 由 `Model`、`Dataset`、`Record` 或用户添加的任何内容组成。
具体任务模板可查看 
`任务章节 <../component/workflow.html#task-section>`_。
尽管任务模板是固定的，但用户可以通过自定义 ``TaskGen`` 来基于任务模板生成不同的 ``task``。

以下是 ``TaskGen`` 的基类：

.. autoclass:: qlib.workflow.task.gen.TaskGen
    :members:
    :noindex:

``Qlib`` provides a class `RollingGen <https://github.com/microsoft/qlib/tree/main/qlib/workflow/task/gen.py>`_ to generate a list of ``task`` of the dataset in different date segments.
This class allows users to verify the effect of data from different periods on the model in one experiment. More information is `here <../reference/api.html#TaskGen>`__.

任务存储
============
To achieve higher efficiency and the possibility of cluster operation, ``Task Manager`` will store all tasks in `MongoDB <https://www.mongodb.com/>`_.
``TaskManager`` 能自动获取未完成任务，并通过错误处理管理一组任务的生命周期。
使用此模块时，用户**必须**完成 `MongoDB <https://www.mongodb.com/>`_ 的配置。

用户需在 `初始化 <../start/initialization.html#Parameters>`_ 时提供MongoDB URL和数据库名称以使用 ``TaskManager``，或进行如下声明。

    .. code-block:: python

        from qlib.config import C
        C["mongo"] = {
            "task_url" : "mongodb://localhost:27017/", # your MongoDB url
            "task_db_name" : "rolling_db" # database name
        }

.. autoclass:: qlib.workflow.task.manage.TaskManager
    :members:
    :noindex:

关于 ``Task Manager`` 的更多信息可查阅 `此处 <../reference/api.html#TaskManager>`__。

任务训练
=============
生成并存储这些 ``task`` 后，就可以运行处于 *WAITING* 状态的 ``task`` 了。
``Qlib`` 提供了名为 ``run_task`` 的方法来运行任务池中的 ``task``，但用户也可以自定义任务的执行方式。
获取 ``task_func`` 的简单方法是直接使用 ``qlib.model.trainer.task_train``。
它将运行由 ``task`` 定义的完整工作流，包括 *模型*、*数据集*、*记录*。

.. autofunction:: qlib.workflow.task.manage.run_task
    :noindex:

同时，``Qlib`` 提供了一个名为 ``Trainer`` 的模块。 

.. autoclass:: qlib.model.trainer.Trainer
    :members:
    :noindex:

``Trainer`` 将训练一系列任务并返回一组模型记录器。
``Qlib`` 提供两种 Trainer，TrainerR 是最简单的方式，而 TrainerRM 基于 TaskManager 来自动管理任务生命周期。
如果您不想使用 ``Task Manager`` 来管理任务，那么使用 TrainerR 来训练由 ``TaskGen`` 生成的任务列表就足够了。
`此处 <../reference/api.html#Trainer>`_ 是关于不同 ``Trainer`` 的详细信息。

任务收集
===============
在收集模型训练结果前，您需要使用 ``qlib.init`` 指定 mlruns 的路径。

为了收集训练后的 ``task`` 结果，``Qlib`` 提供了 `Collector <../reference/api.html#Collector>`_、`Group <../reference/api.html#Group>`_ 和 `Ensemble <../reference/api.html#Ensemble>`_，以可读、可扩展且松耦合的方式收集结果。

`Collector <../reference/api.html#Collector>`_ 可以从任何地方收集对象并进行处理，如合并、分组、平均等。它包含两个步骤操作：``collect``（将任何内容收集到字典中）和 ``process_collect``（处理收集到的字典）。

`Group <../reference/api.html#Group>`_ 也包含两个步骤：``group``（基于 `group_func` 对一组对象进行分组并将其转换为字典）和 ``reduce``（基于某些规则将字典转换为集成）。
例如：{(A,B,C1): object, (A,B,C2): object} ---``group``---> {(A,B): {C1: object, C2: object}} ---``reduce``---> {(A,B): object}

`Ensemble <../reference/api.html#Ensemble>`_ 可以合并集成中的对象。
例如：{C1: object, C2: object} ---``Ensemble``---> object。
您可以在 ``Collector`` 的 process_list 中设置所需的集成。
常见的集成包括 ``AverageEnsemble`` 和 ``RollingEnsemble``。平均集成用于集成同一时间段内不同模型的结果，滚动集成用于集成同一时间段内不同模型的结果

因此层级关系是：``Collector`` 的第二步对应 ``Group``，而 ``Group`` 的第二步对应 ``Ensemble``。

更多信息，请参阅 `Collector <../reference/api.html#Collector>`_、`Group <../reference/api.html#Group>`_ 和 `Ensemble <../reference/api.html#Ensemble>`_，或查看 `示例 <https://github.com/microsoft/qlib/tree/main/examples/model_rolling/task_manager_rolling.py>`_。