.. _model:

===========================================
预测模型：模型训练与预测
===========================================

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

``Forecast Model`` 旨在生成股票的`预测分数`。用户可以通过 ``qrun`` 在自动化工作流中使用 ``Forecast Model``，详情请参阅 `工作流：工作流管理 <workflow.html>`_。

由于 ``Qlib`` 的组件采用松耦合方式设计，``Forecast Model`` 也可以作为独立模块使用。

基类与接口
======================

``Qlib`` provides a base class `qlib.model.base.Model <../reference/api.html#module-qlib.model.base>`_ from which all models should inherit.

基类提供以下接口：

.. autoclass:: qlib.model.base.Model
    :members:
    :noindex:

``Qlib`` 还提供了一个基类 `qlib.model.base.ModelFT <../reference/api.html#qlib.model.base.ModelFT>`_，其中包含用于微调模型的方法。

关于其他接口如 `finetune`，请参阅 `Model API <../reference/api.html#module-qlib.model.base>`_。

示例
=======

``Qlib`` 的 `Model Zoo` 包含诸如 ``LightGBM``、``MLP``、``LSTM`` 等模型。这些模型被视为 ``Forecast Model`` 的基准。以下步骤展示了如何将 ``LightGBM`` 作为独立模块运行。

- 首先使用 `qlib.init` 初始化 ``Qlib``，请参阅 `Initialization <../start/initialization.html>`_。
- 运行以下代码获取 `prediction score` `pred_score`
    .. code-block:: Python

        from qlib.contrib.model.gbdt import LGBModel
        from qlib.contrib.data.handler import Alpha158
        from qlib.utils import init_instance_by_config, flatten_dict
        from qlib.workflow import R
        from qlib.workflow.record_temp import SignalRecord, PortAnaRecord

        market = "csi300"
        benchmark = "SH000300"

        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,
        }

        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"),
                    },
                },
            },
        }

        # model initialization
        model = init_instance_by_config(task["model"])
        dataset = init_instance_by_config(task["dataset"])

        # start exp
        with R.start(experiment_name="workflow"):
            # train
            R.log_params(**flatten_dict(task))
            model.fit(dataset)

            # prediction
            recorder = R.get_recorder()
            sr = SignalRecord(model, dataset, recorder)
            sr.generate()

    .. note::

        `Alpha158` 是 ``Qlib`` 提供的数据处理器，请参阅 `Data Handler <data.html#data-handler>`_。
        `SignalRecord` 是 ``Qlib`` 中的 `Record Template`，请参阅 `Workflow <recorder.html#record-template>`_。

此外，上述示例已在 ``examples/train_backtest_analyze.ipynb`` 中提供。
从技术上讲，模型预测的含义取决于用户设计的标签设置。
默认情况下，该分数通常表示预测模型对工具的评级。分数越高，工具的盈利能力越强。


自定义模型
============

Qlib 支持自定义模型。如果用户有兴趣定制自己的模型并将其集成到 ``Qlib`` 中，请参阅 `自定义模型集成 <../start/integration.html>`_。


API
===
请参阅 `模型API <../reference/api.html#module-qlib.model.base>`_。