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来可视化和检查实验结果。更多信息,请参考相关文档这里

Qlib 记录器

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

from qlib.workflow import R

QlibRecorder 包含几个常见的API,用于管理工作流中的实验记录器。有关更多可用的API,请参阅以下关于实验管理器实验记录器的部分。

以下是QlibRecorder的可用接口:

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

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

__init__(exp_manager: ExpManager)
start(*, experiment_id: str | None = None, experiment_name: str | None = None, recorder_id: str | None = None, recorder_name: str | None = None, uri: str | None = None, resume: bool = False)

启动实验的方法。此方法只能在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
Parameters:
  • 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)
Parameters:
  • experiment_id (str) – 想要启动的实验的id。

  • experiment_name (str) – 要启动的实验的名称

  • recorder_id (str) – 想要启动的实验下的记录器ID。

  • recorder_name (str) – 想要启动的实验下的记录器名称。

  • uri (str) – 实验的跟踪URI,所有工件/指标等都将存储在此处。 默认的URI在qlib.config中设置。

  • resume (bool) – 是否在给定实验下恢复具有给定名称的特定记录器。

Return type:

一个实验实例正在启动。

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)
Parameters:

status (str) – 记录器的状态,可以是 SCHEDULED(已计划)、RUNNING(运行中)、FINISHED(已完成)、FAILED(失败)。

search_records(experiment_ids, **kwargs)

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

此函数的参数并未设置为固定不变,它们会随着QlibExpManager的不同实现而有所不同。Qlib目前提供了一个使用mlflow的ExpManager实现,以下是使用MLflowExpManager的方法示例代码:

R.log_metrics(m=2.50, step=0)
records = R.search_records([experiment_id], order_by=["metrics.m DESC"])
Parameters:
  • 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”)。

Returns:

  • 一个pandas.DataFrame的记录,其中每个指标、参数和标签

  • 都被扩展为它们自己的列,分别命名为metrics.*, params.*, 和 tags.*

  • 对于没有特定指标、参数或标签的记录,它们的

  • 值将分别为(NumPy) Nan, None, 或 None。

list_experiments()

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

exps = R.list_experiments()
Return type:

存储的实验信息的字典(名称 -> 实验)。

list_recorders(experiment_id=None, experiment_name=None)

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

如果用户没有提供实验的id或名称,此方法将尝试检索默认实验并列出默认实验的所有记录器。如果默认实验不存在,该方法将首先创建默认实验,然后在其下创建一个新的记录器。(有关默认实验的更多信息可以找到这里)。

这是示例代码:

recorders = R.list_recorders(experiment_name='test')
Parameters:
  • experiment_id (str) – 实验的id。

  • experiment_name (str) – 实验的名称。

Return type:

存储的记录器信息的字典(id -> recorder)。

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

用于通过给定的ID或名称检索实验的方法。一旦create参数设置为True,如果没有找到有效的实验,此方法将为您创建一个。否则,它只会检索特定的实验或引发错误。

  • 如果‘create’为True:

    • 如果存在active experiment

      • 未指定id或name,返回当前活动的实验。

      • 如果指定了id或name,则返回指定的实验。如果没有找到这样的实验,则使用给定的id或name创建一个新实验。

    • 如果active experiment不存在:

      • 未指定ID或名称,创建默认实验,并将实验设置为活动状态。

      • 如果指定了id或name,则返回指定的实验。如果未找到此类实验,则使用给定的名称或默认实验创建一个新实验。

  • 否则如果‘create’为False:

    • 如果存在active experiment

      • 未指定id或name,返回当前活动的实验。

      • 如果指定了id或name,则返回指定的实验。如果未找到此类实验,则引发错误。

    • 如果active experiment不存在:

      • 未指定ID或名称。如果默认实验存在,则返回它,否则引发错误。

      • 如果指定了id或name,则返回指定的实验。如果没有找到这样的实验,则引发错误。

以下是一些使用案例:

# 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.
Parameters:
  • experiment_id (str) – 实验的id。

  • experiment_name (str) – 实验的名称。

  • create (boolean) – 一个参数,用于确定如果实验之前未被创建,该方法是否将根据用户的规格自动创建一个新实验。

  • start (bool) – 当 start 为 True 时, 如果实验尚未开始(未激活),它将启动 它设计用于 R.log_params 自动启动实验

Return type:

具有给定ID或名称的实验实例。

delete_exp(experiment_id=None, experiment_name=None)

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

这是示例代码:

R.delete_exp(experiment_name='test')
Parameters:
  • experiment_id (str) – 实验的id。

  • experiment_name (str) – 实验的名称。

get_uri()

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

这是示例代码:

uri = R.get_uri()
Return type:

当前实验管理器的URI。

set_uri(uri: str | None)

重置当前实验管理器的默认URI的方法。

注意:

  • 当uri指向文件路径时,请使用绝对路径而不是像“~/mlruns/”这样的字符串。后端不支持这样的字符串。

uri_context(uri: str)

暂时将exp_manager的default_uri设置为uri

注意: - 请参考set_uri中的注意

Parameters:

uri (Text) – 临时uri

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

用于检索记录器的方法。

  • 如果存在active recorder

    • 未指定id或name,返回活动的记录器。

    • 如果指定了id或name,则返回指定的记录器。

  • 如果active recorder不存在:

    • 未指定ID或名称,引发错误。

    • 如果指定了id或name,则必须给出相应的experiment_name,返回指定的记录器。否则,抛出错误。

记录器可以用于进一步的处理,例如save_objectload_objectlog_paramslog_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函数保证了这一点

Parameters:
  • recorder_id (str) – 记录器的ID。

  • recorder_name (str) – 记录器的名称。

  • experiment_name (str) – 实验的名称。

Return type:

一个记录器实例。

delete_recorder(recorder_id=None, recorder_name=None)

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

这是示例代码:

R.delete_recorder(recorder_id='2e7a4efd66574fa49039e00ffaefa99d')
Parameters:
  • 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
Parameters:
  • 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)
Parameters:

参数 (关键字) – 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)
Parameters:

参数 (关键字) – name1=value1, name2=value2, …

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

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

  • 如果存在active recorder:它将通过活动记录器设置标签。

  • 如果active recorder不存在:系统将创建一个默认实验以及一个新的记录器,并在其下设置标签。

Parameters:
  • local_path (str) – 要写入文件的路径。

  • artifact_path (可选[str]) – 如果提供,则为artifact_uri中要写入的目录。

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

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

Parameters:
  • path (str) – 所需工件的相对源路径。

  • dst_path (可选[str]) – 本地文件系统目标目录的绝对路径,用于下载指定的工件。此目录必须已经存在。如果未指定,工件将被下载到本地文件系统上一个新的唯一命名的目录中。

Returns:

所需工件的本地路径。

Return type:

字符串

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")
Parameters:

参数 (关键字) – 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(在此期间它将覆盖默认uri),然后取消设置特定uri并回退到默认uriExpManager._active_exp_uri就是那个特定uri

__init__(uri: str, default_exp_name: str | None)
start_exp(*, experiment_id: str | None = None, experiment_name: str | None = None, recorder_id: str | None = None, recorder_name: str | None = None, uri: str | None = None, resume: bool = False, **kwargs) Experiment

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

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

Parameters:
  • experiment_id (str) – 当前实验的ID。

  • experiment_name (str) – 活动实验的名称。

  • recorder_id (str) – 要启动的记录器的ID。

  • recorder_name (str) – 要启动的记录器的名称。

  • uri (str) – 当前的跟踪URI。

  • resume (boolean) – 是否恢复实验和记录器。

Return type:

一个活跃的实验。

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

结束一个活跃的实验。

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

Parameters:
  • experiment_name (str) – 活动实验的名称。

  • recorder_status (str) – 实验活动记录器的状态。

create_exp(experiment_name: str | None = None)

创建一个实验。

Parameters:

experiment_name (str) – 实验名称,必须是唯一的。

Return type:

一个实验对象。

Raises:

ExpAlreadyExistError

search_records(experiment_ids=None, **kwargs)

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

Returns:

  • 一个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或name,返回当前活动的实验。

      • 如果指定了id或name,则返回指定的实验。如果未找到此类实验,则使用给定的id或name创建一个新实验。如果start设置为True,则实验设置为活动状态。

    • 如果active experiment不存在:

      • 未指定ID或名称,创建默认实验。

      • 如果指定了id或name,则返回指定的实验。如果没有找到这样的实验,则使用给定的id或name创建一个新实验。如果start设置为True,则实验设置为活动状态。

  • 否则如果 create 为 False:

    • 如果存在active experiment

      • 未指定id或name,返回当前活动的实验。

      • 如果指定了id或name,则返回指定的实验。如果没有找到这样的实验,则引发错误。

    • 如果active experiment不存在:

      • 未指定ID或名称。如果默认实验存在,则返回它,否则引发错误。

      • 如果指定了id或name,则返回指定的实验。如果没有找到这样的实验,则引发错误。

Parameters:
  • experiment_id (str) – 要返回的实验的id。

  • experiment_name (str) – 要返回的实验名称。

  • create (boolean) – 如果之前没有创建过实验,则创建它。

  • 开始 (布尔值) – 如果创建了新实验,则启动它。

Return type:

一个实验对象。

delete_exp(experiment_id=None, experiment_name=None)

删除一个实验。

Parameters:
  • experiment_id (str) – 实验ID。

  • experiment_name (str) – 实验名称。

property default_uri

从qlib.config.C获取默认的跟踪URI

property uri

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

Return type:

跟踪URI字符串。

list_experiments()

列出所有现有的实验。

Return type:

存储的实验信息的字典(名称 -> 实验)。

对于其他接口,如create_expdelete_exp,请参考Experiment Manager API

实验

Experiment 类仅负责单个实验,并将处理与实验相关的任何操作。包括startend等基本方法。此外,还提供了与recorders相关的方法:例如get_recorderlist_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)

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

Parameters:
  • recorder_id (str) – 要创建的记录器的ID。

  • recorder_name (str) – 要创建的记录器的名称。

  • resume (bool) – 是否恢复第一个记录器

Return type:

一个活跃的记录器。

end(recorder_status='SCHEDULED')

结束实验。

Parameters:

recorder_status (str) – 结束时要设置的记录器状态(SCHEDULED, RUNNING, FINISHED, FAILED)。

create_recorder(recorder_name=None)

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

Parameters:

recorder_name (str) – 要创建的记录器的名称。

Return type:

一个记录器对象。

search_records(**kwargs)

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

Returns:

  • 一个pandas.DataFrame的记录,其中每个指标、参数和标签

  • 都被扩展为它们自己的列,分别命名为metrics.*, params.*, 和 tags.*

  • 对于没有特定指标、参数或标签的记录,它们的

  • 值将分别为(NumPy) Nan, None, 或 None。

delete_recorder(recorder_id)

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

Parameters:

recorder_id (str) – 要删除的记录器的ID。

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

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

  • 如果 create 为 True:

    • 如果存在active recorder

      • 未指定id或name,返回活动的记录器。

      • 如果指定了id或name,则返回指定的记录器。如果未找到此类实验,则使用给定的id或name创建一个新的记录器。如果start设置为True,则记录器设置为活动状态。

    • 如果active recorder不存在:

      • 未指定ID或名称,创建一个新的记录器。

      • 如果指定了id或name,则返回指定的实验。如果未找到此类实验,则使用给定的id或name创建一个新的记录器。如果start设置为True,则记录器设置为活动状态。

  • 否则如果 create 为 False:

    • 如果存在active recorder

      • 未指定id或name,返回活动的记录器。

      • 如果指定了id或name,则返回指定的记录器。如果未找到此类exp,则引发错误。

    • 如果active recorder不存在:

      • 未指定ID或名称,引发错误。

      • 如果指定了id或name,则返回指定的记录器。如果未找到此类exp,则引发错误。

Parameters:
  • recorder_id (str) – 要删除的记录器的ID。

  • recorder_name (str) – 要删除的记录器的名称。

  • create (boolean) – 如果之前没有创建过记录器,则创建它。

  • start (boolean) – 如果创建了新的记录器,则启动它。

Return type:

一个记录器对象。

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

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

flt_kwargsdict

根据条件筛选记录器 例如:list_recorders(status=Recorder.STATUS_FI)

Returns:

if rtype == “dict”:

一个存储的记录器信息的字典(id -> recorder)。

elif rtype == “list”:

一个记录器的列表。

Return type:

返回类型取决于 rtype

对于其他接口,如search_recordsdelete_recorder,请参考Experiment API

Qlib 还提供了一个默认的 Experiment,当用户使用诸如 log_metricsget_exp 等 API 时,它将在某些情况下被创建和使用。如果使用了默认的 Experiment,在运行 Qlib 时会有相关的日志信息。用户可以在 Qlib 的配置文件中或 Qlib初始化 过程中更改默认 Experiment 的名称,该名称默认设置为 ‘Experiment’。

记录器

Recorder 类负责单个记录器。它将处理一些详细操作,例如单个运行的 log_metricslog_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。用户可以通过关键字参数(名称:值)保存对象。

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

Parameters:
  • local_path (str) – 如果提供,则将文件或目录保存到工件URI。

  • artifact_path=None (str) – 工件在URI中存储的相对路径。

load_object(name)

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

Parameters:

name (str) – 要加载的文件的名称。

Return type:

保存的对象。

start_run()

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

Return type:

一个活动的运行对象(例如 mlflow.ActiveRun 对象)。

end_run()

结束一个活动的记录器。

log_params(**kwargs)

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

Parameters:

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

log_metrics(step=None, **kwargs)

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

Parameters:

arguments (keyword) – 要记录为指标的键值对。

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

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

Parameters:
  • local_path (str) – 要写入文件的路径。

  • artifact_path (可选[str]) – 如果提供,则为artifact_uri中要写入的目录。

set_tags(**kwargs)

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

Parameters:

arguments (keyword) – 要记录为标签的键值对。

delete_tags(*keys)

从运行中删除一些标签。

Parameters:

keys (series of strs of the keys) – 要删除的标签的所有名称。

list_artifacts(artifact_path: str | None = None)

列出记录器的所有工件。

Parameters:

artifact_path (str) – 工件在URI中存储的相对路径。

Return type:

存储的工件信息(名称、路径等)列表。

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

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

Parameters:
  • path (str) – 所需工件的相对源路径。

  • dst_path (可选[str]) – 本地文件系统目标目录的绝对路径,用于下载指定的工件。此目录必须已经存在。如果未指定,工件将被下载到本地文件系统上一个新的唯一命名的目录中。

Returns:

所需工件的本地路径。

Return type:

字符串

list_metrics()

列出记录器的所有指标。

Return type:

存储的指标字典。

list_params()

列出记录器的所有参数。

Return type:

存储的参数字典。

list_tags()

列出记录器的所有标签。

Return type:

存储的标签字典。

对于其他接口,如save_objectsload_object,请参考Recorder API

记录模板

RecordTemp 类是一个用于生成特定格式的实验结果的类,例如IC和回测。我们提供了三种不同的记录模板类:

  • SignalRecord: 该类生成模型的预测结果。

  • SigAnaRecord: 该类生成模型的ICICIRRank ICRank 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: 该类生成回测的结果。关于回测的详细信息以及可用的策略,用户可以参考策略回测

这里是一个简单的例子,展示了在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的更多信息,请参考Record Template API

已知限制

  • Python对象是基于pickle保存的,这可能导致在转储对象和加载对象的环境不同时出现问题。