.. _serial:

=============
序列化
=============
.. currentmodule:: qlib

简介
============
``Qlib`` 支持将 ``DataHandler``、``DataSet``、``Processor`` 和 ``Model`` 等对象的状态转储到磁盘并重新加载。

可序列化类
==================

``Qlib`` provides a base class ``qlib.utils.serial.Serializable``, whose state can be dumped into or loaded from disk in `pickle` format.
当用户转储 ``Serializable`` 实例的状态时，实例中名称**不以** `_` 开头的属性将被保存到磁盘。
但用户可以通过 ``config`` 方法或重写 ``default_dump_all`` 属性来禁用此功能。

用户还可以重写 ``pickle_backend`` 属性来选择 pickle 后端。支持的值为 "pickle"（默认且通用）和 "dill"（可转储更多内容如函数，详见 `此处 <https://pypi.org/project/dill/>`_）。

示例
=======
``Qlib`` 的可序列化类包括 ``DataHandler``、``DataSet``、``Processor`` 和 ``Model`` 等，它们都是 ``qlib.utils.serial.Serializable`` 的子类。
具体而言，``qlib.data.dataset.DatasetH`` 就是其中之一。用户可按以下方式序列化 ``DatasetH``。

.. code-block:: Python

    ##=============dump dataset=============
    dataset.to_pickle(path="dataset.pkl") # dataset is an instance of qlib.data.dataset.DatasetH

    ##=============reload dataset=============
    with open("dataset.pkl", "rb") as file_dataset:
        dataset = pickle.load(file_dataset)

.. note::
    只有 ``DatasetH`` 的状态应被保存到磁盘，例如用于数据归一化的某些 `均值` 和 `方差` 等。

    重新加载 ``DatasetH`` 后，用户需要重新初始化它。这意味着用户可以重置 ``DatasetH`` 或 ``QlibDataHandler`` 的某些状态，例如 `instruments`、`start_time`、`end_time` 和 `segments` 等，并根据这些状态生成新数据（数据不属于状态，不应保存到磁盘）。

A more detailed example is in this `link <https://github.com/microsoft/qlib/tree/main/examples/highfreq>`_.


API
===
请参阅 `序列化API <../reference/api.html#module-qlib.utils.serial.Serializable>`_。