Qlib 记录器：实验管理

介绍

Qlib 包含一个名为 QlibRecorder 的实验管理系统，旨在帮助用户高效地处理实验和分析结果。

该系统有三个组件：

ExperimentManager
一个管理实验的类。
Experiment
一个实验类，每个实例负责一个单独的实验。
Recorder
一个记录器的类，每个实例负责一次单独的运行。

这是系统结构的一般视图：

ExperimentManager
    - Experiment 1
        - Recorder 1
        - Recorder 2
        - ...
    - Experiment 2
        - Recorder 1
        - Recorder 2
        - ...
    - ...

该实验管理系统定义了一组接口，并提供了一个具体实现 MLflowExpManager，该实现基于机器学习平台：MLFlow (link)。

如果用户将 ExpManager 的实现设置为 MLflowExpManager，他们可以使用命令 mlflow ui 来可视化和检查实验结果。有关更多信息，请参阅相关文档 here。

Qlib 记录器

QlibRecorder 为用户提供了一个高级 API，以使用实验管理系统。这些接口被封装在 Qlib 中的变量 R 中，用户可以直接使用 R 与系统进行交互。以下命令展示了如何在 Python 中导入 R：

from qlib.workflow import R

QlibRecorder 包含几个用于在工作流中管理 experiments 和 recorders 的常用 API。有关更多可用 API，请参阅以下关于 Experiment Manager、Experiment 和 Recorder 的部分。

以下是 QlibRecorder 的可用接口：

class qlib.workflow.__init__.QlibRecorder(exp_manager: ExpManager)

一个全球系统，帮助管理实验。

__init__(exp_manager: ExpManager)

启动实验的方法。此方法只能在 Python 的 with 语句中调用。以下是示例代码：

# start new experiment and recorder
with R.start(experiment_name='test', recorder_name='recorder_1'):
    model.fit(dataset)
    R.log...
    ... # further operations

# resume previous experiment and recorder
with R.start(experiment_name='test', recorder_name='recorder_1', resume=True): # if users want to resume recorder, they have to specify the exact same name for experiment and recorder.
    ... # further operations

参数:

experiment_id (str) -- 要启动的实验的 ID。
experiment_name (str) -- 要启动的实验的名称。
recorder_id (str) -- 要启动的实验下的记录器的 ID。
recorder_name (str) -- 要启动的实验下的记录器的名称。
uri (str) -- 实验的跟踪 URI，所有的工件/指标等将存储在此处。默认 URI 在 qlib.config 中设置。请注意，此 URI 参数不会更改配置文件中定义的 URI。因此，下次用户在同一实验中调用此函数时，也必须指定此参数，并保持相同的值。否则，可能会出现不一致的 URI。
resume (bool) -- 是否在给定实验下恢复具有给定名称的特定记录器。

start_exp(*, experiment_id=None, experiment_name=None, recorder_id=None, recorder_name=None, uri=None, resume=False)

启动实验的低级方法。当使用此方法时，应该手动结束实验，并且记录器的状态可能不会被正确处理。以下是示例代码：

R.start_exp(experiment_name='test', recorder_name='recorder_1')
... # further operations
R.end_exp('FINISHED') or R.end_exp(Recorder.STATUS_S)

参数:

experiment_id (str) -- 要启动的实验的 ID。
experiment_name (str) -- 要启动的实验的名称
recorder_id (str) -- 要启动的实验下的记录器的 ID。
recorder_name (str) -- 要启动的实验下的记录器的名称。
uri (str) -- 实验的跟踪 URI，所有的工件/指标等将存储在此处。默认 URI 在 qlib.config 中设置。
resume (bool) -- 是否在给定实验下恢复具有给定名称的特定记录器。

返回类型:

An experiment instance being started.

end_exp(recorder_status='FINISHED')

手动结束实验的方法。它将结束当前活动的实验，以及其活动记录器，并指定 status 类型。以下是该方法的示例代码：

R.start_exp(experiment_name='test')
... # further operations
R.end_exp('FINISHED') or R.end_exp(Recorder.STATUS_S)

参数:: status (str) -- 记录器的状态，可以是 SCHEDULED、RUNNING、FINISHED 或 FAILED。

search_records(experiment_ids, **kwargs)

获取符合搜索条件的记录的 pandas DataFrame。

此函数的参数并不是固定的，它们会因 Qlib 中 ExpManager 的不同实现而有所不同。Qlib 现在提供了一个带有 mlflow 的 ExpManager 实现，以下是使用 MLflowExpManager 的方法示例代码：

R.log_metrics(m=2.50, step=0)
records = R.search_records([experiment_id], order_by=["metrics.m DESC"])

参数:

experiment_ids (list) -- 实验 ID 列表。
filter_string (str) -- 过滤查询字符串，默认为搜索所有运行。
run_view_type (int) -- 枚举值之一 ACTIVE_ONLY、DELETED_ONLY 或 ALL（例如，在 mlflow.entities.ViewType 中）。
max_results (int) -- 放入数据框的最大运行次数。
order_by (list) -- 按列排序的列表（例如，"metrics.rmse"）。

返回:

一个 pandas.DataFrame 的记录，其中每个指标、参数和标签
扩展到各自命名为 metrics.、params.* 和 tags.* 的列。**
分别。对于没有特定指标、参数或标签的记录，它们的
值将分别为 (NumPy) Nan、None 或 None.

list_experiments()

列出所有现有实验的方法（不包括正在删除的实验）。

exps = R.list_experiments()

返回类型:: A dictionary (name -> experiment) of experiments information that being stored.

list_recorders(experiment_id=None, experiment_name=None)

列出具有给定 ID 或名称的实验的所有记录器的方法。

如果用户没有提供实验的 ID 或名称，此方法将尝试检索默认实验并列出默认实验的所有记录器。如果默认实验不存在，该方法将首先创建默认实验，然后在其下创建一个新的记录器。（有关默认实验的更多信息，请参见这里）。

以下是示例代码：

recorders = R.list_recorders(experiment_name='test')

参数:

experiment_id (str) -- 实验的 ID。
experiment_name (str) -- 实验的名称。

返回类型:

A dictionary (id -> recorder) of recorder information that being stored.

get_exp(*, experiment_id=None, experiment_name=None, create: bool = True, start: bool = False) → Experiment

根据给定的 ID 或名称检索实验的方法。一旦 create 参数设置为 True，如果没有找到有效的实验，该方法将为您创建一个。否则，它将仅检索特定实验或引发错误。

如果 'create' 为 True：
- 如果 active experiment 存在：
  未指定ID或名称，返回活动实验。
  
  如果指定了 ID 或名称，返回指定的实验。如果未找到此实验，则使用给定的 ID 或名称创建一个新实验。
- 如果`活动实验`不存在：
  未指定 ID 或名称，创建一个默认实验，并将实验设置为活动状态。
  
  如果指定了 ID 或名称，返回指定的实验。如果未找到此实验，则使用给定名称或默认实验创建一个新实验。
否则如果 'create' 为 False：
- 如果 active experiment 存在：
  未指定ID或名称，返回活动实验。
  
  如果指定了ID或名称，返回指定的实验。如果未找到该实验，则引发错误。
- 如果`活动实验`不存在：
  未指定ID或名称。如果默认实验存在，则返回它，否则引发错误。
  
  如果指定了ID或名称，返回指定的实验。如果未找到该实验，则引发错误。

以下是一些用例：

# Case 1
with R.start('test'):
    exp = R.get_exp()
    recorders = exp.list_recorders()

# Case 2
with R.start('test'):
    exp = R.get_exp(experiment_name='test1')

# Case 3
exp = R.get_exp() -> a default experiment.

# Case 4
exp = R.get_exp(experiment_name='test')

# Case 5
exp = R.get_exp(create=False) -> the default experiment if exists.

参数:

experiment_id (str) -- 实验的 ID。
experiment_name (str) -- 实验的名称。
create (boolean) -- 一个参数决定了如果实验尚未创建，方法是否会根据用户的规范自动创建一个新实验。
start (bool) -- 当start为True时，如果实验尚未开始（未激活），它将启动。该设计用于R.log_params以自动启动实验。

返回类型:

An experiment instance with given id or name.

delete_exp(experiment_id=None, experiment_name=None)

用于删除具有给定id或名称的实验的方法。必须提供id或名称中的至少一个，否则将发生错误。

以下是示例代码：

R.delete_exp(experiment_name='test')

参数:

experiment_id (str) -- 实验的 ID。
experiment_name (str) -- 实验的名称。

get_uri()

用于检索当前实验管理器的uri的方法。

以下是示例代码：

uri = R.get_uri()

返回类型:: The uri of current experiment manager.

set_uri(uri: str | None)

用于重置当前实验管理器的**默认**uri的方法。

注意：

当uri引用文件路径时，请使用绝对路径，而不是像"~/mlruns/"这样的字符串。后端不支持这种字符串。

uri_context(uri: str)

临时将exp_manager的**default_uri**设置为uri

注意：- 请参阅`set_uri`中的注意事项

参数:: uri (Text) -- 临时uri

get_recorder(*, recorder_id=None, recorder_name=None, experiment_id=None, experiment_name=None) → Recorder

用于检索记录器的方法。

如果存在`活动记录器`：
- 未指定ID或名称，返回活动记录器。
- 如果指定了id或名称，则返回指定的记录器。
如果不存在`活动记录器`：
- 未指定ID或名称，引发错误。
- 如果指定了id或名称，并且必须提供相应的experiment_name，则返回指定的记录器。否则，抛出错误。

记录器可用于进一步处理，例如`save_object`、load_object、log_params、`log_metrics`等。

以下是一些用例：

# Case 1
with R.start(experiment_name='test'):
    recorder = R.get_recorder()

# Case 2
with R.start(experiment_name='test'):
    recorder = R.get_recorder(recorder_id='2e7a4efd66574fa49039e00ffaefa99d')

# Case 3
recorder = R.get_recorder() -> Error

# Case 4
recorder = R.get_recorder(recorder_id='2e7a4efd66574fa49039e00ffaefa99d') -> Error

# Case 5
recorder = R.get_recorder(recorder_id='2e7a4efd66574fa49039e00ffaefa99d', experiment_name='test')

以下是用户可能关心的一些问题 - 问：如果多个记录器满足查询（例如，按experiment_name查询），它将返回哪个记录器？ - 答：如果使用mlflow后端，则返回具有最新`start_time`的记录器。因为MLflow的`search_runs`函数保证了这一点。

参数:

recorder_id (str) -- 记录器的id。
recorder_name (str) -- 记录器的名称。
experiment_name (str) -- 实验的名称。

返回类型:

A recorder instance.

delete_recorder(recorder_id=None, recorder_name=None)

用于删除具有给定id或名称的记录器的方法。必须提供id或名称中的至少一个，否则将发生错误。

以下是示例代码：

R.delete_recorder(recorder_id='2e7a4efd66574fa49039e00ffaefa99d')

参数:

recorder_id (str) -- 实验的 ID。
recorder_name (str) -- 实验的名称。

save_objects(local_path=None, artifact_path=None, **kwargs: Dict[str, Any])

用于将对象作为工件保存到uri的实验中的方法。它支持从本地文件/目录保存或直接保存对象。用户可以使用有效的Python关键字参数来指定要保存的对象及其名称（名称：值）。

总之，API设计用于将**对象**保存到**实验管理后端路径**，1. Qlib提供两种方法来指定**对象** - 通过`**kwargs`直接传递对象（例如，R.save_objects(trained_model=model)） - 传递对象的本地路径，即`local_path`参数。2. `artifact_path`表示**实验管理后端路径**

如果存在`active recorder`：它将通过活动记录器保存对象。
如果不存在`active recorder`：系统将创建一个默认实验，并创建一个新的记录器，并在其下保存对象。

备注

如果想要使用特定的记录器保存对象，建议首先通过`get_recorder` API获取特定记录器，并使用该记录器保存对象。支持的参数与此方法相同。

以下是一些用例：

# Case 1
with R.start(experiment_name='test'):
    pred = model.predict(dataset)
    R.save_objects(**{"pred.pkl": pred}, artifact_path='prediction')
    rid = R.get_recorder().id
...
R.get_recorder(recorder_id=rid).load_object("prediction/pred.pkl")  #  after saving objects, you can load the previous object with this api

# Case 2
with R.start(experiment_name='test'):
    R.save_objects(local_path='results/pred.pkl', artifact_path="prediction")
    rid = R.get_recorder().id
...
R.get_recorder(recorder_id=rid).load_object("prediction/pred.pkl")  #  after saving objects, you can load the previous object with this api

参数:

local_path (str) -- 如果提供，则将文件或目录保存到工件 URI。
artifact_path (str) -- 要存储在 URI 中的工件的相对路径。
**kwargs (Dict[Text, Any]) -- 要保存的对象。例如，{"pred.pkl": pred}

load_object(name: str): 从URI中的实验工件加载对象的方法。

log_params(**kwargs)

在实验期间记录参数的方法。除了使用``R``，还可以在通过`get_recorder` API获取特定记录器后，记录到该记录器。

如果存在`active recorder`：它将通过活动记录器记录参数。
如果不存在`active recorder`：系统将创建一个默认实验以及一个新的记录器，并在其下记录参数。

以下是一些用例：

# Case 1
with R.start('test'):
    R.log_params(learning_rate=0.01)

# Case 2
R.log_params(learning_rate=0.01)

参数:: argument (keyword) -- name1=value1, name2=value2, ...

log_metrics(step=None, **kwargs)

在实验期间记录指标的方法。除了使用``R``，还可以在通过`get_recorder` API获取特定记录器后，记录到该记录器。

如果存在`active recorder`：它将通过活动记录器记录指标。
如果不存在`active recorder`：系统将创建一个默认实验以及一个新的记录器，并在其下记录指标。

以下是一些用例：

# Case 1
with R.start('test'):
    R.log_metrics(train_loss=0.33, step=1)

# Case 2
R.log_metrics(train_loss=0.33, step=1)

参数:: argument (keyword) -- name1=value1, name2=value2, ...

log_artifact(local_path: str, artifact_path: str | None = None)

将本地文件或目录作为当前活动运行的工件记录。

如果存在`active recorder`：它将通过活动记录器设置标签。
如果不存在`active recorder`：系统将创建一个默认实验以及一个新的记录器，并在其下设置标签。

参数:

local_path (str) -- 要写入的文件路径。
artifact_path (Optional[str]) -- 如果提供，写入``artifact_uri``中的目录。

download_artifact(path: str, dst_path: str | None = None) → str

如果适用，从运行中下载工件文件或目录到本地目录，并返回其本地路径。

参数:

path (str) -- 所需工件的相对源路径。
dst_path (Optional[str]) -- 要下载指定工件的本地文件系统目标目录的绝对路径。此目录必须已经存在。如果未指定，工件将下载到本地文件系统上的新唯一命名目录。

返回:

所需工件的本地路径。

返回类型:

str

set_tags(**kwargs)

设置记录器标签的方法。除了使用``R``，还可以在通过`get_recorder` API获取特定记录器后，将标签设置到该记录器。

如果存在`active recorder`：它将通过活动记录器设置标签。
如果不存在`active recorder`：系统将创建一个默认实验以及一个新的记录器，并在其下设置标签。

以下是一些用例：

# Case 1
with R.start('test'):
    R.set_tags(release_version="2.2.0")

# Case 2
R.set_tags(release_version="2.2.0")

参数:: argument (keyword) -- name1=value1, name2=value2, ...

实验管理器

``Qlib``中的``ExpManager``模块负责管理不同的实验。``ExpManager``的大多数API与``QlibRecorder``类似，最重要的API将是``get_exp``方法。用户可以直接参考上述文档以获取有关如何使用``get_exp``方法的详细信息。

class qlib.workflow.expm.ExpManager(uri: str, default_exp_name: str | None)

这是用于管理实验的 ExpManager 类。API 的设计类似于 mlflow。（链接：https://mlflow.org/docs/latest/python_api/mlflow.html）

预计 ExpManager 是一个单例（顺便说一下，我们可以有多个具有不同 uri 的 Experiment。用户可以从不同的 uri 获取不同的实验，然后比较它们的记录）。全局配置（即 C）也是一个单例。

因此我们尝试将它们对齐。它们共享同一个变量，称为 default uri。有关变量共享的详细信息，请参阅 ExpManager.default_uri。

当用户开始实验时，用户可能希望将 uri 设置为特定的 uri（在此期间将覆盖 default uri），然后取消设置 specific uri 并回退到 default uri。ExpManager._active_exp_uri 是该 specific uri。

__init__(uri: str, default_exp_name: str | None)

开始一个实验。此方法包括首先获取或创建一个实验，然后将其设置为活动状态。

维护 _active_exp_uri 包含在 start_exp 中，剩余实现应包含在子类的 _end_exp 中。

参数:

experiment_id (str) -- 活动实验的 id。
experiment_name (str) -- 活动实验的名称。
recorder_id (str) -- 要启动的记录器的ID。
recorder_name (str) -- 要启动的记录器的名称。
uri (str) -- 当前的跟踪URI。
resume (boolean) -- 是否恢复实验和记录器。

返回类型:

An active experiment.

end_exp(recorder_status: str = 'SCHEDULED', **kwargs)

结束一个活动实验。

维护 _active_exp_uri 包含在 end_exp 中，剩余实现应包含在子类的 _end_exp 中。

参数:

experiment_name (str) -- 活动实验的名称。
recorder_status (str) -- 实验的活动记录器的状态。

create_exp(experiment_name: str | None = None)

创建一个实验。

参数:: experiment_name (str) -- 实验名称，必须是唯一的。
返回类型:: An experiment object.
抛出:: ExpAlreadyExistError --

search_records(experiment_ids=None, **kwargs)

获取符合实验搜索条件的记录的 pandas DataFrame。输入是用户想要应用的搜索条件。

返回:

一个 pandas.DataFrame 的记录，其中每个指标、参数和标签
扩展到各自命名为 metrics.、params.* 和 tags.* 的列。**
分别。对于没有特定指标、参数或标签的记录，它们的
值将分别为 (NumPy) Nan、None 或 None.

get_exp(*, experiment_id=None, experiment_name=None, create: bool = True, start: bool = False)

检索一个实验。此方法包括获取一个活动实验，以及获取或创建一个特定实验。

当用户指定实验ID和名称时，该方法将尝试返回特定实验。当用户未提供记录器ID或名称时，该方法将尝试返回当前活动实验。create 参数决定该方法是否会根据用户的规范自动创建一个新实验，如果该实验之前尚未创建。

如果 create 为 True：
- 如果 active experiment 存在：
  未指定ID或名称，返回活动实验。
  
  如果指定了ID或名称，返回指定的实验。如果未找到该实验，则使用给定的ID或名称创建一个新实验。如果`start`设置为True，则该实验将被设置为活动状态。
- 如果`活动实验`不存在：
  未指定ID或名称，创建一个默认实验。
  
  如果指定了ID或名称，返回指定的实验。如果未找到该实验，则使用给定的ID或名称创建一个新实验。如果`start`设置为True，则该实验将被设置为活动状态。
否则如果`create`为False：
- 如果 active experiment 存在：
  未指定ID或名称，返回活动实验。
  
  如果指定了ID或名称，返回指定的实验。如果未找到该实验，则引发错误。
- 如果`活动实验`不存在：
  未指定ID或名称。如果默认实验存在，则返回它，否则引发错误。
  
  如果指定了ID或名称，返回指定的实验。如果未找到该实验，则引发错误。

参数:

experiment_id (str) -- 要返回的实验ID。
experiment_name (str) -- 要返回的实验名称。
create (boolean) -- 如果实验尚未创建，则创建该实验。
start (boolean) -- 如果创建了一个新实验，则启动该实验。

返回类型:

An experiment object.

delete_exp(experiment_id=None, experiment_name=None)

删除一个实验。

参数:

experiment_id (str) -- 实验ID。
experiment_name (str) -- 实验名称。

property default_uri: 从qlib.config.C获取默认跟踪URI。

property uri

获取默认跟踪URI或当前URI。

返回类型:: The tracking URI string.

list_experiments()

列出所有现有实验。

返回类型:: A dictionary (name -> experiment) of experiments information that being stored.

有关其他接口，如`create_exp`、delete_exp，请参阅`实验管理器API <../reference/api.html#experiment-manager>`_。

实验

``Experiment``类专门负责单个实验，它将处理与实验相关的任何操作。包括`start`、end`实验等基本方法。此外，还提供与`recorders`相关的方法：这些方法包括`get_recorder`和`list_recorders。

class qlib.workflow.exp.Experiment(id, name)

这是每个正在运行的实验的`Experiment`类。该API的设计类似于mlflow。（链接：https://mlflow.org/docs/latest/python_api/mlflow.html）

__init__(id, name)

start(*, recorder_id=None, recorder_name=None, resume=False)

启动实验并将其设置为活动状态。此方法还将启动一个新的记录器。

参数:

recorder_id (str) -- 要创建的记录器的ID。
recorder_name (str) -- 要创建的记录器的名称。
resume (bool) -- 是否恢复第一个记录器。

返回类型:

An active recorder.

end(recorder_status='SCHEDULED')

结束实验。

参数:: recorder_status (str) -- 结束时要设置的记录器状态（SCHEDULED, RUNNING, FINISHED, FAILED）。

create_recorder(recorder_name=None)

为每个实验创建一个记录器。

参数:: recorder_name (str) -- 要创建的记录器的名称。
返回类型:: A recorder object.

search_records(**kwargs)

获取符合实验搜索条件的记录的 pandas DataFrame。输入是用户想要应用的搜索条件。

返回:

一个 pandas.DataFrame 的记录，其中每个指标、参数和标签
扩展到各自命名为 metrics.、params.* 和 tags.* 的列。**
分别。对于没有特定指标、参数或标签的记录，它们的
值将分别为 (NumPy) Nan、None 或 None.

delete_recorder(recorder_id)

为每个实验创建一个记录器。

参数:: recorder_id (str) -- 要删除的记录器的ID。

get_recorder(recorder_id=None, recorder_name=None, create: bool = True, start: bool = False) → Recorder

为用户检索记录器。当用户指定记录器ID和名称时，该方法将尝试返回特定的记录器。当用户未提供记录器ID或名称时，该方法将尝试返回当前活动的记录器。`create`参数决定如果记录器之前未创建，该方法是否会根据用户的规范自动创建一个新的记录器。

如果 create 为 True：
- 如果存在`活动记录器`：
  未指定ID或名称，返回活动记录器。
  
  如果指定了ID或名称，返回指定的记录器。如果未找到这样的实验，则使用给定的ID或名称创建一个新的记录器。如果`start`设置为True，则记录器被设置为活动状态。
- 如果不存在`活动记录器`：
  未指定ID或名称，创建一个新的记录器。
  
  如果指定了ID或名称，返回指定的实验。如果未找到这样的实验，则使用给定的ID或名称创建一个新的记录器。如果`start`设置为True，则记录器被设置为活动状态。
否则如果`create`为False：
- 如果存在`活动记录器`：
  未指定ID或名称，返回活动记录器。
  
  如果指定了ID或名称，返回指定的记录器。如果未找到这样的实验，则引发错误。
- 如果不存在`活动记录器`：
  未指定ID或名称，引发错误。
  
  如果指定了ID或名称，返回指定的记录器。如果未找到这样的实验，则引发错误。

参数:

recorder_id (str) -- 要删除的记录器的ID。
recorder_name (str) -- 要删除的记录器的名称。
create (boolean) -- 如果记录器之前未创建，则创建记录器。
start (boolean) -- 如果创建了新的记录器，则启动该记录器。

返回类型:

A recorder object.

list_recorders(rtype: Literal['dict', 'list'] = 'dict', **flt_kwargs) → List[Recorder] | Dict[str, Recorder]

列出该实验的所有现有记录器。请在调用此方法之前先获取实验实例。如果用户想使用方法`R.list_recorders()`，请参考`QlibRecorder`中的相关API文档。

flt_kwargs字典: 通过条件过滤记录器，例如：list_recorders(status=Recorder.STATUS_FI)

返回:: 如果 rtype == "dict": 一个存储记录器信息的字典（id -> recorder）。否则如果 rtype == "list": 一个记录器的列表。
返回类型:: 返回类型取决于 rtype

对于其他接口，例如 search_records、delete_recorder，请参阅 Experiment API。

Qlib 还提供了一个默认的 Experiment，在用户使用 log_metrics 或 get_exp 等 API 时，会在某些情况下创建并使用该实验。如果使用默认的 Experiment，在运行 Qlib 时将会有相关的日志信息。用户可以在 Qlib 的配置文件中或在 Qlib 的初始化过程中更改默认 Experiment 的名称，默认名称为 'Experiment'。

Recorder

Recorder 类负责单个记录器。它将处理一些详细操作，例如单次运行的 log_metrics、log_params。它旨在帮助用户轻松跟踪运行期间生成的结果和事物。

以下是一些未包含在 QlibRecorder 中的重要 API：

class qlib.workflow.recorder.Recorder(experiment_id, name)

这是用于记录实验的 Recorder 类。API 的设计类似于 mlflow。（链接：https://mlflow.org/docs/latest/python_api/mlflow.html）

记录器的状态可以是 SCHEDULED、RUNNING、FINISHED、FAILED。

__init__(experiment_id, name)

save_objects(local_path=None, artifact_path=None, **kwargs)

将对象（如预测文件或模型检查点）保存到工件 URI。用户可以通过关键字参数（name:value）保存对象。

请参考 qlib.workflow:R.save_objects 的文档

参数:

local_path (str) -- 如果提供，则将文件或目录保存到工件 URI。
artifact_path=None (str) -- 要存储在 URI 中的工件的相对路径。

load_object(name)

加载对象，例如预测文件或模型检查点。

参数:: name (str) -- 要加载的文件名。
返回类型:: The saved object.

start_run()

开始运行或恢复记录器。返回值可以在 with 块内用作上下文管理器；否则，您必须调用 end_run() 来终止当前运行。（请参见 mlflow 中的 ActiveRun 类）

返回类型:: An active running object (e.g. mlflow.ActiveRun object).

end_run(): 结束一个活动的记录器。

log_params(**kwargs)

记录当前运行的一批参数。

参数:: arguments (keyword) -- 要记录为参数的键值对。

log_metrics(step=None, **kwargs)

记录当前运行的多个指标。

参数:: arguments (keyword) -- 要记录为指标的键值对。

log_artifact(local_path: str, artifact_path: str | None = None)

将本地文件或目录记录为当前活动运行的工件。

参数:

local_path (str) -- 要写入的文件路径。
artifact_path (Optional[str]) -- 如果提供，写入``artifact_uri``中的目录。

set_tags(**kwargs)

为当前运行记录一批标签。

参数:: arguments (keyword) -- 要记录为标签的键值对。

delete_tags(*keys)

从运行中删除一些标签。

参数:: keys (series of strs of the keys) -- 要删除的标签的所有名称。

list_artifacts(artifact_path: str | None = None)

列出记录器的所有工件。

参数:: artifact_path (str) -- 要存储在 URI 中的工件的相对路径。
返回类型:: A list of artifacts information (name, path, etc.) that being stored.

download_artifact(path: str, dst_path: str | None = None) → str

如果适用，从运行中下载工件文件或目录到本地目录，并返回其本地路径。

参数:

path (str) -- 所需工件的相对源路径。
dst_path (Optional[str]) -- 要下载指定工件的本地文件系统目标目录的绝对路径。此目录必须已经存在。如果未指定，工件将下载到本地文件系统上的新唯一命名目录。

返回:

所需工件的本地路径。

返回类型:

str

list_metrics()

列出记录器的所有指标。

返回类型:: A dictionary of metrics that being stored.

list_params()

列出记录器的所有参数。

返回类型:: A dictionary of params that being stored.

list_tags()

列出记录器的所有标签。

返回类型:: A dictionary of tags that being stored.

对于其他接口，例如 save_objects、load_object，请参阅 Recorder API。

记录模板

RecordTemp 类是一个能够以特定格式生成实验结果（如 IC 和回测）的类。我们提供了三种不同的记录模板类：

SignalRecord：该类生成模型的预测结果。
SigAnaRecord：该类生成模型的 IC、ICIR、Rank IC 和 Rank ICIR。

以下是 SigAnaRecord 中所做的简单示例，用户可以参考该示例以计算 IC、Rank IC、基于自身预测和标签的多空收益。

from qlib.contrib.eva.alpha import calc_ic, calc_long_short_return

ic, ric = calc_ic(pred.iloc[:, 0], label.iloc[:, 0])
long_short_r, long_avg_r = calc_long_short_return(pred.iloc[:, 0], label.iloc[:, 0])

PortAnaRecord：该类生成回测的结果。有关回测的详细信息以及可用的策略，用户可以参考 Strategy 和 Backtest。

以下是 PortAnaRecord 中所做的简单示例，用户可以参考该示例以基于自身预测和标签进行回测。

from qlib.contrib.strategy.strategy import TopkDropoutStrategy
from qlib.contrib.evaluate import (
    backtest as normal_backtest,
    risk_analysis,
)

# backtest
STRATEGY_CONFIG = {
    "topk": 50,
    "n_drop": 5,
}
BACKTEST_CONFIG = {
    "limit_threshold": 0.095,
    "account": 100000000,
    "benchmark": BENCHMARK,
    "deal_price": "close",
    "open_cost": 0.0005,
    "close_cost": 0.0015,
    "min_cost": 5,
}

strategy = TopkDropoutStrategy(**STRATEGY_CONFIG)
report_normal, positions_normal = normal_backtest(pred_score, strategy=strategy, **BACKTEST_CONFIG)

# analysis
analysis = dict()
analysis["excess_return_without_cost"] = risk_analysis(report_normal["return"] - report_normal["bench"])
analysis["excess_return_with_cost"] = risk_analysis(report_normal["return"] - report_normal["bench"] - report_normal["cost"])
analysis_df = pd.concat(analysis)  # type: pd.DataFrame
print(analysis_df)

有关 API 的更多信息，请参阅记录模板 API。

已知限制

Python 对象是基于 pickle 保存的，当环境转储对象和加载对象不同时，可能会导致问题。