Qlib 记录器：实验管理

简介

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

该系统包含三个组件：

  • ExperimentManager

    用于管理实验的类。

  • 实验

    表示实验的类，其每个实例负责单个实验。

  • 记录器

    表示记录器的类，其每个实例负责单次运行。

以下是该系统结构的总体视图：

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

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

如果用户将 ExpManager 的实现设置为 MLflowExpManager，则可以使用命令 mlflow ui 来可视化并查看实验结果。更多详细信息，请参阅相关文档 此处。

Qlib 记录器

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

from qlib.workflow import R

QlibRecorder 提供了多个常用 API，用于在工作流中管理 实验 和 记录器。更多可用 API，请参考下文关于 实验管理器、实验 和 记录器 的部分。

以下是 QlibRecorder 提供的可用接口：

类 qlib.workflow.__init__。QlibRecorder(exp_manager: 实验管理器)

一个用于管理实验的全局系统。

__init__(exp_manager: 实验管理器)
开始(*, 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
参数:

  • experiment_id (str) – 要启动的实验的 ID。

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

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

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

  • 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) – 要启动的实验下的记录器（recorder）的 ID。

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

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

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

返回类型:

正在启动的实验实例。

end_exp(记录器状态='FINISHED')

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

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

状态（str）——记录器的状态，可以是 SCHEDULED（已计划）、RUNNING（运行中）、FINISHED（已完成）或 FAILED（失败）。

search_records(experiment_ids, **kwargs)

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

此函数的参数不固定，会因 ExpManager 在 Qlib 中的不同实现而有所不同。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）——DataFrame 中包含的最大运行记录数量。

  • order_by（list）——用于排序的列名列表（例如，“metrics.rmse”）。

返回:

  • 一个 pandas.DataFrame 格式的记录，其中每个指标（metric）、参数（parameter）和标签（tag）

  • 都被展开为独立的列，列名分别为 metrics.*, params.*, 和 tags.*

  • 对于没有特定指标、参数或标签的记录，其值将分别为 (NumPy) NaN、None 或 None。

  • 值将分别为 (NumPy) NaN、None 或 None。

list_experiments()

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

exps = R.list_experiments()
返回类型:

一个字典（名称 -> 实验），包含存储的所有实验信息。

list_recorders(experiment_id=None, experiment_name=None)

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

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

以下是示例代码：

recorders = R.list_recorders(experiment_name='test')
参数:

  • experiment_id（str）——实验的 ID。

  • experiment_name（str）——实验的名称。

返回类型:

一个字典（id -> 记录器），包含所存储的记录器信息。

get_exp(*, experiment_id=None, experiment_name=None, create: bool = True, start: bool = False) → 实验（Experiment）

用于获取指定 ID 或名称的实验的方法。当 create 参数设为 True 时，如果未找到有效实验，该方法将自动创建一个；否则，仅尝试获取特定实验，若未找到则抛出错误。

  • 如果 'create' 为 True：

    • 如果存在活跃实验：

      • 未指定 ID 或名称，则返回当前活跃实验。

      • 若指定了 ID 或名称，则返回对应的实验；若未找到该实验，则使用给定的 ID 或名称创建一个新实验。

    • 如果不存在活跃实验：

      • 若未指定 ID 或名称，则创建一个默认实验，并将其设置为激活状态。

      • 若指定了 ID 或名称，则返回对应的实验；若未找到该实验，则使用给定的名称或创建默认实验。

  • 否则，如果 'create' 为 False：

    • 如果存在活跃实验：

      • 未指定 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 (布尔值) – 该参数决定当实验尚未创建时，方法是否根据用户设定自动创建一个新实验。

  • start (bool) – 当 start 为 True 时，如果实验尚未启动（未激活），则会自动启动。该功能旨在支持 R.log_params 等操作自动开启实验。

返回类型:

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

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()
返回类型:

当前实验管理器的 URI。

set_uri(uri: str | None)

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

注意：

  • 当 URI 指向文件路径时，请使用绝对路径，而不要使用类似 "~/mlruns/" 的字符串。后端不支持此类字符串。

uri_context(uri: str)

临时将 exp_manager 的 default_uri 设置为 uri

注意：- 请参考 set_uri 中的 NOTE

参数:

uri (文本) – 临时的 uri

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

用于获取 recorder 的方法。

  • 如果存在活跃记录器：

    • 未指定 ID 或名称，返回活跃记录器。

    • 如果指定了 id 或 name，则返回指定的 recorder。

  • 如果不存在活跃记录器：

    • 未指定 ID 或名称，抛出错误。

    • 如果指定了 id 或 name，则必须同时提供对应的 experiment_name，才能返回指定的 recorder；否则将抛出错误。

该 recorder 可用于后续操作，例如 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')

以下是一些用户可能关心的问题：Q: 如果多个 recorder 满足查询条件（例如仅通过 experiment_name 查询），会返回哪一个？A: 若使用 MLflow 后端，则会返回 start_time 最新的那个 recorder，因为 MLflow 的 search_runs 函数保证了这一点。

参数:

  • recorder_id (str) – recorder 的 ID。

  • recorder_name (str) – recorder 的名称。

  • experiment_name（str）——实验的名称。

返回类型:

一个 recorder 实例。

delete_recorder(recorder_id=None, recorder_name=None)

用于删除指定 ID 或名称的 recorder 的方法。必须至少提供 id 或 name 中的一个，否则将报错。

以下是示例代码：

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 关键字参数来指定要保存的对象及其名称（name: value）。

总之，该 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(名称: 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)

在实验过程中记录指标（metrics）的方法。除了使用R外，还可以通过get_recorder API 获取特定记录器后，向该记录器写入指标。

  • 如果存在活动记录器（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)

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

  • 如果活动记录器存在：将通过该活动记录器设置标签。

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

参数:

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

  • artifact_path (Optional[str]) – 如果提供，表示要写入的 artifact_uri 中的目录。

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

从一次运行中下载一个产物文件或目录到本地目录（如适用），并返回其本地路径。

参数:

  • path (str) – 所需产物的相对源路径。

  • dst_path (可选[str]) – 要下载指定产物的本地文件系统目标目录的绝对路径。该目录必须已存在。如果未指定，产物将被下载到本地文件系统上一个新创建的、唯一命名的目录中。

返回:

所需产物的本地路径。

返回类型:

str

set_tags(**kwargs)

用于为记录器设置标签的方法。除了使用R之外，还可以通过get_recorder API 获取特定记录器后，为其设置标签。

  • 如果活动记录器存在：将通过该活动记录器设置标签。

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

以下是一些使用示例：

# 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方法的详细信息。

类 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）也是一个单例。

因此我们尝试将它们保持一致。它们共享同一个变量，称为 默认 uri。有关变量共享的详细信息，请参见 ExpManager.default_uri。

当用户启动一个实验时，可能希望将 uri 设置为特定的 uri（在此期间会覆盖 默认 uri），之后再取消设置该 特定 uri，并恢复使用 默认 uri。ExpManager._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

启动一个实验。该方法首先调用 get_or_create 来获取或创建一个实验，然后将其设置为激活状态。

在 start_exp 中包含了对 _active_exp_uri 的维护，其余实现应在子类的 _end_exp 中完成。

参数:

  • experiment_id (str) – 当前激活实验的 ID。

  • experiment_name (str) – 当前激活实验的名称。

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

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

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

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

返回类型:

一个激活状态的实验。

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

结束一个激活状态的实验。

在 end_exp 中包含了对 _active_exp_uri 的维护，其余实现应在子类的 _end_exp 中完成。

参数:

  • experiment_name (str) – 当前激活实验的名称。

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

create_exp(experiment_name: str | None = None)

创建一个实验。

参数:

experiment_name (str) – 实验名称，必须唯一。

返回类型:

一个实验对象。

Raises:

ExpAlreadyExistError –

search_records(experiment_ids=None, **kwargs)

获取符合实验搜索条件的记录的 pandas DataFrame。输入为用户希望应用的搜索条件。

返回:

  • 一个 pandas.DataFrame 格式的记录，其中每个指标（metric）、参数（parameter）和标签（tag）

  • 都被展开为独立的列，列名分别为 metrics.*, params.*, 和 tags.*

  • 对于没有特定指标、参数或标签的记录，其值将分别为 (NumPy) NaN、None 或 None。

  • 值将分别为 (NumPy) NaN、None 或 None。

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

检索一个实验。该方法包括获取一个活跃的实验，或根据指定条件获取或创建一个特定的实验。

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

  • 如果 create 为 True：

    • 如果存在活跃实验：

      • 未指定 ID 或名称，则返回当前活跃实验。

      • 如果指定了 ID 或名称，则返回指定的实验；若未找到该实验，则创建一个具有给定 ID 或名称的新实验。如果将 start 设置为 True，则该实验会被设为活跃状态。

    • 如果不存在活跃实验：

      • 未指定 ID 或名称，则创建一个默认实验。

      • 如果指定了 ID 或名称，则返回指定的实验；若未找到该实验，则创建一个具有给定 ID 或名称的新实验。如果将 start 设置为 True，则该实验会被设为活跃状态。

  • 否则，如果 create 为 False：

    • 如果存在活跃实验：

      • 未指定 ID 或名称，则返回当前活跃实验。

      • 如果指定了 ID 或名称，则返回指定的实验；若未找到该实验，则抛出错误。

    • 如果不存在活跃实验：

      • 未指定 ID 或名称。如果默认实验存在，则返回它；否则抛出错误。

      • 如果指定了 ID 或名称，则返回指定的实验；若未找到该实验，则抛出错误。

参数:

  • experiment_id (str) – 要返回的实验的 ID。

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

  • create (boolean) – 如果实验尚未创建，则自动创建。

  • start (boolean) – 如果创建了新实验，则启动该实验。

返回类型:

一个实验对象。

delete_exp(experiment_id=None, experiment_name=None)

删除一个实验。

参数:

  • experiment_id (str) – 实验的 ID。

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

属性 default_uri

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

属性 uri

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

返回类型:

跟踪 URI 字符串。

list_experiments()

列出所有现有的实验。

返回类型:

一个字典（名称 -> 实验），包含存储的所有实验信息。

对于其他接口，如 create_exp、delete_exp，请参考 实验管理器 API。

实验

实验 类仅负责单个实验，它将处理与实验相关的所有操作。包含启动、结束实验等基本方法。此外，还提供与 记录器 相关的方法：例如 get_recorder 和 list_recorders。

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

这是每个运行实验所对应的实验类。该 API 的设计参考了 mlflow。（链接：https://mlflow.org/docs/latest/python_api/mlflow.html）

__init__(id, name)
start(*, recorder_id=None, recorder_name=None, resume=False)

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

参数:

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

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

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

返回类型:

一个活跃的记录器。

结束(记录器状态='SCHEDULED')

结束实验。

参数:

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

create_recorder(recorder_name=None)

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

参数:

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

返回类型:

一个记录器对象。

search_records(**kwargs)

获取符合实验搜索条件的记录的 pandas DataFrame。输入为用户希望应用的搜索条件。

返回:

  • 一个 pandas.DataFrame 格式的记录，其中每个指标（metric）、参数（parameter）和标签（tag）

  • 都被展开为独立的列，列名分别为 metrics.*, params.*, 和 tags.*

  • 对于没有特定指标、参数或标签的记录，其值将分别为 (NumPy) NaN、None 或 None。

  • 值将分别为 (NumPy) NaN、None 或 None。

delete_recorder(recorder_id)

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

参数:

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

get_recorder(recorder_id=无, recorder_name=无, create: 布尔值 = 真, start: 布尔值 = 假) → 记录器

获取用户的记录器。当用户提供 recorder_id 或 recorder_name 时，该方法会尝试返回指定的记录器；当用户未提供 recorder_id 或 recorder_name 时，该方法会尝试返回当前活跃的记录器。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) – 如果创建了新的记录器，则启动它。

返回类型:

一个记录器对象。

list_recorders(rtype: 字面量['字典', '列表'] = '字典', **flt_kwargs) → 列表[记录器] | 字典[字符串, 记录器]

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

flt_kwargsdict

根据条件过滤记录器，例如 list_recorders(status=Recorder.STATUS_FI)

返回:

如果 rtype == “dict”：

一个字典（id -> 记录器），包含所存储的记录器信息。

elif rtype == “list”：

一个 Recorder 列表。

返回类型:

返回类型取决于 rtype。

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

Qlib 还提供了一个默认的 Experiment，当用户使用诸如 log_metrics 或 get_exp 等 API 时，在特定情况下会自动创建并使用该默认 Experiment。若使用默认的 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）

记录器（recorder）的状态可以是 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 (str) – 要加载的文件名称。

返回类型:

已保存的对象。

start_run()

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

返回类型:

一个正在运行的活动对象（例如 mlflow.ActiveRun 对象）。

end_run()

结束一个活跃的 Recorder。

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 中存储的相对路径。

返回类型:

被存储的产物信息列表（名称、路径等）。

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

从一次运行中下载一个产物文件或目录到本地目录（如适用），并返回其本地路径。

参数:

  • path (str) – 所需产物的相对源路径。

  • dst_path (可选[str]) – 要下载指定产物的本地文件系统目标目录的绝对路径。该目录必须已存在。如果未指定，产物将被下载到本地文件系统上一个新创建的、唯一命名的目录中。

返回:

所需产物的本地路径。

返回类型:

str

list_metrics()

列出记录器的所有指标。

返回类型:

正在存储的指标字典。

list_params()

列出记录器的所有参数。

返回类型:

正在存储的参数字典。

list_tags()

列出记录器的所有标签。

返回类型:

正在存储的标签字典。

有关其他接口，如 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：此类用于生成 回测 的结果。有关 回测 的详细信息以及可用的 策略，请参阅 策略 和 回测。

以下是 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 模板 API。

已知限制

  • Python 对象基于 pickle 保存，当序列化对象的环境与反序列化对象的环境不同时，可能会出现问题。