.. _workflow: ============================= 工作流：工作流管理 ============================= .. currentmodule:: qlib 简介 ============ The components in `Qlib Framework <../introduction/introduction.html#framework>`_ are designed in a loosely-coupled way. Users could build their own Quant research workflow with these components like `Example `_. 此外，``Qlib`` 提供了更友好的接口 ``qrun``，用于自动运行由配置定义的整个工作流程。运行整个工作流程被称为一次`执行`。 通过 ``qrun``，用户可以轻松启动一次`执行`，包含以下步骤： - 数据 - 加载 - 处理 - 切片 - 模型 - 训练与推理 - 保存与加载 - 评估 - 预测信号分析 - 回测 对于每次`执行`，``Qlib`` 拥有完整的系统来追踪训练、推理和评估阶段生成的所有信息及产物。有关 ``Qlib`` 如何处理这些内容的更多信息，请参阅相关文档：`记录器：实验管理 <../component/recorder.html>`_。 完整示例 ================ 在深入细节之前，这里展示一个 ``qrun`` 的完整示例，它定义了典型量化研究中的工作流程。 以下是 ``qrun`` 的典型配置文件。 .. code-block:: YAML qlib_init: provider_uri: "~/.qlib/qlib_data/cn_data" region: cn market: &market csi300 benchmark: &benchmark SH000300 data_handler_config: &data_handler_config start_time: 2008-01-01 end_time: 2020-08-01 fit_start_time: 2008-01-01 fit_end_time: 2014-12-31 instruments: *market port_analysis_config: &port_analysis_config strategy: class: TopkDropoutStrategy module_path: qlib.contrib.strategy.strategy kwargs: topk: 50 n_drop: 5 signal: backtest: start_time: 2017-01-01 end_time: 2020-08-01 account: 100000000 benchmark: *benchmark exchange_kwargs: limit_threshold: 0.095 deal_price: close open_cost: 0.0005 close_cost: 0.0015 min_cost: 5 task: model: class: LGBModel module_path: qlib.contrib.model.gbdt kwargs: loss: mse colsample_bytree: 0.8879 learning_rate: 0.0421 subsample: 0.8789 lambda_l1: 205.6999 lambda_l2: 580.9768 max_depth: 8 num_leaves: 210 num_threads: 20 dataset: class: DatasetH module_path: qlib.data.dataset kwargs: handler: class: Alpha158 module_path: qlib.contrib.data.handler kwargs: *data_handler_config segments: train: [2008-01-01, 2014-12-31] valid: [2015-01-01, 2016-12-31] test: [2017-01-01, 2020-08-01] record: - class: SignalRecord module_path: qlib.workflow.record_temp kwargs: {} - class: PortAnaRecord module_path: qlib.workflow.record_temp kwargs: config: *port_analysis_config 将配置保存到 `configuration.yaml` 后，用户可以通过以下单条命令启动工作流并测试他们的想法。 .. code-block:: bash qrun configuration.yaml 如果用户想在调试模式下使用 ``qrun``，请使用以下命令： .. code-block:: bash python -m pdb qlib/cli/run.py examples/benchmarks/LightGBM/workflow_config_lightgbm_Alpha158.yaml .. note:: 安装 ``Qlib`` 时，`qrun` 将被放置到您的 $PATH 目录中。 .. note:: `yaml` 文件中的 `&` 符号表示字段的锚点，当其他字段需要将该参数作为值的一部分时非常有用。以上述配置文件为例，用户可以直接修改 `market` 和 `benchmark` 的值，而无需遍历整个配置文件。 配置文件 ================== 本节将详细介绍 ``qrun`` 的使用方法。 在使用 ``qrun`` 之前，用户需要准备一个配置文件。以下内容展示了如何准备配置文件的各个部分。 配置文件的设计逻辑非常简单。它预定义了固定的工作流程，并通过这个 yaml 接口让用户定义如何初始化每个组件。 它遵循 `init_instance_by_config `_ 的设计。该接口定义了 Qlib 每个组件的初始化方式，通常包括类和初始化参数。 例如，以下 yaml 和代码是等价的。 .. code-block:: YAML model: class: LGBModel module_path: qlib.contrib.model.gbdt kwargs: loss: mse colsample_bytree: 0.8879 learning_rate: 0.0421 subsample: 0.8789 lambda_l1: 205.6999 lambda_l2: 580.9768 max_depth: 8 num_leaves: 210 num_threads: 20 .. code-block:: python from qlib.contrib.model.gbdt import LGBModel kwargs = { "loss": "mse" , "colsample_bytree": 0.8879, "learning_rate": 0.0421, "subsample": 0.8789, "lambda_l1": 205.6999, "lambda_l2": 580.9768, "max_depth": 8, "num_leaves": 210, "num_threads": 20, } LGBModel(kwargs) Qlib 初始化部分 ----------------- 首先，配置文件需要包含几个基本参数，这些参数将用于初始化qlib。 .. code-block:: YAML provider_uri: "~/.qlib/qlib_data/cn_data" region: cn 各字段含义如下： - `provider_uri` 类型：str。Qlib数据的URI。例如，可以是``get_data.py``加载的数据存储位置。 - `region` - 若`region` == "us"，``Qlib``将以美股模式初始化。 - 若`region` == "cn"，``Qlib``将以A股模式初始化。 .. note:: `region`的值应与`provider_uri`中存储的数据保持一致。 任务模块 ------------ 配置中的`task`字段对应一个`task`，包含三个不同子模块的参数：`Model`、`Dataset`和`Record`。 模型模块 ~~~~~~~~~~~~~ 在`task`字段中，`model`模块描述了用于训练和推理的模型参数。有关基础``Model``类的更多信息，请参阅`Qlib模型 <../component/model.html>`_。 .. code-block:: YAML model: class: LGBModel module_path: qlib.contrib.model.gbdt kwargs: loss: mse colsample_bytree: 0.8879 learning_rate: 0.0421 subsample: 0.8789 lambda_l1: 205.6999 lambda_l2: 580.9768 max_depth: 8 num_leaves: 210 num_threads: 20 各字段含义如下： - `class` 类型：str。模型类的名称。 - `module_path` 类型：str。模型在qlib中的路径。 - `kwargs` 模型的关键字参数。更多信息请参考具体模型实现：`models `_。 .. note:: ``Qlib`` 提供了一个名为 ``init_instance_by_config`` 的工具，用于通过包含 `class`、`module_path` 和 `kwargs` 字段的配置来初始化 ``Qlib`` 内部的任何类。 数据集部分 ~~~~~~~~~~~~~~~ `dataset` 字段描述了 ``Qlib`` 中 ``Dataset`` 模块以及 ``DataHandler`` 模块的参数。关于 ``Dataset`` 模块的更多信息，请参阅 `Qlib Data <../component/data.html#dataset>`_。 ``DataHandler`` 的关键字参数配置如下： .. code-block:: YAML data_handler_config: &data_handler_config start_time: 2008-01-01 end_time: 2020-08-01 fit_start_time: 2008-01-01 fit_end_time: 2014-12-31 instruments: *market 用户可以查阅 `DataHandler <../component/data.html#datahandler>`_ 的文档以了解配置中各字段的含义。 以下是 ``Dataset`` 模块的配置，该模块将在训练和测试阶段负责数据预处理和切片。 .. code-block:: YAML dataset: class: DatasetH module_path: qlib.data.dataset kwargs: handler: class: Alpha158 module_path: qlib.contrib.data.handler kwargs: *data_handler_config segments: train: [2008-01-01, 2014-12-31] valid: [2015-01-01, 2016-12-31] test: [2017-01-01, 2020-08-01] 记录部分 ~~~~~~~~~~~~~~ `record` 字段是关于 ``Qlib`` 中 ``Record`` 模块的参数。``Record`` 负责以标准格式跟踪训练过程和结果，例如 `信息系数(IC)` 和 `回测`。 以下脚本是 `回测` 及其使用的 `策略` 的配置： .. code-block:: YAML port_analysis_config: &port_analysis_config strategy: class: TopkDropoutStrategy module_path: qlib.contrib.strategy.strategy kwargs: topk: 50 n_drop: 5 signal: backtest: limit_threshold: 0.095 account: 100000000 benchmark: *benchmark deal_price: close open_cost: 0.0005 close_cost: 0.0015 min_cost: 5 For more information about the meaning of each field in configuration of `strategy` and `backtest`, users can look up the documents: `Strategy <../component/strategy.html>`_ and `Backtest <../component/backtest.html>`_. 以下是不同`记录模板`的配置详情，例如 ``SignalRecord`` 和 ``PortAnaRecord``： .. code-block:: YAML record: - class: SignalRecord module_path: qlib.workflow.record_temp kwargs: {} - class: PortAnaRecord module_path: qlib.workflow.record_temp kwargs: config: *port_analysis_config 如需了解更多关于 ``Qlib`` 中 ``Record`` 模块的信息，用户可以参阅相关文档：`记录模板 <../component/recorder.html#record-template>`_。